Merge branch '26_1' into issue-4222_26_1

Author: GoodDayForSurf

apps/demos/Demos/DataGrid/AIAssistant/description.md

@@ -1,18 +1,29 @@
-With our v26.1 release, we will extend the AI-powered capabilities of both the DevExtreme [DataGrid](https://js.devexpress.com/Documentation/Guide/UI_Components/DataGrid/Overview/) and [TreeList](https://js.devexpress.com/Documentation/Guide/UI_Components/TreeList/Overview/). We plan to introduce a DevExtreme Chat-based AI assistant that will allow you to use natural language to interact with DataGrid/TreeList. The DataGrid/TreeList AI assistant will be able to complete the following actions:
-* Sort, filter, search, and group data.
-* Resize, reorder, fix/unfix, and show/hide columns.
-* Change pagination settings.
-<!--split-->
+The AI Assistant for the DevExtreme [DataGrid](/Documentation/Guide/UI_Components/DataGrid/Overview/) allows you to interact with the component using natural language. The Chat also supports [speech-to-text input](/Documentation/ApiReference/UI_Components/dxChat/Configuration/#speechToTextEnabled), ideal for hands-free interactions or entering longer prompts.
+
+You can use/configure the following DataGrid features in the AI Assistant Chat prompts:
 
-This feature is particularly well suited for the following usage scenarios:
+- [Filtering and Searching](/Documentation/Guide/UI_Components/DataGrid/Filtering_and_Searching/)
+- [Sorting](/Documentation/Guide/UI_Components/DataGrid/Sorting/)
+- [Grouping](/Documentation/Guide/UI_Components/DataGrid/Grouping/)
+- [Paging](/Documentation/Guide/UI_Components/DataGrid/Paging/)
+- [Focused Row](/Documentation/Guide/UI_Components/DataGrid/Focused_Row/)
+- [Selection](/Documentation/Guide/UI_Components/DataGrid/Selection/)
+- [Summaries](/Documentation/Guide/UI_Components/DataGrid/Summaries/Predefined_Aggregate_Functions/)
+- [Column Fixing](/Documentation/Guide/UI_Components/DataGrid/Columns/Column_Fixing/), [Resizing](/Documentation/Guide/UI_Components/DataGrid/Columns/Column_Sizing/), and [Reordering](/Documentation/Guide/UI_Components/DataGrid/Columns/Column_Reordering/)
+
+The AI Assistant feature is also available for the DevExtreme [TreeList](/Documentation/ApiReference/UI_Components/dxTreeList/Configuration/#aiAssistant) component.
+<!--split-->
 
-* **Large Datasets**: Use the power of AI to browse large data sets. Apply complex filter values with natural language.
+In this demo, the AI Assistant is enabled for a DataGrid that displays mock sales data with over 1500 records.
 
+[note]
 
-* **Complex Grid Configurations**: Allow users to specify complex display preferences quickly.
+AI services used for this demo have been rate and data limited. As such, you may experience performance-related delays when exploring the capabilities of the DataGrid AI Assistant.
 
+When connected to your own AI model/service without rate and data limits, the AI Assistant will perform seamlessly, without artificial delays. Note that DevExtreme does not offer an AI REST API and does not ship any built-in LLMs/SLMs.
 
-* **Accessibility-first Applications**: Allow users to interact with your application in a manner that is most appropriate for each specific situation: while at their desk, or on the go (when their hands are busy and they require voice commands to interact with your app).
+[/note]
 
+To enable the AI Assistant, configure the [aiIntegration](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#aiIntegration) or **aiAssistant**.[aiIntegration](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/aiAssistant/#aiIntegration) object and set the **aiAssistant**.[enabled](/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/aiAssistant/#enabled) property to `true`. Once activated, the DataGrid adds a predefined item (*"aiAssistantButton"*) to the toolbar. This button opens the AI Assistant Chat in a draggable pop-up window.
 
-* **Replicable Configurations**: Apply the same prompt to recreate complex grid configurations across sessions. Reduce time spent on tedious layout adjustments.
+This demo also configures [suggestions](/Documentation/ApiReference/UI_Components/dxChat/Configuration/#suggestions) for the AI Assistant Chat. These buttons allow you to interact with the assistant in one click using predefined prompts. For additional information about suggestions, refer to the following demo: [DevExtreme Chat - Prompt Suggestions](/Demos/WidgetsGallery/Demo/Chat/PromptSuggestions/).

packages/devextreme/js/__internal/core/ai_integration/templates/index.ts

@@ -42,8 +42,7 @@ export const templates: PromptTemplates = {
     user: 'User prompt text: {{text}}. Dataset: {{data}}.',
   },
   executeGridAssistant: {
-    // TODO: Implement system prompt when grid operations are ready
-    system: 'You are a helpful AI assistant for a data grid component. The user sends a natural language request describing an operation on the grid (e.g., sorting, filtering, grouping). You receive the user\'s message, a context object describing the current grid state, and a JSON schema describing the available commands and their arguments. Your task is to interpret the user\'s request and return a JSON object with one field: "actions" — an array of command objects, each with "name" (the command name) and "args" (an object of arguments matching the schema). Output must be a valid JSON string, directly parsable by JSON.parse. Do not include any markdown, formatting, or extra text — only the raw JSON object.',
+    system: 'You are a helpful AI assistant for a data grid component. The user sends a natural language request describing an operation on the grid (e.g., sorting, filtering, grouping). You receive the user\'s message, a context object describing the current grid state, and a JSON schema describing the available commands and their arguments. Your task is to interpret the user\'s request and return a JSON object with one field: "actions" — an array of command objects, each with "name" (the command name) and "args" (an object of arguments matching the schema). Output must be a valid JSON string, directly parsable by JSON.parse. Do not include any markdown, formatting, or extra text — only the raw JSON object.\n\nCRITICAL RULE FOR OPTIONAL ARGUMENTS: If an optional argument is not used, the field MUST be ENTIRELY ABSENT from the JSON object — the key must not appear at all. NEVER emit an optional field with value null, empty string "", empty array [], or any placeholder. This rule overrides any instinct to "complete" the object — omitted IS the value.',
     user: 'User request: {{text}}. Grid context: {{context}}.',
   },
 };

packages/devextreme/js/__internal/grids/data_grid/ai_assistant/commands/__tests__/summary.test.ts

@@ -57,6 +57,7 @@ describe('summaryCommand', () => {
     ])('accepts summaryType "%s"', (summaryType) => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType }],
+        groupItems: [],
       }).success).toBe(true);
     });
 
