GridCommands: support optional properties for summary

Author: anna-shakhova

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

@@ -104,6 +104,74 @@ describe('summaryCommand', () => {
         totalItems: [{ column: 'amount', summaryType: 'sum', extra: 1 }],
       }).success).toBe(false);
     });
+
+    it('accepts showInColumn and displayFormat on totalItems', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{
+          column: 'amount',
+          summaryType: 'sum',
+          showInColumn: 'name',
+          displayFormat: 'Sum: {0}',
+        }],
+      }).success).toBe(true);
+    });
+
+    it('accepts showInColumn, displayFormat, showInGroupFooter, alignByColumn on groupItems', () => {
+      expect(summaryCommand.schema.safeParse({
+        groupItems: [{
+          column: 'amount',
+          summaryType: 'avg',
+          showInColumn: 'name',
+          displayFormat: '{1}: {0}',
+          showInGroupFooter: true,
+          alignByColumn: true,
+        }],
+      }).success).toBe(true);
+    });
+
+    it('rejects showInGroupFooter on totalItems (group-only field)', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{
+          column: 'amount',
+          summaryType: 'sum',
+          showInGroupFooter: true,
+        }],
+      }).success).toBe(false);
+    });
+
+    it('rejects alignByColumn on totalItems (group-only field)', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{
+          column: 'amount',
+          summaryType: 'sum',
+          alignByColumn: true,
+        }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when showInColumn is not a string', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{ column: 'amount', summaryType: 'sum', showInColumn: 1 }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when displayFormat is not a string', () => {
+      expect(summaryCommand.schema.safeParse({
+        totalItems: [{ column: 'amount', summaryType: 'sum', displayFormat: 5 }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when showInGroupFooter is not a boolean', () => {
+      expect(summaryCommand.schema.safeParse({
+        groupItems: [{ column: 'amount', summaryType: 'sum', showInGroupFooter: 'yes' }],
+      }).success).toBe(false);
+    });
+
+    it('rejects when alignByColumn is not a boolean', () => {
+      expect(summaryCommand.schema.safeParse({
+        groupItems: [{ column: 'amount', summaryType: 'sum', alignByColumn: 1 }],
+      }).success).toBe(false);
+    });
   });
 
   describe('execute', () => {
@@ -161,6 +229,23 @@ describe('summaryCommand', () => {
       expect(optionSpy).not.toHaveBeenCalledWith('summary', expect.anything());
     });
 
+    it('returns failure when showInColumn does not resolve to an existing column', async () => {
+      const instance = await createGrid();
+      const optionSpy = jest.spyOn(instance, 'option');
+      const callbacks = createCallbacks();
+
+      const result = await summaryCommand.execute(instance, callbacks)({
+        totalItems: [{
+          column: 'amount',
+          summaryType: 'sum',
+          showInColumn: 'unknown',
+        }],
+      });
+
+      expect(result.status).toBe('failure');
+      expect(optionSpy).not.toHaveBeenCalledWith('summary', expect.anything());
+    });
+
     it('calls component.option("summary", { totalItems, groupItems }) on success', async () => {
       const instance = await createGrid();
       const optionSpy = jest.spyOn(instance, 'option');

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

@@ -7,17 +7,29 @@ import type { Column } from './types';
 
 const SUMMARY_TYPES = ['sum', 'min', 'max', 'avg', 'count'] as const satisfies readonly SummaryType[];
 
-const summaryItemSchema = z.object({
+const summaryItemBaseShape = {
   column: z.string(),
   summaryType: z.enum(SUMMARY_TYPES),
+  showInColumn: z.string().optional(),
+  displayFormat: z.string().optional(),
+};
+
+const totalItemSchema = z.object(summaryItemBaseShape).strict();
+
+const groupItemSchema = z.object({
+  ...summaryItemBaseShape,
+  showInGroupFooter: z.boolean().optional(),
+  alignByColumn: z.boolean().optional(),
 }).strict();
 
 const summaryCommandSchema = z.object({
-  totalItems: z.array(summaryItemSchema).optional(),
-  groupItems: z.array(summaryItemSchema).optional(),
+  totalItems: z.array(totalItemSchema).optional(),
+  groupItems: z.array(groupItemSchema).optional(),
 }).strict();
 
-type SummaryItem = z.infer<typeof summaryItemSchema>;
+type TotalItem = z.infer<typeof totalItemSchema>;
+type GroupItem = z.infer<typeof groupItemSchema>;
+type SummaryItem = TotalItem | GroupItem;
 
 const SUMMARY_TYPE_LABELS: Record<SummaryItem['summaryType'], string> = {
   sum: 'sum',
@@ -57,7 +69,15 @@ const buildDefaultMessage = (
 
 export const summaryCommand = defineGridCommand({
   name: 'summary',
-  description: 'Configure column summaries. totalItems aggregate the entire data set; groupItems aggregate within each group. Provide at least one item across the two arrays — use clearSummary to remove all summaries. Replaces existing summaries entirely; pre-merge with the grid\'s current summary items if you intend to add rather than replace.',
+  description: 'Configure column summaries. totalItems aggregate the entire data set; groupItems aggregate within each group. Provide at least one item across the two arrays — use clearSummary to remove all summaries. Replaces existing summaries entirely; pre-merge with the grid\'s current summary items if you intend to add rather than replace.\n'
+    + 'Each item supports:\n'
+    + '- column (required): dataField of the column to aggregate.\n'
+    + '- summaryType (required): one of "sum", "min", "max", "avg", "count".\n'
+    + '- showInColumn (optional): dataField of the column under which the summary value is rendered. For totalItems, controls which column\'s footer cell shows the value. For groupItems, used when showInGroupFooter=true or alignByColumn=true to pick the column the value is shown under. Must match an existing column.\n'
+    + '- displayFormat (optional): format template for the rendered value. Placeholders: "{0}" — the formatted summary value; "{1}" — the parent column\'s caption (for group items only resolvable when showInColumn is specified). Example: "Sum: {0}" or "{1}: {0}".\n'
+    + 'Group items additionally support:\n'
+    + '- showInGroupFooter (optional, default false): render in the group footer instead of the group row.\n'
+    + '- alignByColumn (optional, default false): when false, group summary items are listed in parentheses after the group row header. When true, items are aligned by their columns within the group row.',
   schema: summaryCommandSchema,
   execute: (component, { success, failure }) => (args): Promise<CommandResult> => {
     const columnsController = component.getController('columns');
@@ -71,9 +91,17 @@ export const summaryCommand = defineGridCommand({
       return Promise.resolve(failure(defaultMessage));
     }
 
-    const allColumnsResolve = allItems.every(
-      (item) => columnsController.columnOption(item.column) !== undefined,
-    );
+    const allColumnsResolve = allItems.every((item) => {
+      if (columnsController.columnOption(item.column) === undefined) {
+        return false;
+      }
+
+      if (item.showInColumn !== undefined) {
+        return columnsController.columnOption(item.showInColumn) !== undefined;
+      }
+
+      return true;
+    });
 
     if (!allColumnsResolve) {
       return Promise.resolve(failure(defaultMessage));