@opencorestack/opengridx 3.9.0 → 3.10.0

package/lib/hooks/core/useGridKeyboardNavigation.ts

@@ -1,22 +1,33 @@
-import { useState, useCallback, useMemo, useRef, useLayoutEffect } from 'react';
-import { getScrollStart, isRtl, logicalArrowKey, setScrollStart } from '../../utils/direction';
+import {
+    useState,
+    useCallback,
+    useMemo,
+    useRef,
+    useLayoutEffect,
+} from 'react';
+import { handleGridKeyDown } from './gridKeyDown';
+import { getScrollStart, setScrollStart } from '../../utils/direction';
 import { scrollRowIntoView } from '../../utils/scroll';
-import { resolveCellEditable } from '../../utils/editing';
-import { getCellValue } from '../../utils/values';
-import { isSyntheticRowId } from '../../utils/syntheticRows';
 import {
     CHECKBOX_FIELD,
     EXPAND_FIELD,
     REORDER_FIELD,
-    classifyKeyTarget,
     findFocusTarget,
     focusedCellFromElement,
     isSameCell,
     isSystemField,
 } from '../../utils/focus';
 import type { FocusedCell } from '../../utils/focus';
-import { isRangeColumnField } from '../../utils/cellSelection';
-import type { GridRowModel, GridRowId, GridColDef, GridCellParams, GridSortItem, GridSortDirection, GridRowParams, GridRowMeta } from '../../types';
+import type {
+    GridRowModel,
+    GridRowId,
+    GridColDef,
+    GridCellParams,
+    GridSortItem,
+    GridSortDirection,
+    GridRowParams,
+    GridRowMeta,
+} from '../../types';
 import type { GridEditingState } from '../features/useGridEditing';
 
 export type { FocusedCell } from '../../utils/focus';