@@ -67,41 +68,59 @@ describe('summaryCommand', () => {
       }).success).toBe(true);
     });
 
-    it('accepts empty object (executability layer rejects it)', () => {
-      expect(summaryCommand.schema.safeParse({}).success).toBe(true);
+    it('rejects empty object (totalItems and groupItems are required)', () => {
+      expect(summaryCommand.schema.safeParse({}).success).toBe(false);
+    });
+
+    it('rejects when totalItems is omitted', () => {
+      expect(summaryCommand.schema.safeParse({
+        groupItems: [{ column: 'amount', summaryType: 'avg' }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when groupItems is omitted', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{ column: 'amount', summaryType: 'sum' }],
+      }).success).toBe(false);
     });
 
     it('rejects an unknown summaryType (including "custom")', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'custom' }],
+        groupItems: [],
       }).success).toBe(false);
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'median' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when an item is missing column', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ summaryType: 'sum' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when an item is missing summaryType', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount' }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects unknown properties on the root', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
         extra: 1,
       }).success).toBe(false);
     });
 
     it('rejects unknown properties on the item', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', extra: 1 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
@@ -113,11 +132,13 @@ describe('summaryCommand', () => {
           showInColumn: 'name',
           displayFormat: 'Sum: {0}',
         }],
+        groupItems: [],
       }).success).toBe(true);
     });
 
     it('accepts showInColumn, displayFormat, showInGroupFooter, alignByColumn on groupItems', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{
           column: 'amount',
           summaryType: 'avg',
@@ -136,6 +157,7 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           showInGroupFooter: true,
         }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
@@ -146,47 +168,41 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           alignByColumn: true,
         }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when showInColumn is not a string', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', showInColumn: 1 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when displayFormat is not a string', () => {
       expect(summaryCommand.schema.safeParse({
         totalItems: [{ column: 'amount', summaryType: 'sum', displayFormat: 5 }],
+        groupItems: [],
       }).success).toBe(false);
     });
 
     it('rejects when showInGroupFooter is not a boolean', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'sum', showInGroupFooter: 'yes' }],
       }).success).toBe(false);
     });
 
     it('rejects when alignByColumn is not a boolean', () => {
       expect(summaryCommand.schema.safeParse({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'sum', alignByColumn: 1 }],
       }).success).toBe(false);
     });
   });
 
   describe('execute', () => {
-    it('returns failure when both totalItems and groupItems are empty/omitted', async () => {
-      const instance = await createGrid();
-      const optionSpy = jest.spyOn(instance, 'option');
-      const callbacks = createCallbacks();
-
-      const result = await summaryCommand.execute(instance, callbacks)({});
-
-      expect(result.status).toBe('failure');
-      expect(optionSpy).not.toHaveBeenCalledWith('summary', expect.anything());
-    });
-
-    it('returns failure when both arrays are explicitly empty', async () => {
+    it('returns failure when both arrays are empty', async () => {
       const instance = await createGrid();
       const optionSpy = jest.spyOn(instance, 'option');
       const callbacks = createCallbacks();
@@ -210,6 +226,7 @@ describe('summaryCommand', () => {
           { column: 'amount', summaryType: 'sum' },
           { column: 'unknown', summaryType: 'avg' },
         ],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -222,6 +239,7 @@ describe('summaryCommand', () => {
       const callbacks = createCallbacks();
 
       const result = await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
         groupItems: [{ column: 'unknown', summaryType: 'sum' }],
       });
 
@@ -240,6 +258,7 @@ describe('summaryCommand', () => {
           summaryType: 'sum',
           showInColumn: 'unknown',
         }],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -263,21 +282,6 @@ describe('summaryCommand', () => {
       expect(result.status).toBe('success');
     });
 
-    it('passes empty arrays when one of the inputs is omitted', async () => {
-      const instance = await createGrid();
-      const optionSpy = jest.spyOn(instance, 'option');
-      const callbacks = createCallbacks();
-
-      await summaryCommand.execute(instance, callbacks)({
-        totalItems: [{ column: 'amount', summaryType: 'sum' }],
-      });
-
-      expect(optionSpy).toHaveBeenCalledWith('summary', {
-        totalItems: [{ column: 'amount', summaryType: 'sum' }],
-        groupItems: [],
-      });
-    });
-
     it('returns failure when option throws', async () => {
       const instance = await createGrid();
       const realOption = instance.option.bind(instance);
@@ -291,6 +295,7 @@ describe('summaryCommand', () => {
 
       const result = await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(result.status).toBe('failure');
@@ -304,6 +309,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -316,6 +322,7 @@ describe('summaryCommand', () => {
       const callbacks = createCallbacks();
 
       await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
         groupItems: [{ column: 'amount', summaryType: 'avg' }],
       });
 
@@ -336,6 +343,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'amount', summaryType: summaryType as 'sum' | 'min' | 'max' | 'avg' | 'count' }],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -349,6 +357,7 @@ describe('summaryCommand', () => {
 
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'name', summaryType: 'count' }],
+        groupItems: [],
       });
 
       // 'name' has no explicit caption — DevExtreme auto-derives "Name"
@@ -366,6 +375,7 @@ describe('summaryCommand', () => {
           { column: 'amount', summaryType: 'sum' },
           { column: 'amount', summaryType: 'avg' },
         ],
+        groupItems: [],
       });
 
       expect(callbacks.success).toHaveBeenCalledWith(
@@ -391,7 +401,10 @@ describe('summaryCommand', () => {
       const instance = await createGrid();
       const callbacks = createCallbacks();
 
-      await summaryCommand.execute(instance, callbacks)({});
+      await summaryCommand.execute(instance, callbacks)({
+        totalItems: [],
+        groupItems: [],
+      });
 
       expect(callbacks.failure).toHaveBeenCalledWith('Display data summaries.');
     });
@@ -403,6 +416,7 @@ describe('summaryCommand', () => {
       // Single item with unresolved column → failure path, item-list message
       await summaryCommand.execute(instance, callbacks)({
         totalItems: [{ column: 'unknown', summaryType: 'sum' }],
+        groupItems: [],
       });
 
       expect(callbacks.failure).toHaveBeenCalledWith(
@@ -427,16 +441,16 @@ describe('clearSummaryCommand', () => {
   });
 
   describe('execute', () => {
-    it('calls component.option("summary", { groupItems: undefined, totalItems: undefined }) on success', async () => {
+    it('calls component.option("summary", { groupItems: [], totalItems: [] }) on success', async () => {
       const instance = await createGrid();
       const optionSpy = jest.spyOn(instance, 'option');
       const callbacks = createCallbacks();
 
       const result = await clearSummaryCommand.execute(instance, callbacks)();
 
       expect(optionSpy).toHaveBeenCalledWith('summary', {
-        groupItems: undefined,
-        totalItems: undefined,
+        groupItems: [],
+        totalItems: [],
       });
       expect(result.status).toBe('success');
     });