feat(react-sdk): implement useAISearch hook for AI search state management (dotCMS#33851)

## Summary

This PR implements the `useAISearch` React hook for managing AI search
state in React applications and improves the AI search API response
structure for better developer experience.

### Key Changes

#### 1. New `useAISearch` React Hook
(`libs/sdk/react/src/lib/next/hooks/useAISearch.ts`)
- **State Management**: Manages AI search lifecycle with `idle`,
`loading`, `success`, and `error` states
- **Type-Safe**: Full TypeScript support with generic content type
parameter
- **API Integration**: Seamlessly integrates with the dotCMS client AI
search API
- **Exposed Methods**:
- `search(prompt: string)` - Executes AI search with the provided prompt
  - `reset()` - Resets search state to idle
- **Return Values**:
  - `response` - Full AI search response with metadata
  - `results` - Direct access to content results array
  - `status` - Current operation status with error details

#### 2. API Response Refactoring
- **Breaking Change**: Renamed `dotCMSResults` → `results` in
`DotCMSAISearchResponse`
- **Rationale**: More intuitive naming convention aligned with modern
API design
- **Internal Transformation**: Client SDK now transforms raw API
response to user-facing format
- **New Internal Type**: `DotCMSAISearchRawResponse` for backend
compatibility
- **Updated**: All documentation and examples in README.md

#### 3. Content Drive Improvements (Merged from dotCMS#33764)
- **Enhanced Error Handling**: Upload failures now show specific error
messages from API response
- **UI Fix**: Toolbar grid layout adjusted to properly accommodate
search input (2 columns + flexible space)
- **Code Cleanup**: Removed unnecessary path state updates and unused
test cases in sidebar store

#### 4. Type System Enhancements
- **New Generic Status Type**: `DotCMSEntityStatus` for consistent state
management patterns
- **Internal Types Export**: Added `internal.ts` exports for AI types to
support SDK implementation
- **Enhanced Type Safety**: Better type inference for AI search
responses

### Files Changed

**Core Implementation:**
- `libs/sdk/react/src/lib/next/hooks/useAISearch.ts` - New React hook
- `libs/sdk/react/src/lib/next/shared/types.ts` - Type definitions
- `libs/sdk/react/src/index.ts` - Public API exports

**API Layer:**
- `libs/sdk/client/src/lib/client/ai/search/search.ts` - Response
transformation
- `libs/sdk/types/src/lib/ai/public.ts` - Public API types
- `libs/sdk/types/src/lib/ai/internal.ts` - Internal types
- `libs/sdk/types/src/lib/components/generic/public.ts` - Shared status
type

**Documentation:**
- `libs/sdk/client/README.md` - Comprehensive examples and usage

**Content Drive:**
-
`libs/portlets/dot-content-drive/portlet/src/lib/dot-content-drive-shell/dot-content-drive-shell.component.ts`
-
`libs/portlets/dot-content-drive/portlet/src/lib/components/dot-content-drive-toolbar/dot-content-drive-toolbar.component.scss`
-
`libs/portlets/dot-content-drive/portlet/src/lib/store/features/sidebar/withSidebar.ts`

## Test Plan

- [ ] Verify `useAISearch` hook properly manages state transitions (idle
→ loading → success/error)
- [ ] Test AI search with various prompts and configuration options
- [ ] Confirm `results` property contains expected content data
- [ ] Validate error handling when search fails
- [ ] Test `reset()` functionality returns to idle state
- [ ] Verify TypeScript types are correctly inferred for custom content
types
- [ ] Check Content Drive upload error messages display correctly
- [ ] Validate toolbar layout renders properly across different screen
sizes
- [ ] Run existing AI search tests to ensure backward compatibility in
SDK client
- [ ] Verify documentation examples work as expected

## Breaking Changes

⚠️ **API Response Property Renamed**:
`DotCMSAISearchResponse.dotCMSResults` →
`DotCMSAISearchResponse.results`

**Migration Guide:**
```typescript
// Before
const response = await client.ai.search('query', 'index');
response.dotCMSResults.forEach(item => console.log(item));

// After
const response = await client.ai.search('query', 'index');
response.results.forEach(item => console.log(item));
```

This PR fixes: dotCMS#33850

Author: zJaaal

core-web/libs/portlets/dot-content-drive/portlet/src/lib/components/dot-content-drive-toolbar/dot-content-drive-toolbar.component.scss

@@ -59,8 +59,7 @@
     width: 100%;
     grid-area: toolbar-group-top;
 
-    grid-template-columns: repeat(3, minmax(4.5rem, 14rem));
-
+    grid-template-columns: repeat(2, minmax(4.5rem, 14rem)) 1fr;
     .search-input {
         grid-column: 1 / 3;
     }

core-web/libs/portlets/dot-content-drive/portlet/src/lib/dot-content-drive-shell/dot-content-drive-shell.component.spec.ts

@@ -655,6 +655,46 @@ describe('DotContentDriveShellComponent', () => {
             });
         });
 
