GridCore: add sorting grid command (DevExpress#33444)

Author: anna-shakhova

packages/devextreme/eslint.config.mjs

@@ -403,6 +403,19 @@ export default [
             'spellcheck/spell-checker': 'off',
         },
     },
+    // Spellcheck overrides for ai_assistant (Zod dependency)
+    {
+        files: ['js/__internal/grids/grid_core/ai_assistant/**/*'],
+        rules: {
+            'spellcheck/spell-checker': ['error', {
+                ...spellCheckConfig[0].rules['spellcheck/spell-checker'][1],
+                skipWords: [
+                    ...spellCheckConfig[0].rules['spellcheck/spell-checker'][1].skipWords,
+                    'Zod',
+                ],
+            }],
+        },
+    },
     // Rules for js/__internal folder
     {
         files: ['js/__internal/**/*'],

packages/devextreme/js/__internal/grids/grid_core/ai_assistant/commands/__tests__/sorting.test.ts

@@ -0,0 +1,310 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from '@jest/globals';
+import type { Properties } from '@js/ui/data_grid';
+import type { CommandResult } from '@ts/grids/grid_core/ai_assistant/types';
+import type { InternalGrid } from '@ts/grids/grid_core/m_types';
+
+import {
+  afterTest,
+  beforeTest,
+  createDataGrid,
+} from '../../../__tests__/__mock__/helpers/utils';
+import { clearSortingCommand, sortingCommand } from '../sorting';
+
+const createCallbacks = (): {
+  success: jest.Mock<(message?: string) => CommandResult>;
+  failure: jest.Mock<(message?: string) => CommandResult>;
+} => ({
+  success: jest.fn((message?: string) => ({ status: 'success' as const, message: message ?? '' })),
+  failure: jest.fn((message?: string) => ({ status: 'failure' as const, message: message ?? '' })),
+});
+
+const createGrid = async (
+  options: Record<string, unknown> = {},
+): Promise<InternalGrid> => {
+  const { instance } = await createDataGrid({
+    dataSource: [
+      { id: 1, name: 'Alpha' },
+      { id: 2, name: 'Beta' },
+    ],
+    columns: [
+      { dataField: 'id', dataType: 'number' },
+      { dataField: 'name', caption: 'Full Name', dataType: 'string' },
+    ],
+    ...options,
+  } as unknown as Properties);
+  return instance as unknown as InternalGrid;
+};
+
+describe('sortingCommand', () => {
+  beforeEach(() => beforeTest());
+  afterEach(() => afterTest());
+
+  describe('schema', () => {
+    it.each([
+      ['asc'],
+      ['desc'],
+      ['none'],
+    ])('accepts valid args with sortOrder "%s"', (sortOrder) => {
+      expect(sortingCommand.schema.safeParse({
+        dataField: 'name',
+        sortOrder,
+      }).success).toBe(true);
+    });
+
+    it('rejects when dataField is missing', () => {
+      expect(sortingCommand.schema.safeParse({
+        sortOrder: 'asc',
+      }).success).toBe(false);
+    });
+
+    it('rejects when sortOrder is missing', () => {
+      expect(sortingCommand.schema.safeParse({
+        dataField: 'name',
+      }).success).toBe(false);
+    });
+
+    it('rejects when dataField is not a string', () => {
+      expect(sortingCommand.schema.safeParse({
+        dataField: 123,
+        sortOrder: 'asc',
+      }).success).toBe(false);
+    });
+
+    it('rejects when sortOrder is not in the enum', () => {
+      expect(sortingCommand.schema.safeParse({
+        dataField: 'name',
+        sortOrder: 'ascending',
+      }).success).toBe(false);
+    });
+
+    it('rejects unknown properties', () => {
+      expect(sortingCommand.schema.safeParse({
+        dataField: 'name',
+        sortOrder: 'asc',
+        extra: 1,
+      }).success).toBe(false);
+    });
+  });
+
+  describe('execute', () => {
+    it('returns failure and skips changeSortOrder when sorting.mode is "none"', async () => {
+      const instance = await createGrid({ sorting: { mode: 'none' } });
+      const columnsController = instance.getController('columns');
+      const spy = jest.spyOn(columnsController, 'changeSortOrder');
+      const callbacks = createCallbacks();
+
+      const result = await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      expect(result.status).toBe('failure');
+      expect(callbacks.success).not.toHaveBeenCalled();
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('returns failure and skips changeSortOrder when column.allowSorting is false', async () => {
+      const instance = await createGrid({
+        columns: [
+          { dataField: 'id', dataType: 'number' },
+          {
+            dataField: 'name', caption: 'Full Name', dataType: 'string', allowSorting: false,
+          },
+        ],
+      });
+      const columnsController = instance.getController('columns');
+      const spy = jest.spyOn(columnsController, 'changeSortOrder');
+      const callbacks = createCallbacks();
+
+      const result = await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      expect(result.status).toBe('failure');
+      expect(callbacks.success).not.toHaveBeenCalled();
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('returns failure and skips changeSortOrder when dataField does not match any column', async () => {
+      const instance = await createGrid();
+      const columnsController = instance.getController('columns');
+      const spy = jest.spyOn(columnsController, 'changeSortOrder');
+      const callbacks = createCallbacks();
+
+      const result = await sortingCommand.execute(instance, callbacks)({
+        dataField: 'unknown',
+        sortOrder: 'asc',
+      });
+
+      expect(result.status).toBe('failure');
+      expect(callbacks.success).not.toHaveBeenCalled();
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('calls columnsController.changeSortOrder(column.index, sortOrder) exactly once', async () => {
+      const instance = await createGrid();
+      const columnsController = instance.getController('columns');
+      const spy = jest.spyOn(columnsController, 'changeSortOrder');
+      const callbacks = createCallbacks();
+
+      const result = await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      const nameColumn = columnsController.columnOption('name') as { index: number };
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy).toHaveBeenCalledWith(nameColumn.index, 'asc');
+      expect(result.status).toBe('success');
+    });
+
+    it('returns failure when changeSortOrder throws', async () => {
+      const instance = await createGrid();
+      const columnsController = instance.getController('columns');
+      jest.spyOn(columnsController, 'changeSortOrder').mockImplementation(() => {
+        throw new Error('Error changing sort order');
+      });
+      const callbacks = createCallbacks();
+
+      const result = await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      expect(result.status).toBe('failure');
+    });
+  });
+
+  describe('default message', () => {
+    it('uses `Sort data against "[caption]" in ascending order.` for sortOrder "asc"', async () => {
+      const instance = await createGrid();
+      const callbacks = createCallbacks();
+
+      await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      expect(callbacks.success).toHaveBeenCalledWith(
+        'Sort data against "Full Name" in ascending order.',
+      );
+    });
+
+    it('uses `Sort data against "[caption]" in descending order.` for sortOrder "desc"', async () => {
+      const instance = await createGrid();
+      const callbacks = createCallbacks();
+
+      await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'desc',
+      });
+
+      expect(callbacks.success).toHaveBeenCalledWith(
+        'Sort data against "Full Name" in descending order.',
+      );
+    });
+
+    it('uses `Clear sorting against "[caption]".` for sortOrder "none"', async () => {
+      const instance = await createGrid();
+      const callbacks = createCallbacks();
+
+      await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'none',
+      });
+
+      expect(callbacks.success).toHaveBeenCalledWith(
+        'Clear sorting against "Full Name".',
+      );
+    });
+
+    it('passes the same default message to failure when executability fails', async () => {
+      const instance = await createGrid({ sorting: { mode: 'none' } });
+      const callbacks = createCallbacks();
+
+      await sortingCommand.execute(instance, callbacks)({
+        dataField: 'name',
+        sortOrder: 'asc',
+      });
+
+      expect(callbacks.failure).toHaveBeenCalledWith(
+        'Sort data against "Full Name" in ascending order.',
+      );
+    });
+
+    it('falls back to the raw dataField when no column matches', async () => {
+      const instance = await createGrid();
+      const callbacks = createCallbacks();
+
+      await sortingCommand.execute(instance, callbacks)({
+        dataField: 'unknown',
+        sortOrder: 'asc',
+      });
+
+      expect(callbacks.failure).toHaveBeenCalledWith(
+        'Sort data against "unknown" in ascending order.',
+      );
+    });
+  });
+});
+
+describe('clearSortingCommand', () => {
+  beforeEach(() => beforeTest());
+  afterEach(() => afterTest());
+
+  describe('schema', () => {
+    it('accepts an empty object', () => {
+      expect(clearSortingCommand.schema.safeParse({}).success).toBe(true);
+    });
+
+    it('rejects unknown properties', () => {
+      expect(clearSortingCommand.schema.safeParse({
+        extra: 1,
+      }).success).toBe(false);
+    });
+  });
+
+  describe('execute', () => {
+    it('calls grid instance clearSorting() exactly once', async () => {
+      const instance = await createGrid();
+      const spy = jest.spyOn(instance, 'clearSorting');
+      const callbacks = createCallbacks();
+
+      const result = await clearSortingCommand.execute(instance, callbacks)();
+
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(result.status).toBe('success');
+    });
+
+    it('returns failure when clearSorting throws', async () => {
+      const instance = await createGrid();
+      jest.spyOn(instance, 'clearSorting').mockImplementation(() => {
+        throw new Error('boom');
+      });
+      const callbacks = createCallbacks();
+
+      const result = await clearSortingCommand.execute(instance, callbacks)();
+
+      expect(result.status).toBe('failure');
+    });
+  });
+
+  describe('default message', () => {
+    it('uses the literal `Clear sorting.`', async () => {
+      const instance = await createGrid();
+      const callbacks = createCallbacks();
+
+      await clearSortingCommand.execute(instance, callbacks)();
+
+      expect(callbacks.success).toHaveBeenCalledWith('Clear sorting.');
+    });
+  });
+});

packages/devextreme/js/__internal/grids/grid_core/ai_assistant/commands/sorting.ts

@@ -0,0 +1,67 @@
+import type { GridCommand } from '@ts/grids/grid_core/ai_assistant/types';
+import type { Column } from '@ts/grids/grid_core/columns_controller/types';
+import { z } from 'zod';
+
+const sortingCommandSchema = z.object({
+  dataField: z.string(),
+  sortOrder: z.enum(['asc', 'desc', 'none']),
+}).strict();
+
+type SortingCommandArgs = z.infer<typeof sortingCommandSchema>;
+
+const getSortingDefaultMessage = (
+  args: SortingCommandArgs,
+  column: Column | undefined,
+): string => {
+  const columnName = column?.caption ?? args.dataField;
+
+  if (args.sortOrder === 'none') {
+    return `Clear sorting against "${columnName}".`;
+  }
+
+  const sortOrder = args.sortOrder === 'asc' ? 'ascending' : 'descending';
+
+  return `Sort data against "${columnName}" in ${sortOrder} order.`;
+};
+
+export const sortingCommand: GridCommand<SortingCommandArgs> = {
+  name: 'sorting',
+  description: 'Sort a column ascending, descending, or remove its sort',
+  schema: sortingCommandSchema,
+  execute: (component, { success, failure }) => (args) => {
+    const columnsController = component.getController('columns');
+    const column: Column | undefined = columnsController.columnOption(args.dataField);
+    const defaultMessage = getSortingDefaultMessage(args, column);
+
+    if (!column || !columnsController.allowColumnSorting(column)) {
+      return Promise.resolve(failure(defaultMessage));
+    }
+
+    try {
+      // Handles remote operations via data controller listening for the `sorting` change
+      columnsController.changeSortOrder(column.index, args.sortOrder);
+
+      return Promise.resolve(success(defaultMessage));
+    } catch {
+      return Promise.resolve(failure(defaultMessage));
+    }
+  },
+};
+
+export const clearSortingCommand: GridCommand = {
+  name: 'clearSorting',
+  description: 'Remove sorting from all columns',
+  schema: z.object({}).strict(),
+  execute: (component, { success, failure }) => () => {
+    const defaultMessage = 'Clear sorting.';
+
+    try {
+      // Handles remote operations via data controller listening for the `sorting` change
+      component.clearSorting();
+
+      return Promise.resolve(success(defaultMessage));
+    } catch {
+      return Promise.resolve(failure(defaultMessage));
+    }
+  },
+};