@@ -44,7 +55,7 @@ export interface UseGridKeyboardNavigationParams<R extends GridRowModel> {
     /** Focusable columns in render order: system columns first, then the visible data columns. */
     navigationColumns: ReadonlyArray<NavigationColumn<R>>;
     checkboxSelection: boolean;
-    selectedRowIds: Set<GridRowId>;
+    selectedRowIds: ReadonlySet<GridRowId>;
     handleSelectionChange: (id: GridRowId, selected: boolean) => void;
     handleDetailPanelToggle: (id: GridRowId) => void;
     editingHandlers: {
@@ -133,8 +144,6 @@ export interface UseGridKeyboardNavigationReturn {
 
 const defaultGetRowId = <R extends GridRowModel>(row: R): GridRowId => row.id;
 
-const NAVIGATION_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown']);
-
 /** Keeps a stored focus position valid when its row or column is no longer rendered. */
 function resolveFocus<R extends GridRowModel>(
     cell: FocusedCell | null,
@@ -359,230 +368,37 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
     }, [setKeyboardMode]);
 
     const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
-        const viewport = event.currentTarget as HTMLElement;
-        const targetKind = classifyKeyTarget(event.target, viewport);
-        if (targetKind === 'foreign') return;
-        setKeyboardMode(true);
-
-        // While an IME is composing, Enter / Escape / arrows confirm or navigate candidates.
-        if (event.nativeEvent?.isComposing || event.keyCode === 229) return;
-
-        // In a right-to-left grid ArrowLeft moves to the column on the left: the next column.
-        const key = logicalArrowKey(event.key, isRtl(viewport));
-        const isSpace = key === ' ' || key === 'Spacebar';
-        const isEditing = Boolean(editingHandlers.editingCell);
-
-        // Row positions: rows from 0, the column header row at `headerRow`, and the header filter
-        // row (when rendered) at -1, between the header and the rows.
-        const headerRow = headerFilters ? -2 : -1;
-        const moveTo = (r: number, c: number) => {
-            const col = navigationColumns[c];
-            if (!col || r < headerRow || r >= allRenderableRows.length) return;
-            if (r === headerRow) setFocusedCell({ id: null, field: col.field });
-            else if (r < 0) setFocusedCell({ id: null, field: col.field, headerFilter: true });
-            else setFocusedCell({ id: getRowId(allRenderableRows[r]), field: col.field, rowIndex: r });
-            scrollCellIntoView(r, col.field);
-        };
-
-        if (!focusedCell) {
-            if (!NAVIGATION_KEYS.has(key)) return;
-            const initial = getDefaultFocus();
-            if (!initial) return;
-            event.preventDefault();
-            setFocusedCell(initial);
-            scrollCellIntoView(initial.rowIndex ?? -1, initial.field);
-            return;
-        }
-
-        const { id, field } = focusedCell;
-        const onHeaderFilter = id === null && Boolean(focusedCell.headerFilter);
-        const rowIndex = id !== null ? focusedRowIndex : onHeaderFilter ? -1 : headerRow;
-        const colIndex = navigationColumns.findIndex(c => c.field === field);
-        const systemColumnCount = navigationColumns.filter(c => isSystemField(c.field)).length;
-        const isSyntheticRow = (rowId: GridRowId) => isSyntheticRowId(rowId, rowMetaMap);
-        // Same rule and starting value as double-click (see Row / resolveCellEditable).
-        const isEditableCell = (row: R, r: number, c: number) => {
-            const colDef = navigationColumns[c] as GridColDef<R>;
-            if (isSystemField(colDef.field)) return false;
-            return resolveCellEditable({
-                row,
-                field: colDef.field,
-                value: getCellValue(row, colDef.field, colDef),
-                colDef,
-                rowIndex: r,
-                colIndex: c - systemColumnCount,
-                rowMeta: rowMetaMap?.get(getRowId(row)),
-            }, isCellEditable);
-        };
-
-        // Next editable data cell in reading order, for Tab while editing.
-        const findNextEditable = (deltaCol: number) => {
-            let r = rowIndex;
-            let c = colIndex;
-            const maxSteps = (allRenderableRows.length + 1) * navigationColumns.length;
-            for (let steps = 0; steps < maxSteps; steps++) {
-                c += deltaCol;
-                if (c >= navigationColumns.length) { c = 0; r++; }
-                else if (c < 0) { c = navigationColumns.length - 1; r--; }
-                if (r < 0 || r >= allRenderableRows.length) return null;
-
-                const row = allRenderableRows[r];
-                // Cells covered by a span are not stops; their origin is.
-                if (getSpanOrigin?.(getRowId(row), navigationColumns[c].field)) continue;
-                if (isEditableCell(row, r, c)) return { r, c };
-            }
-            return null;
-        };
-
-        if (isEditing) {
-            if (key === 'Enter') {
-                event.preventDefault();
-                editingHandlers.stopCellEdit();
-            } else if (key === 'Escape') {
-                event.preventDefault();
-                editingHandlers.stopCellEdit({ cancel: true });
-            } else if (key === 'Tab' && id !== null) {
-                // No next editable cell: the browser moves focus on and the editor commits on blur.
-                const next = findNextEditable(event.shiftKey ? -1 : 1);
-                if (next) {
-                    event.preventDefault();
-                    editingHandlers.stopCellEdit();
-                    moveTo(next.r, next.c);
-                }
-            }
-            return;
-        }
-
-        // Tab is not captured outside edit mode: the grid is a single tab stop and Tab leaves it
-        // (or reaches focusable content inside cells and detail panels).
-        if (key === 'Escape' && cellSelection?.collapseSelection()) {
-            event.preventDefault();
-            return;
-        }
-        if (key === 'Tab' || key === 'Escape') return;
-        // Enter and Space activate a control rendered inside a cell.
-        if (targetKind === 'control' && (key === 'Enter' || isSpace)) return;
-
-        if ((event.ctrlKey || event.metaKey) && (key === 'a' || key === 'A')) {
-            if (cellSelection) {
-                if (cellSelection.selectAllCells()) event.preventDefault();
-                return;
-            }
-            if (!rowSelectionEnabled || !multipleRowSelectionEnabled || !handleSelectAll) return;
-            event.preventDefault();
-            handleSelectAll(true);
-            return;
-        }
-
-        // A filter cell handles Enter, Space and typing itself (HeaderFilterCell).
-        if (onHeaderFilter && (key === 'Enter' || isSpace)) return;
-        if (id === null) {
-            if (key === 'Enter' || isSpace) {
-                event.preventDefault();
-                if (field === CHECKBOX_FIELD) {
-                    // Same as clicking the select-all checkbox.
-                    findFocusTarget(viewport, focusedCell, -1)?.click();
-                    return;
-                }
-                const col = navigationColumns[colIndex];
-                if (!col || isSystemField(field) || col.sortable === false) return;
-                const currentSort = sortModel.find(item => item.field === field);
-                const direction: GridSortDirection = currentSort ? (currentSort.sort === 'asc' ? 'desc' : null) : 'asc';
-                if ((multiSort || event.shiftKey) && handleSortAdd) handleSortAdd(field, direction);
-                else handleSort(field, direction);
-                return;
-            }
-        } else if (key === 'Enter' || isSpace) {
-            event.preventDefault();
-            const row = allRenderableRows[rowIndex];
-            if (field === CHECKBOX_FIELD) {
-                handleSelectionChange(id, !selectedRowIds.has(id));
-                return;
-            }
-            if (field === EXPAND_FIELD) {
-                if (!event.shiftKey) handleDetailPanelToggle(id);
-                return;
-            }
-            if (isSpace) {
-                // Shift+Space selects the row; plain Space only must not scroll the viewport.
-                if (event.shiftKey && rowSelectionEnabled && !isSyntheticRow(id)) {
-                    handleSelectionChange(id, !selectedRowIds.has(id));
-                }
-                return;
-            }
-            if (field === REORDER_FIELD) return;
-            if (isEditableCell(row, rowIndex, colIndex)) {
-                editingHandlers.startCellEdit({ id, field, value: getCellValue(row, field, navigationColumns[colIndex] as GridColDef<R>) });
-                return;
-            }
-            // A row with children toggles, so keyboard users can expand a tree-data parent even
-            // though clicking it selects it. Others: the keyboard equivalent of clicking the row.
-            if (toggleRowExpansion && rowMetaMap?.get(id)?.hasChildren) {
-                toggleRowExpansion(id);
-                return;
-            }
-            onRowActivate?.({ row, id, rowIndex });
-            return;
-        }
-
-        // Treegrid shortcuts: Alt+ArrowRight expands, Alt+ArrowLeft collapses the focused row.
-        if (event.altKey && (key === 'ArrowRight' || key === 'ArrowLeft') && toggleRowExpansion && id !== null) {
-            event.preventDefault();
-            const meta = rowMetaMap?.get(id);
-            if (meta?.hasChildren && Boolean(meta.isExpanded) !== (key === 'ArrowRight')) toggleRowExpansion(id);
-            return;
-        }
-
-        if (!NAVIGATION_KEYS.has(key)) return;
-        // Prevent native scrolling even when the focus cannot move (grid edges).
-        event.preventDefault();
-
-        const lastRow = allRenderableRows.length - 1;
-        const lastCol = navigationColumns.length - 1;
-        const withModifier = event.ctrlKey || event.metaKey;
-        const page = pagination ? pageSize : 10;
-
-        // Shift+navigation on a data cell extends the cell range; focus stays on its anchor.
-        if (cellSelection && event.shiftKey && id !== null && isRangeColumnField(field)
-            && cellSelection.extendSelection(key, withModifier, page, focusedCell)) {
-            return;
-        }
-
-        const step = (r: number, c: number): { r: number; c: number } => {
-            switch (key) {
-                case 'ArrowRight': return c + 1 > lastCol ? { r: r + 1, c: 0 } : { r, c: c + 1 };
-                case 'ArrowLeft': return c - 1 < 0 ? { r: r - 1, c: lastCol } : { r, c: c - 1 };
-                case 'ArrowDown': return { r: r + 1, c };
-                case 'ArrowUp': return { r: r - 1, c };
-                case 'Home': return { r: withModifier ? headerRow : r, c: 0 };
-                case 'End': return { r: withModifier ? lastRow : r, c: lastCol };
-                case 'PageUp': return { r: Math.max(headerRow, r - page), c };
-                default: return { r: Math.min(lastRow, r + page), c };
-            }
-        };
-        const inGrid = ({ r, c }: { r: number; c: number }) => r >= headerRow && r <= lastRow && c >= 0 && c <= lastCol;
-        const spanOriginAt = ({ r, c }: { r: number; c: number }) =>
-            r >= 0 ? getSpanOrigin?.(getRowId(allRenderableRows[r]), navigationColumns[c].field) ?? null : null;
-
-        let next = step(rowIndex, colIndex);
-        // Arrow keys step over the cells of the focused span (its own merged area) ...
-        if (key.startsWith('Arrow')) {
-            for (let origin = inGrid(next) ? spanOriginAt(next) : null;
-                origin && origin.rowId === id && origin.field === field;
-                origin = inGrid(next) ? spanOriginAt(next) : null) {
-                next = step(next.r, next.c);
-            }
-        }
-        if (!inGrid(next)) return;
-        // ... then land on the origin of whatever span covers the target cell.
-        const origin = spanOriginAt(next);
-        if (origin) {
-            const originRow = allRenderableRows.findIndex(r => getRowId(r) === origin.rowId);
-            const originCol = navigationColumns.findIndex(c => c.field === origin.field);
-            if (originRow !== -1 && originCol !== -1) next = { r: originRow, c: originCol };
-        }
-        if (next.r === rowIndex && next.c === colIndex) return;
-        moveTo(next.r, next.c);
+        handleGridKeyDown(event, {
+            focusedCell,
+            focusedRowIndex,
+            allRenderableRows,
+            navigationColumns,
+            editingHandlers,
+            selectedRowIds,
+            handleSelectionChange,
+            handleDetailPanelToggle,
+            setKeyboardMode,
+            sortModel,
+            handleSort,
+            handleSortAdd,
+            multiSort,
+            isCellEditable,
+            pagination,
+            pageSize,
+            rowMetaMap,
+            onRowActivate,
+            toggleRowExpansion,
+            handleSelectAll,
+            rowSelectionEnabled,
+            multipleRowSelectionEnabled,
+            getDefaultFocus,
+            scrollCellIntoView,
+            getSpanOrigin,
+            getRowId,
+            cellSelection,
+            headerFilters,
+            setFocusedCell,
+        });
     }, [
         focusedCell,
         focusedRowIndex,

package/lib/hooks/core/useGridLiveRowSelection.ts

@@ -3,7 +3,7 @@ import type { GridRowId, GridRowMeta, GridRowModel } from '../../types';
 
 export interface UseGridLiveRowSelectionParams {
     /** The selection model (controlled prop or internal state). */
-    selectedRowIds: Set<GridRowId>;
+    selectedRowIds: ReadonlySet<GridRowId>;
     /** The row store: ids of the rows the grid holds. */
     rowsLookup: ReadonlyMap<GridRowId, GridRowModel>;
     /** Hierarchy rows the grid made (group rows, generated tree parents); their ids are kept. */
@@ -32,7 +32,7 @@ const idsKey = (ids: Iterable<GridRowId>): string =>
  * own state that re-adds them) is not notified again and cannot loop, and StrictMode's re-run of
  * the effect does not report twice.
  */
-export function useGridLiveRowSelection(params: UseGridLiveRowSelectionParams): Set<GridRowId> {
+export function useGridLiveRowSelection(params: UseGridLiveRowSelectionParams): ReadonlySet<GridRowId> {
     const { selectedRowIds, rowsLookup, rowMetaMap, enabled, onSelectionModelChange } = params;
 
     const liveRowIds = useMemo(() => {

package/lib/hooks/core/useGridRowInteractions.ts

@@ -10,7 +10,7 @@ export interface UseGridRowInteractionsParams<R extends GridRowModel> {
     dataRows: R[];
     getRowId: (row: GridRowModel) => GridRowId;
     isPivotActive: boolean;
-    selectedRowIds: Set<GridRowId>;
+    selectedRowIds: ReadonlySet<GridRowId>;
     onSelectionModelChange: (model: GridRowId[]) => void;
     disableMultipleRowSelection: boolean;
     disableRowSelectionOnClick: boolean;

package/lib/hooks/core/useGridRowSelection.ts

@@ -1,5 +1,6 @@
 import { useCallback, useMemo } from 'react';
 import type { GridRowId } from '../../types';
+import { isKnownToContainAll, markContainsAll, rememberSelectionSet } from '../../utils/selectionSets';
 
 // ── Pure selection transitions (shared by the UI handlers and the imperative API) ──────────
 
@@ -15,7 +16,12 @@ export function nextSelectionForRows(
     }
     const next = new Set(current);
     ids.forEach(id => (isSelected ? next.add(id) : next.delete(id)));
-    return Array.from(next);
+    const model = Array.from(next);
+    // The model's set is `next`: reused when this array comes back as rowSelectionModel, and known to
+    // contain `ids` when they were selected (select-all then skips counting them again).
+    rememberSelectionSet(model, next);
+    if (isSelected) markContainsAll(next, ids);
+    return model;
 }
 
 /** A row click toggles the row; with `single` it replaces the selection instead of adding to it. */
@@ -30,7 +36,7 @@ export function isSameSelection(current: ReadonlySet<GridRowId>, next: readonly
 }
 
 export interface UseGridRowSelectionParams {
-    selectedRowIds: Set<GridRowId>;
+    selectedRowIds: ReadonlySet<GridRowId>;
     /** Applies a new model: internal state when uncontrolled, plus onRowSelectionModelChange. */
     onSelectionModelChange: (model: GridRowId[]) => void;
     disableMultipleRowSelection: boolean;
@@ -75,6 +81,9 @@ export function useGridRowSelection(params: UseGridRowSelectionParams): UseGridR
     }, [commit, selectedRowIds, selectableRowIds]);
 
     const { allSelected, someSelected } = useMemo(() => {
+        if (selectableRowIds.length > 0 && isKnownToContainAll(selectedRowIds, selectableRowIds)) {
+            return { allSelected: true, someSelected: false };
+        }
         let selectedCount = 0;
         for (const id of selectableRowIds) if (selectedRowIds.has(id)) selectedCount++;
         const all = selectableRowIds.length > 0 && selectedCount === selectableRowIds.length;

package/lib/hooks/core/useGridToolbarProps.ts

@@ -13,6 +13,7 @@ import type {
     GridRowModel,
     GridToolbarSlotProps,
 } from '../../types';
+import { untypedColumns } from '../../utils/untypedColumns';
 
 type ToolbarSlot = NonNullable<DataGridProps['slots']>['toolbar'];
 type ToolbarSlotProps = NonNullable<DataGridProps['slotProps']>['toolbar'];
@@ -79,8 +80,8 @@ export function useGridToolbarProps<R extends GridRowModel>(
             };
         return {
             apiRef,
-            columns: orderedColumns as unknown as GridColDef[],
-            baseColumns: baseColumns as unknown as GridColDef[],
+            columns: untypedColumns(orderedColumns),
+            baseColumns: baseColumns && untypedColumns(baseColumns),
             aggregationModel,
             onAggregationModelChange,
             ...(pivotMode || pivotModelProp || onPivotModelChangeProp ? {

package/lib/hooks/features/useGridAiAssistant.ts

@@ -12,7 +12,7 @@ import type {
     GridColDef,
     GridLocaleText,
 } from '../../types';
-import { resolveGridLocale, type ResolvedGridLocale } from '../../utils/gridLocale';
+import { aiChipTextsOf, resolveGridLocale, type ResolvedGridLocale } from '../../utils/gridLocale';
 import { attempt } from '../../utils/attempt';
 import { isGridAiValidated } from '../../utils/aiBrand';
 import {
@@ -143,7 +143,8 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         const byField = new Map(columns.map((col) => [col.field, col.headerName || col.field]));
         return (field: string) => byField.get(field) ?? field;
     }, [columns]);
-    const chips = useMemo(() => (applied ? buildAiChips(applied.state, labelOf) : []), [applied, labelOf]);
+    const chipTexts = useMemo(() => aiChipTextsOf(locale), [locale]);
+    const chips = useMemo(() => (applied ? buildAiChips(applied.state, labelOf, chipTexts) : []), [applied, labelOf, chipTexts]);
 
     const abortRequest = useCallback(() => {
         const controller = controllerRef.current;

package/lib/hooks/useColumnReorder.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useRef, useEffect } from 'react';
 import type { GridColDef, GridRowModel, GridColumnOrderChangeParams } from '../types';
 import { COLUMN_DRAG_MIME, hasDragToken, onNativeDragEnd, setDragToken } from '../utils/dragData';
+import { untypedColumn } from '../utils/untypedColumns';
 
 export interface UseColumnReorderProps<R extends GridRowModel = GridRowModel> {
   /** Every current column, in the grid's column order. Reported indices are positions in it. */
@@ -89,7 +90,7 @@ export function useColumnReorder<R extends GridRowModel = GridRowModel>(
       if (oldIndex === -1 || targetIndex === -1 || oldIndex === targetIndex) return;
 
       onColumnOrderChange?.({
-        column: columns[oldIndex] as unknown as GridColDef,
+        column: untypedColumn(columns[oldIndex]),
         oldIndex,
         targetIndex,
       });

package/lib/hooks/useTreeData.ts

@@ -319,7 +319,9 @@ export function useTreeData<R extends GridRowModel>(props: UseTreeDataProps<R>)
      * indent and the labels of auto-created parents): sorting by it orders auto-created parents by
      * their label, since they have no cell values of their own.
      */
-    const getVisibleRows = useCallback((options?: GridHierarchyVisibleRowsOptions): GridRowModel[] | null => {
+    // Generated parent rows (missing path ancestors) are rendered like the consumer's rows and typed as
+    // `R`, as row grouping's group rows are: the grid's documented convention for rendered rows.
+    const getVisibleRows = useCallback((options?: GridHierarchyVisibleRowsOptions): R[] | null => {
         if (!isActive) return null;
         const labelField = options?.labelField;
         const expandAll = options?.expandAll ?? false;
@@ -364,7 +366,7 @@ export function useTreeData<R extends GridRowModel>(props: UseTreeDataProps<R>)
         };
 
         traverse(rootIds);
-        return result;
+        return result as R[];
     }, [isActive, visibility, isClientSort, sortModel, syntheticIds, treeNodes, rowLookup, columnLookup, rootIds, expandedGroupIds]);
 
     const isGroupExpanded = useCallback((id: GridRowId) => expandedGroupIds.has(id), [expandedGroupIds]);

package/lib/types/locale.ts

@@ -364,6 +364,28 @@ export interface GridLocaleText {
     aiAssistantFailed?: (message: string) => string;
     /** Error text when a failed request has no message. Default: `"Unknown error"` @since v3.9 */
     aiAssistantUnknownError?: string;
+    /** Change chip for the quick-filter words. Default: `` (w) => `Search: ${w}` `` @since v3.10 */
+    aiAssistantChipSearch?: (words: string) => string;
+    /** Change chip when the reply cleared the filters. Default: `"No filters"` @since v3.10 */
+    aiAssistantChipNoFilters?: string;
+    /** Change chip for one sort key. Default: `` (f, d) => `Sort: ${f}, ascending|descending` `` @since v3.10 */
+    aiAssistantChipSort?: (field: string, direction: 'asc' | 'desc') => string;
+    /** Change chip when the reply cleared the sort. Default: `"No sorting"` @since v3.10 */
+    aiAssistantChipNoSorting?: string;
+    /** Change chip for one grouping field. Default: `` (f) => `Group: ${f}` `` @since v3.10 */
+    aiAssistantChipGroup?: (field: string) => string;
+    /** Change chip when the reply removed grouping. Default: `"No grouping"` @since v3.10 */
+    aiAssistantChipNoGrouping?: string;
+    /** Change chip for one summary; `fn` is the function id (`sum`, `avg`, …). Default: `` (fn, f) => `Sum: ${f}` `` (Sum, Average, Count, Min, Max, Unique) @since v3.10 */
+    aiAssistantChipSummary?: (fn: string, field: string) => string;
+    /** Change chip when the reply removed the summaries. Default: `"No summaries"` @since v3.10 */
+    aiAssistantChipNoSummaries?: string;
+    /** Change chip for the pivot; receives the column labels joined with ", ". Default: `` (f) => `Pivot: ${f}` `` @since v3.10 */
+    aiAssistantChipPivot?: (fields: string) => string;
+    /** Change chip when the reply turned the pivot off. Default: `"No pivot"` @since v3.10 */
+    aiAssistantChipNoPivot?: string;
+    /** Change chip for a column shown or hidden. Default: `` (f, v) => `Show: ${f}` `` / `` `Hide: ${f}` `` @since v3.10 */
+    aiAssistantChipVisibility?: (field: string, visible: boolean) => string;
 
     // ── Pagination (v3.9) ─────────────────────────────────────────────────────
     /** `aria-label` of the pagination bar. Default: `"Pagination"` @since v3.9 */

package/lib/utils/aggregation/index.ts

@@ -210,3 +210,19 @@ export function formatAggregateForColumn<R extends GridRowModel>(
     if (normalized instanceof Date) return Number.isNaN(normalized.getTime()) ? '' : formatLocalDate(normalized);
     return formatAggregationValue(normalized, fnName);
 }
+
+const BUILT_IN_AGGREGATION_FUNCTIONS = Object.keys(AGGREGATION_FUNCTIONS) as BuiltInAggFn[];
+
+function isBuiltInAggregationFunction(fn: string): fn is BuiltInAggFn {
+    return Object.prototype.hasOwnProperty.call(AGGREGATION_FUNCTIONS, fn);
+}
+
+/**
+ * The summary functions offered for a column: its `availableAggregationFunctions` when set,
+ * otherwise every built-in one. Names the aggregation engine does not implement are dropped,
+ * because choosing one would show the label in the header but never compute a value.
+ */
+export function getOfferedAggregationFunctions(col: Pick<GridColDef, 'availableAggregationFunctions'>): BuiltInAggFn[] {
+    if (!col.availableAggregationFunctions) return BUILT_IN_AGGREGATION_FUNCTIONS;
+    return Array.from(new Set(col.availableAggregationFunctions.filter(isBuiltInAggregationFunction)));
+}

package/lib/utils/aiAssistant.ts

@@ -119,47 +119,78 @@ function valueText(value: unknown): string {
     return value === undefined || value === null ? '' : String(value);
 }
 
-function filterLabel(node: GridFilterItem | GridFilterGroup, label: (field: string) => string): string {
-    if ('items' in node) return `(${node.items.map((child) => filterLabel(child, label)).join(` ${node.logicOperator} `)})`;
-    return [label(node.field), node.operator, valueText(node.value)].filter(Boolean).join(' ');
+function filterLabel(node: GridFilterItem | GridFilterGroup, label: (field: string) => string, operator: (op: string) => string): string {
+    if ('items' in node) return `(${node.items.map((child) => filterLabel(child, label, operator)).join(` ${node.logicOperator} `)})`;
+    return [label(node.field), operator(node.operator), valueText(node.value)].filter(Boolean).join(' ');
 }
 
 const FN_LABELS: Record<string, string> = { sum: 'Sum', avg: 'Average', count: 'Count', min: 'Min', max: 'Max', unique: 'Unique' };
 
+/** The chips' texts (the grid passes its `localeText`; English by default). */
+export interface GridAiChipTexts {
+    operator: (operator: string) => string;
+    search: (words: string) => string;
+    noFilters: string;
+    sort: (field: string, direction: 'asc' | 'desc') => string;
+    noSorting: string;
+    group: (field: string) => string;
+    noGrouping: string;
+    summary: (fn: string, field: string) => string;
+    noSummaries: string;
+    pivot: (fields: string) => string;
+    noPivot: string;
+    visibility: (field: string, visible: boolean) => string;
+}
+
+export const AI_CHIP_TEXTS_EN: GridAiChipTexts = {
+    operator: op => op,
+    search: words => `Search: ${words}`,
+    noFilters: 'No filters',
+    sort: (field, direction) => `Sort: ${field}, ${direction === 'desc' ? 'descending' : 'ascending'}`,
+    noSorting: 'No sorting',
+    group: field => `Group: ${field}`,
+    noGrouping: 'No grouping',
+    summary: (fn, field) => `${FN_LABELS[fn] ?? fn}: ${field}`,
+    noSummaries: 'No summaries',
+    pivot: fields => `Pivot: ${fields}`,
+    noPivot: 'No pivot',
+    visibility: (field, visible) => `${visible ? 'Show' : 'Hide'}: ${field}`,
+};
+
 /** One chip per change: filter item, quick-filter words, sort key, grouping field, aggregation, visibility change, pivot. */
-export function buildAiChips(applied: GridAiState, label: (field: string) => string): GridAiChip[] {
+export function buildAiChips(applied: GridAiState, label: (field: string) => string, texts: GridAiChipTexts = AI_CHIP_TEXTS_EN): GridAiChip[] {
     const chips: GridAiChip[] = [];
     const { filterModel, sortModel, rowGroupingModel, aggregationModel, pivotModel, columnVisibilityModel } = applied;
     if (filterModel) {
         const items = filterModel.items ?? [];
-        items.forEach((item, i) => chips.push({ id: `filter:${i}`, part: 'filter', label: filterLabel(item, label) }));
+        items.forEach((item, i) => chips.push({ id: `filter:${i}`, part: 'filter', label: filterLabel(item, label, texts.operator) }));
         const words = filterModel.quickFilterValues ?? [];
-        if (words.length > 0) chips.push({ id: 'filter:quick', part: 'filter', label: `Search: ${words.join(' ')}` });
-        if (items.length === 0 && words.length === 0) chips.push({ id: 'filter:clear', part: 'filter', label: 'No filters' });
+        if (words.length > 0) chips.push({ id: 'filter:quick', part: 'filter', label: texts.search(words.join(' ')) });
+        if (items.length === 0 && words.length === 0) chips.push({ id: 'filter:clear', part: 'filter', label: texts.noFilters });
     }
     if (sortModel) {
-        sortModel.forEach((s, i) => chips.push({ id: `sort:${i}`, part: 'sort', label: `Sort: ${label(s.field)}, ${s.sort === 'desc' ? 'descending' : 'ascending'}` }));
-        if (sortModel.length === 0) chips.push({ id: 'sort:clear', part: 'sort', label: 'No sorting' });
+        sortModel.forEach((s, i) => chips.push({ id: `sort:${i}`, part: 'sort', label: texts.sort(label(s.field), s.sort === 'desc' ? 'desc' : 'asc') }));
+        if (sortModel.length === 0) chips.push({ id: 'sort:clear', part: 'sort', label: texts.noSorting });
     }
     if (rowGroupingModel) {
-        rowGroupingModel.forEach((field, i) => chips.push({ id: `grouping:${i}`, part: 'grouping', label: `Group: ${label(field)}` }));
-        if (rowGroupingModel.length === 0) chips.push({ id: 'grouping:clear', part: 'grouping', label: 'No grouping' });
+        rowGroupingModel.forEach((field, i) => chips.push({ id: `grouping:${i}`, part: 'grouping', label: texts.group(label(field)) }));
+        if (rowGroupingModel.length === 0) chips.push({ id: 'grouping:clear', part: 'grouping', label: texts.noGrouping });
     }
     if (aggregationModel) {
         const fields = Object.keys(aggregationModel);
         fields.forEach((field) => {
             const fn = aggregationModel[field];
-            chips.push({ id: `aggregation:${field}`, part: 'aggregation', label: `${FN_LABELS[fn] ?? fn}: ${label(field)}` });
+            chips.push({ id: `aggregation:${field}`, part: 'aggregation', label: texts.summary(fn, label(field)) });
         });
-        if (fields.length === 0) chips.push({ id: 'aggregation:clear', part: 'aggregation', label: 'No summaries' });
+        if (fields.length === 0) chips.push({ id: 'aggregation:clear', part: 'aggregation', label: texts.noSummaries });
     }
     if (pivotModel) {
         const fields = [...pivotModel.rowFields, ...pivotModel.columnFields, ...pivotModel.valueFields.map((v) => v.field)];
-        chips.push({ id: 'pivot', part: 'pivot', label: fields.length > 0 ? `Pivot: ${fields.map(label).join(', ')}` : 'No pivot' });
+        chips.push({ id: 'pivot', part: 'pivot', label: fields.length > 0 ? texts.pivot(fields.map(label).join(', ')) : texts.noPivot });
     }
     if (columnVisibilityModel) {
         for (const field of Object.keys(columnVisibilityModel)) {
-            chips.push({ id: `columnVisibility:${field}`, part: 'columnVisibility', label: `${columnVisibilityModel[field] ? 'Show' : 'Hide'}: ${label(field)}` });
+            chips.push({ id: `columnVisibility:${field}`, part: 'columnVisibility', label: texts.visibility(label(field), Boolean(columnVisibilityModel[field])) });
         }
     }
     return chips;