+        it('should show error message on upload failure with errors', () => {
+            const error = {
+                error: {
+                    errors: [{ message: 'Upload failed' }]
+                }
+            };
+            uploadService.uploadDotAsset.mockReturnValue(throwError(() => error));
+            store.selectedNode.mockReturnValue({
+                ...ALL_FOLDER,
+                data: {
+                    hostname: MOCK_SITES[0].hostname,
+                    path: '',
+                    type: 'folder',
+                    id: MOCK_SITES[0].identifier
+                }
+            });
+            const addSpy = jest.spyOn(messageService, 'add');
+
+            const fileInput = spectator.query('input[type="file"]') as HTMLInputElement;
+            Object.defineProperty(fileInput, 'files', {
+                value: [mockFile],
+                writable: false
+            });
+
+            spectator.triggerEventHandler('input[type="file"]', 'change', { target: fileInput });
+
+            expect(addSpy).toHaveBeenCalledTimes(2);
+            expect(addSpy).toHaveBeenNthCalledWith(1, {
+                severity: 'info',
+                summary: 'content-drive.file-upload-in-progress',
+                detail: 'content-drive.file-upload-in-progress-detail'
+            });
+            expect(addSpy).toHaveBeenNthCalledWith(2, {
+                severity: 'error',
+                summary: 'content-drive.add-dotasset-error',
+                detail: 'content-drive.add-dotasset-error-detail',
+                life: ERROR_MESSAGE_LIFE
+            });
+        });
+
         it('should not upload when no files are selected', () => {
             const fileInput = spectator.query('input[type="file"]') as HTMLInputElement;
             Object.defineProperty(fileInput, 'files', {

core-web/libs/portlets/dot-content-drive/portlet/src/lib/dot-content-drive-shell/dot-content-drive-shell.component.ts

@@ -371,9 +371,9 @@ export class DotContentDriveShellComponent {
                     this.#messageService.add({
                         severity: 'error',
                         summary: this.#dotMessageService.get('content-drive.add-dotasset-error'),
-                        detail: this.#dotMessageService.get(
-                            'content-drive.add-dotasset-error-detail'
-                        ),
+                        detail:
+                            error.error?.errors?.[0]?.message ??
+                            this.#dotMessageService.get('content-drive.add-dotasset-error-detail'),
                         life: ERROR_MESSAGE_LIFE
                     });
                 }

core-web/libs/portlets/dot-content-drive/portlet/src/lib/store/features/sidebar/withSidebar.spec.ts

@@ -215,28 +215,6 @@ describe('withSidebar', () => {
                 // Verify the service was not called since node has children
                 expect(folderService.getFolders).not.toHaveBeenCalled();
             });
-
-            it('should update the store path when loadChildFolders is called', (done) => {
-                const testPath = '/documents/images/';
-                const host = 'demo.dotcms.com';
-
-                // Check initial path
-                const initialPath = store.path();
-                expect(initialPath).toBe('/test/path'); // From initialState
-
-                folderService.getFolders.mockReturnValue(of(mockFolders));
-
-                store.loadChildFolders(testPath, host).subscribe((result) => {
-                    // Verify the path was updated in the store
-                    expect(store.path()).toBe(testPath);
-                    expect(store.path()).not.toBe(initialPath);
-
-                    // Also verify the service was called and returned expected data
-                    expect(result.parent).toEqual(mockFolders[0]);
-                    expect(result.folders).toHaveLength(2);
-                    done();
-                });
-            });
         });
 
         describe('setSelectedNode', () => {

core-web/libs/portlets/dot-content-drive/portlet/src/lib/store/features/sidebar/withSidebar.ts

@@ -10,7 +10,7 @@ import { Observable, of } from 'rxjs';
 
 import { inject } from '@angular/core';
 
-import { catchError, take, tap } from 'rxjs/operators';
+import { catchError, take } from 'rxjs/operators';
 
 import { DotFolderService } from '@dotcms/data-access';
 import { DotFolder } from '@dotcms/dotcms-models';
@@ -98,9 +98,7 @@ export function withSidebar() {
                 const host = hostname || store.currentSite()?.hostname;
                 const fullPath = `${host}${path}`;
 
-                return getFolderNodesByPath(fullPath, dotFolderService).pipe(
-                    tap(() => patchState(store, { path }))
-                );
+                return getFolderNodesByPath(fullPath, dotFolderService);
             },
             /**
              * Sets the selected node

core-web/libs/sdk/client/README.md

@@ -241,17 +241,17 @@ Before using AI-powered search, ensure your dotCMS instance is properly configur
 #### Basic AI Search
 ```typescript
 // Search for content semantically related to your query
-const results = await client.ai.search(
+const response = await client.ai.search(
     'articles about machine learning',
     'content_index'
 );
-console.log(results.dotCMSResults);
+console.log(response.results);
 ```
 
 #### Customizing Search Parameters
 ```typescript
 // Fine-tune search with query parameters
-const results = await client.ai.search(
+const response = await client.ai.search(
     'artificial intelligence tutorials',
     'content_index',
     {
@@ -270,7 +270,7 @@ const results = await client.ai.search(
 import { DISTANCE_FUNCTIONS } from '@dotcms/types';
 
 // Customize AI search behavior with threshold and distance function
-const results = await client.ai.search(
+const response = await client.ai.search(
     'deep learning concepts',
     'content_index',
     {
@@ -286,7 +286,7 @@ const results = await client.ai.search(
 #### Complete Example with All Options
 ```typescript
 // Combine query and AI parameters for precise control
-const results = await client.ai.search(
+const response = await client.ai.search(
     'best practices for content management',
     'articles_index',
     {
@@ -306,7 +306,7 @@ const results = await client.ai.search(
 );
 
 // Access results with match scores
-results.dotCMSResults.forEach(result => {
+resp[onse].results.forEach(result => {
     console.log(result.title);
     console.log('Matches:', result.matches); // Distance and extracted text
 });
@@ -416,7 +416,7 @@ interface Article extends DotCMSBasicContentlet {
 }
 
 // Type-safe AI search
-const results: DotCMSAISearchResponse<Article> = await client.ai.search<Article>(
+const response: DotCMSAISearchResponse<Article> = await client.ai.search<Article>(
     'machine learning tutorials',
     'content_index',
     {
@@ -432,7 +432,7 @@ const results: DotCMSAISearchResponse<Article> = await client.ai.search<Article>
 );
 
 // Access typed results with match information
-results.dotCMSResults.forEach(article => {
+response.results.forEach(article => {
     console.log(article.title);           // ✅ Type-safe: string
     console.log(article.category);        // ✅ Type-safe: string
 
@@ -818,7 +818,7 @@ search<T extends DotCMSBasicContentlet>(
 
 ```typescript
 interface DotCMSAISearchResponse<T> {
-    dotCMSResults: Array<T & {
+    results: Array<T & {
         matches?: Array<{
             distance: number;      // Similarity score
             extractedText: string; // Matched text excerpt
@@ -867,9 +867,9 @@ client.ai.search(
         query: { limit: 10 },
         config: { threshold: 0.8 }
     }
-).then((results) => {
-    console.log('Found:', results.dotCMSResults.length);
-    return results;
+).then((response) => {
+    console.log('Found:', response.results.length);
+    return response;
 }).catch((error) => {
     console.error('Search failed:', error.message);
 });

core-web/libs/sdk/client/src/lib/client/ai/ai-api.ts

@@ -60,7 +60,7 @@ export class AIClient extends BaseApiClient {
      * @example
      * @example
      * ```typescript
-     * const results = await client.ai.search('machine learning articles', 'content_index', {
+     * const response = await client.ai.search('machine learning articles', 'content_index', {
      *   query: {
      *     limit: 20,
      *     contentType: 'BlogPost',
@@ -83,8 +83,8 @@ export class AIClient extends BaseApiClient {
      *     threshold: 0.7,
      *     distanceFunction: DISTANCE_FUNCTIONS.cosine
      *   }
-     * }).then((results) => {
-     *   console.log(results);
+     * }).then((response) => {
+     *   console.log(response.results);
      * }).catch((error) => {
      *   console.error(error);
      * });

core-web/libs/sdk/client/src/lib/client/ai/search/search.spec.ts

@@ -10,6 +10,7 @@ import {
     DISTANCE_FUNCTIONS,
     DotCMSAISearchResponse
 } from '@dotcms/types';
+import { DotCMSAISearchRawResponse } from '@dotcms/types/internal';
 
 import { AISearch } from './search';
 
@@ -37,7 +38,15 @@ describe('AISearch', () => {
         ...requestOptions
     };
 
-    const mockResponseData: DotCMSAISearchResponse<DotCMSBasicContentlet> = {
+    const mockResponseDataRaw: DotCMSAISearchRawResponse<DotCMSBasicContentlet> = {
+        timeToEmbeddings: 1000,
+        total: 1,
+        query: 'test query',
+        threshold: 0.5,
+        operator: DISTANCE_FUNCTIONS.cosine,
+        offset: 0,
+        limit: 1000,
+        count: 1,
         dotCMSResults: [
             {
                 identifier: '123',
@@ -73,6 +82,11 @@ describe('AISearch', () => {
         ]
     };
 
+    const mockResponseData: DotCMSAISearchResponse<DotCMSBasicContentlet> = {
+        ...mockResponseDataRaw,
+        results: mockResponseDataRaw.dotCMSResults
+    };
+
     beforeEach(() => {
         mockRequest.mockReset();
         MockedFetchHttpClient.mockImplementation(
@@ -82,7 +96,7 @@ describe('AISearch', () => {
                 }) as Partial<FetchHttpClient> as FetchHttpClient
         );
 
-        mockRequest.mockResolvedValue(mockResponseData);
+        mockRequest.mockResolvedValue(mockResponseDataRaw);
     });
 
     it('should initialize with valid configuration', () => {
@@ -151,8 +165,8 @@ describe('AISearch', () => {
             const response = await aiSearch;
 
             expect(response).toEqual(mockResponseData);
-            expect(response.dotCMSResults).toHaveLength(1);
-            expect(response.dotCMSResults[0].title).toBe('Test Content');
+            expect(response.results).toHaveLength(1);
+            expect(response.results[0].title).toBe('Test Content');
         });
 
         it('should build a query with custom query parameters', async () => {

core-web/libs/sdk/client/src/lib/client/ai/search/search.ts

@@ -10,6 +10,7 @@ import {
     DotRequestOptions,
     DotCMSAISearchResponse
 } from '@dotcms/types';
+import { DotCMSAISearchRawResponse } from '@dotcms/types/internal';
 
 import { appendMappedParams } from '../../../utils/params/utils';
 import { BaseApiClient } from '../../base/base-api';
@@ -87,13 +88,18 @@ export class AISearch<T extends DotCMSBasicContentlet> extends BaseApiClient {
     ): Promise<DotCMSAISearchResponse<T> | DotErrorAISearch> {
         return this.fetch<T>().then(
             (data) => {
+                const response: DotCMSAISearchResponse<T> = {
+                    ...data,
+                    results: data.dotCMSResults
+                };
                 if (typeof onfulfilled === 'function') {
-                    const result = onfulfilled(data);
-                    // Ensure we always return a value, fallback to formattedResponse if callback returns undefined
-                    return result ?? data;
+                    const result = onfulfilled(response);
+                    // Ensure we always return a value, fallback to data if callback returns undefined
+
+                    return result ?? response;
                 }
 
-                return data;
+                return response;
             },
             (error: unknown) => {
                 // Wrap error in DotCMSContentError
@@ -130,12 +136,12 @@ export class AISearch<T extends DotCMSBasicContentlet> extends BaseApiClient {
         );
     }
 
-    private fetch<T extends DotCMSBasicContentlet>(): Promise<DotCMSAISearchResponse<T>> {
+    private fetch<T extends DotCMSBasicContentlet>(): Promise<DotCMSAISearchRawResponse<T>> {
         const searchParams = this.buildSearchParams(this.#prompt, this.#params);
         const url = new URL('/api/v1/ai/search', this.dotcmsUrl);
         url.search = searchParams.toString();
 
-        return this.httpClient.request<DotCMSAISearchResponse<T>>(url.toString(), {
+        return this.httpClient.request<DotCMSAISearchRawResponse<T>>(url.toString(), {
             ...this.requestOptions,
             headers: {
                 ...this.requestOptions.headers