@opencorestack/opengridx 1.3.0 → 2.0.1

package/lib/components/DataGrid/DataGrid.v2.test.tsx

@@ -0,0 +1,127 @@
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { DataGrid } from './DataGrid';
+import type { GridColDef } from '../../types';
+
+const COLUMNS: GridColDef[] = [
+    { field: 'id', headerName: 'ID', width: 80 },
+    { field: 'name', headerName: 'Name', width: 150 },
+    { field: 'dept', headerName: 'Dept', width: 120 },
+];
+
+const ROWS = [
+    { id: 1, name: 'Alice', dept: 'Eng' },
+    { id: 2, name: 'Bob', dept: 'HR' },
+];
+
+// ── density ──────────────────────────────────────────────────────────────────
+
+describe('DataGrid — density prop', () => {
+    it('renders without throwing for compact density', () => {
+        expect(() =>
+            render(<DataGrid rows={ROWS} columns={COLUMNS} density="compact" />)
+        ).not.toThrow();
+    });
+
+    it('renders without throwing for comfortable density', () => {
+        expect(() =>
+            render(<DataGrid rows={ROWS} columns={COLUMNS} density="comfortable" />)
+        ).not.toThrow();
+    });
+
+    it('applies compact row height via CSS variable', () => {
+        const { container } = render(
+            <DataGrid rows={ROWS} columns={COLUMNS} density="compact" />
+        );
+        const root = container.firstElementChild as HTMLElement;
+        expect(root.style.getPropertyValue('--ogx-row-height')).toBe('32px');
+    });
+
+    it('applies comfortable row height via CSS variable', () => {
+        const { container } = render(
+            <DataGrid rows={ROWS} columns={COLUMNS} density="comfortable" />
+        );
+        const root = container.firstElementChild as HTMLElement;
+        expect(root.style.getPropertyValue('--ogx-row-height')).toBe('72px');
+    });
+
+    it('uses rowHeight as default when density is standard', () => {
+        const { container } = render(
+            <DataGrid rows={ROWS} columns={COLUMNS} density="standard" rowHeight={52} />
+        );
+        const root = container.firstElementChild as HTMLElement;
+        expect(root.style.getPropertyValue('--ogx-row-height')).toBe('52px');
+    });
+});
+
+// ── disableRowSelectionOnClick ────────────────────────────────────────────────
+
+describe('DataGrid — disableRowSelectionOnClick', () => {
+    it('clicking a row changes selection when prop is false (default)', () => {
+        const onChange = vi.fn();
+        render(
+            <DataGrid
+                rows={ROWS}
+                columns={COLUMNS}
+                onRowSelectionModelChange={onChange}
+            />
+        );
+        const rows = screen.getAllByRole('row');
+        // rows[0] is header, rows[1] is Alice
+        fireEvent.click(rows[1]);
+        expect(onChange).toHaveBeenCalled();
+    });
+
+    it('clicking a row does NOT change selection when disableRowSelectionOnClick=true', () => {
+        const onChange = vi.fn();
+        render(
+            <DataGrid
+                rows={ROWS}
+                columns={COLUMNS}
+                disableRowSelectionOnClick
+                onRowSelectionModelChange={onChange}
+            />
+        );
+        const rows = screen.getAllByRole('row');
+        fireEvent.click(rows[1]);
+        expect(onChange).not.toHaveBeenCalled();
+    });
+});
+
+// ── disableMultipleRowSelection ───────────────────────────────────────────────
+
+describe('DataGrid — disableMultipleRowSelection', () => {
+    it('selecting a second row replaces the first when disableMultipleRowSelection=true', () => {
+        const selections: unknown[][] = [];
+        render(
+            <DataGrid
+                rows={ROWS}
+                columns={COLUMNS}
+                disableMultipleRowSelection
+                onRowSelectionModelChange={(model) => selections.push(model)}
+            />
+        );
+        const rows = screen.getAllByRole('row');
+        fireEvent.click(rows[1]); // select Alice (id=1)
+        fireEvent.click(rows[2]); // select Bob (id=2) — should replace
+        expect(selections.at(-1)).toEqual([2]);
+        expect(selections.at(-1)?.length).toBe(1);
+    });
+
+    it('clicking already-selected row deselects it when disableMultipleRowSelection=true', () => {
+        const selections: unknown[][] = [];
+        render(
+            <DataGrid
+                rows={ROWS}
+                columns={COLUMNS}
+                disableMultipleRowSelection
+                onRowSelectionModelChange={(model) => selections.push(model)}
+            />
+        );
+        const rows = screen.getAllByRole('row');
+        fireEvent.click(rows[1]); // select
+        fireEvent.click(rows[1]); // deselect
+        expect(selections.at(-1)).toEqual([]);
+    });
+});

package/lib/components/Header/Header.test.tsx

@@ -0,0 +1,135 @@
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { Header } from './Header';
+import type { GridColDef } from '../../types';
+
+const COLUMNS: GridColDef[] = [
+    { field: 'name', headerName: 'Name', width: 150 },
+    { field: 'age', headerName: 'Age', width: 100 },
+    { field: 'dept', headerName: 'Dept', width: 120 },
+];
+
+describe('Header — multi-sort shift-click', () => {
+    it('plain click calls onSort with single field (replaces model)', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        render(
+            <Header
+                columns={COLUMNS}
+                sortModel={[]}
+                onSort={onSort}
+                onSortAdd={onSortAdd}
+            />
+        );
+        fireEvent.click(screen.getByText('Name'));
+        expect(onSort).toHaveBeenCalledWith('name', 'asc');
+        expect(onSortAdd).not.toHaveBeenCalled();
+    });
+
+    it('shift-click calls onSortAdd (accumulates)', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        render(
+            <Header
+                columns={COLUMNS}
+                sortModel={[{ field: 'name', sort: 'asc' }]}
+                onSort={onSort}
+                onSortAdd={onSortAdd}
+            />
+        );
+        fireEvent.click(screen.getByText('Age'), { shiftKey: true });
+        expect(onSortAdd).toHaveBeenCalledWith('age', 'asc');
+        expect(onSort).not.toHaveBeenCalled();
+    });
+
+    it('shift-click on already-sorted field cycles direction without replacing others', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        render(
+            <Header
+                columns={COLUMNS}
+                sortModel={[
+                    { field: 'name', sort: 'asc' },
+                    { field: 'age', sort: 'asc' },
+                ]}
+                onSort={onSort}
+                onSortAdd={onSortAdd}
+            />
+        );
+        fireEvent.click(screen.getByText('Age'), { shiftKey: true });
+        expect(onSortAdd).toHaveBeenCalledWith('age', 'desc');
+        expect(onSort).not.toHaveBeenCalled();
+    });
+
+    it('shift-click on desc-sorted field removes it from model', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        render(
+            <Header
+                columns={COLUMNS}
+                sortModel={[
+                    { field: 'name', sort: 'asc' },
+                    { field: 'age', sort: 'desc' },
+                ]}
+                onSort={onSort}
+                onSortAdd={onSortAdd}
+            />
+        );
+        fireEvent.click(screen.getByText('Age'), { shiftKey: true });
+        expect(onSortAdd).toHaveBeenCalledWith('age', null);
+        expect(onSort).not.toHaveBeenCalled();
+    });
+
+    it('plain click on one column while another is sorted resets to single-key', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        render(
+            <Header
+                columns={COLUMNS}
+                sortModel={[{ field: 'name', sort: 'asc' }]}
+                onSort={onSort}
+                onSortAdd={onSortAdd}
+            />
+        );
+        fireEvent.click(screen.getByText('Age'));
+        expect(onSort).toHaveBeenCalledWith('age', 'asc');
+        expect(onSortAdd).not.toHaveBeenCalled();
+    });
+
+    it('does not call onSort/onSortAdd for sortable:false columns', () => {
+        const onSort = vi.fn();
+        const onSortAdd = vi.fn();
+        const cols: GridColDef[] = [
+            { field: 'id', headerName: 'ID', sortable: false },
+        ];
+        render(<Header columns={cols} sortModel={[]} onSort={onSort} onSortAdd={onSortAdd} />);
+        fireEvent.click(screen.getByText('ID'));
+        expect(onSort).not.toHaveBeenCalled();
+        expect(onSortAdd).not.toHaveBeenCalled();
+    });
+});
+
+describe('Header — description tooltip', () => {
+    it('renders title attribute from column description', () => {
+        const cols: GridColDef[] = [
+            { field: 'salary', headerName: 'Salary', description: 'Annual salary in USD' },
+        ];
+        const { container } = render(
+            <Header columns={cols} sortModel={[]} />
+        );
+        const headerCell = container.querySelector('[data-field="salary"]');
+        expect(headerCell?.getAttribute('title')).toBe('Annual salary in USD');
+    });
+
+    it('has no title attribute when description is absent', () => {
+        const cols: GridColDef[] = [
+            { field: 'name', headerName: 'Name' },
+        ];
+        const { container } = render(
+            <Header columns={cols} sortModel={[]} />
+        );
+        const headerCell = container.querySelector('[data-field="name"]');
+        expect(headerCell?.getAttribute('title')).toBeNull();
+    });
+});

package/lib/components/Header/Header.tsx

@@ -134,6 +134,8 @@ export interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onDrop?: (targetField: string) => (event: React.DragEvent) => void;
     focusedCell?: { id: string | number; field: string } | null;
     onHeaderClick?: (field: string) => void;
+    onSortAdd?: (field: string, direction: GridSortDirection) => void;
+    multiSort?: boolean;
     onHideColumn?: (field: string) => void;
     onPinColumn?: (field: string, side: 'left' | 'right' | null) => void;
     onManageColumns?: () => void;
@@ -166,6 +168,8 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
         onDrop,
         focusedCell,
         onHeaderClick,
+        onSortAdd,
+        multiSort = false,
         onHideColumn,
         onPinColumn,
         onManageColumns,
@@ -193,8 +197,8 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
         }
     }, [focusedCell]);
 
-    const handleColumnClick = (colDef: GridColDef<R>) => () => {
-        if (colDef.sortable === false || !onSort) return;
+    const handleColumnClick = (colDef: GridColDef<R>) => (e: React.MouseEvent) => {
+        if (colDef.sortable === false) return;
 
         const currentSort = sortModel.find(item => item.field === colDef.field);
         let newDirection: GridSortDirection = 'asc';
@@ -207,15 +211,25 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
             }
         }
 
-        onSort(colDef.field, newDirection);
+        if ((e.shiftKey || multiSort) && onSortAdd) {
+            onSortAdd(colDef.field, newDirection);
+        } else if (onSort) {
+            onSort(colDef.field, newDirection);
+        }
     };
 
     const getSortIcon = (field: string) => {
         const sortItem = sortModel.find(item => item.field === field);
         if (!sortItem) return null;
 
+        const sortIndex = sortModel.length > 1 ? sortModel.indexOf(sortItem) + 1 : null;
+
         return (
-            <span className={`ogx__sort-icon ogx__sort-icon--${sortItem.sort}`} aria-hidden="true" />
+            <span className={`ogx__sort-icon ogx__sort-icon--${sortItem.sort}`} aria-hidden="true">
+                {sortIndex !== null && (
+                    <span className="ogx__sort-badge">{sortIndex}</span>
+                )}
+            </span>
         );
     };
 
@@ -420,7 +434,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                         }
                         onHeaderClick?.(colDef.field);
                         if (isSortable) {
-                            handleColumnClick(colDef)();
+                            handleColumnClick(colDef)(e);
                         }
                     };
 
@@ -433,6 +447,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                             key={colDef.field}
                             className={classNames}
                             style={style}
+                            title={colDef.description}
                             onClick={handleHeaderClick}
                             role="columnheader"
                             draggable={!!onDragStart}

package/lib/hooks/core/useGridColumns.tsx

@@ -95,10 +95,10 @@ export function useGridColumns<R extends GridRowModel>(
                         }
 
                         if (isRowGrouping && hasChildren && groupingField) {
+                            const groupLabel = meta?.groupLabel ?? `${groupingField}: ${String(groupingValue)}`;
                             content = (
                                 <div className="ogx__group-cell-content">
-                                    {col.field === groupingField ? '' : `${groupingField}: `}
-                                    {String(groupingValue)}
+                                    {groupLabel}
                                     {descendantCount !== undefined ? ` (${descendantCount})` : ''}
                                 </div>
                             );

package/lib/hooks/core/useGridControlledState.ts

@@ -81,7 +81,7 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         onPinnedColumnsChange,
         pivotModel: propPivotModel,
         onPivotModelChange,
-        paginationModel: propPaginationModel = { page: 0, pageSize: 100 },
+        paginationModel: propPaginationModel,
         onPaginationModelChange,
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange,
@@ -144,9 +144,9 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     }, [onPivotModelChange]);
 
     // ── Pagination ───────────────────────────────────────────────────────────
-    const isPaginationControlled = propPaginationModel !== undefined && params.paginationModel !== undefined;
+    const isPaginationControlled = propPaginationModel !== undefined;
     const [internalPaginationModel, setInternalPaginationModel] = useState<GridPaginationModel>(
-        () => initialState?.pagination?.paginationModel ?? propPaginationModel
+        () => initialState?.pagination?.paginationModel ?? propPaginationModel ?? { page: 0, pageSize: 100 }
     );
     const effectivePaginationModel = isPaginationControlled ? propPaginationModel : internalPaginationModel;
 

package/lib/hooks/features/useAggregation.test.ts

@@ -132,4 +132,44 @@ describe('useAggregation — client-side', () => {
         );
         expect(result.current.aggregationResult).toEqual(serverResults);
     });
+
+    it('skips aggregation when function not in availableAggregationFunctions', () => {
+        const columns = [{ field: 'salary', availableAggregationFunctions: ['avg', 'count'] }];
+        const { result } = renderHook(() =>
+            useAggregation({
+                rows: ROWS,
+                columns,
+                aggregationModel: { salary: 'sum' },
+                isServerSide: false,
+            })
+        );
+        // 'sum' is not in the allowed list, so the result should be absent
+        expect(result.current.aggregationResult.salary).toBeUndefined();
+    });
+
+    it('computes aggregation when function is in availableAggregationFunctions', () => {
+        const columns = [{ field: 'salary', availableAggregationFunctions: ['sum', 'avg'] }];
+        const { result } = renderHook(() =>
+            useAggregation({
+                rows: ROWS,
+                columns,
+                aggregationModel: { salary: 'sum' },
+                isServerSide: false,
+            })
+        );
+        expect(result.current.aggregationResult.salary).toBe(260000);
+    });
+
+    it('does not restrict aggregation when availableAggregationFunctions is absent', () => {
+        const columns = [{ field: 'salary' }];
+        const { result } = renderHook(() =>
+            useAggregation({
+                rows: ROWS,
+                columns,
+                aggregationModel: { salary: 'sum' },
+                isServerSide: false,
+            })
+        );
+        expect(result.current.aggregationResult.salary).toBe(260000);
+    });
 });

package/lib/hooks/features/useAggregation.ts

@@ -2,6 +2,7 @@
 import { useMemo, useEffect, useRef, useCallback, useState } from 'react';
 import type {
     GridRowModel,
+    GridColDef,
     GridAggregationModel,
     GridAggregationResult,
     GridFilterModel,
@@ -46,6 +47,7 @@ export function formatAggregationValue(value: unknown, fnName: string): string {
 
 export interface UseAggregationParams<R extends GridRowModel> {
         rows: R[];
+        columns?: GridColDef[];
         aggregationModel: GridAggregationModel;
         isServerSide: boolean;
         dataSource?: GridDataSource<R>;
@@ -65,6 +67,7 @@ export function useAggregation<R extends GridRowModel>(
 ): UseAggregationReturn {
     const {
         rows,
+        columns,
         aggregationModel,
         isServerSide,
         dataSource,
@@ -73,11 +76,21 @@ export function useAggregation<R extends GridRowModel>(
         serverAggregationResults,
     } = params;
 
+    const columnsLookup = useMemo(() => {
+        const map = new Map<string, GridColDef>();
+        (columns ?? []).forEach(col => map.set(col.field, col));
+        return map;
+    }, [columns]);
+
     const clientResult = useMemo<GridAggregationResult>(() => {
         if (isServerSide || Object.keys(aggregationModel).length === 0) return {};
 
         const result: GridAggregationResult = {};
         for (const [field, fnName] of Object.entries(aggregationModel)) {
+            const colDef = columnsLookup.get(field);
+            if (colDef?.availableAggregationFunctions && !colDef.availableAggregationFunctions.includes(fnName)) {
+                continue;
+            }
             const fn = AGGREGATION_FUNCTIONS[fnName as BuiltInAggFn];
             if (!fn) {
                 console.warn(`[useAggregation] Unknown aggregation function: "${fnName}"`);
@@ -87,7 +100,7 @@ export function useAggregation<R extends GridRowModel>(
             result[field] = fn(values);
         }
         return result;
-    }, [rows, aggregationModel, isServerSide]);
+    }, [rows, columnsLookup, aggregationModel, isServerSide]);
 
     const [serverResult, setServerResult] = useState<GridAggregationResult>({});
     const [isLoading, setIsLoading] = useState(false);

package/lib/hooks/useRowGrouping.test.ts

@@ -81,4 +81,57 @@ describe('useRowGrouping — rowMetaMap', () => {
             }
         });
     });
+
+    it('populates groupLabel from groupingValueFormatter when provided', () => {
+        const formatter = ({ field, value }: { field: string; value: unknown }) =>
+            `${String(field).toUpperCase()}: ${String(value)}`;
+        const columns = [{ field: 'dept', groupingValueFormatter: formatter }];
+        const { result } = renderHook(() =>
+            useRowGrouping({ ...BASE_PARAMS, columns })
+        );
+        const map = result.current.rowMetaMap;
+        let foundFormatted = false;
+        map.forEach((meta) => {
+            if (meta.isGroupRow) {
+                expect(meta.groupLabel).toMatch(/^DEPT:/);
+                foundFormatted = true;
+            }
+        });
+        expect(foundFormatted).toBe(true);
+    });
+
+    it('uses default field: value label when groupingValueFormatter is absent', () => {
+        const { result } = renderHook(() => useRowGrouping(BASE_PARAMS));
+        const map = result.current.rowMetaMap;
+        map.forEach((meta) => {
+            if (meta.isGroupRow) {
+                expect(meta.groupLabel).toMatch(/^dept:/);
+            }
+        });
+    });
+});
+
+describe('useRowGrouping — groupable: false', () => {
+    it('skips a column with groupable:false — no group rows created for that field', () => {
+        const columns = [{ field: 'dept', groupable: false as const }];
+        const { result } = renderHook(() =>
+            useRowGrouping({ ...BASE_PARAMS, columns })
+        );
+        const map = result.current.rowMetaMap;
+        // With groupable:false on 'dept', no group rows should exist
+        let groupCount = 0;
+        map.forEach((meta) => { if (meta.isGroupRow) groupCount++; });
+        expect(groupCount).toBe(0);
+    });
+
+    it('still groups when groupable is true (explicit)', () => {
+        const columns = [{ field: 'dept', groupable: true as const }];
+        const { result } = renderHook(() =>
+            useRowGrouping({ ...BASE_PARAMS, columns })
+        );
+        const map = result.current.rowMetaMap;
+        let groupCount = 0;
+        map.forEach((meta) => { if (meta.isGroupRow) groupCount++; });
+        expect(groupCount).toBe(2);
+    });
 });

package/lib/hooks/useRowGrouping.ts

@@ -7,7 +7,8 @@ import type {
     GridTreeNode,
     GridFilterModel,
     GridSortItem,
-    GridRowMeta
+    GridRowMeta,
+    GridColDef
 } from '../types';
 import { isRowMatchingFilter } from '../utils/filtering';
 import { compareValues } from '../utils/sorting';
@@ -15,6 +16,7 @@ import { compareValues } from '../utils/sorting';
 export interface UseRowGroupingParams<R extends GridRowModel> {
     rows: R[];
     getRowId: (row: R) => GridRowId;
+    columns?: GridColDef<R>[];
     rowGroupingModel?: GridRowGroupingModel;
     aggregationModel?: GridAggregationModel;
     defaultGroupingExpansionDepth?: number;
@@ -38,6 +40,7 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
     const {
         rows,
         getRowId,
+        columns,
         rowGroupingModel = EMPTY_ROW_GROUPING_MODEL,
         aggregationModel = EMPTY_AGGREGATION_MODEL,
         defaultGroupingExpansionDepth = 0,
@@ -46,6 +49,12 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
         getAggregationPosition = defaultGetAggregationPosition
     } = params;
 
+    const columnsLookup = useMemo(() => {
+        const map = new Map<string, GridColDef<R>>();
+        (columns ?? []).forEach(col => map.set(col.field, col));
+        return map;
+    }, [columns]);
+
     const [expandedGroupIds, setExpandedGroupIds] = useState<Set<GridRowId>>(new Set());
 
     const { treeNodes, rootIds, groupingRows } = useMemo(() => {
@@ -82,6 +91,13 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
             }
 
             const field = rowGroupingModel[depth];
+
+            // Skip fields where the column has explicitly opted out of grouping.
+            const colDef = columnsLookup.get(field);
+            if (colDef && colDef.groupable === false) {
+                return groupRows(currentRows, depth + 1, parentId);
+            }
+
             const groups = new Map<string, R[]>();
 
             // Group current rows by value of the current field
@@ -143,7 +159,9 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
                     aggregatedValues,
                     isExpanded: false,
                     children: [], 
-                    label: `${field}: ${String(rawValue)}` 
+                    label: colDef?.groupingValueFormatter
+                        ? colDef.groupingValueFormatter({ field, value: rawValue })
+                        : `${field}: ${String(rawValue)}` 
                 };
 
                 treeNode.aggregationPosition = getAggregationPosition(treeNode);
@@ -165,7 +183,7 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
 
         return { treeNodes, rootIds, groupingRows };
 
-    }, [rows, rowGroupingModel, aggregationModel, getRowId, getAggregationPosition]);
+    }, [rows, rowGroupingModel, aggregationModel, getRowId, getAggregationPosition, columnsLookup]);
 
     useEffect(() => {
         if (defaultGroupingExpansionDepth === -1) {
@@ -307,6 +325,7 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
                 treeDepth: node.depth,
                 groupingField: node.groupingField,
                 groupingValue: node.groupingValue,
+                groupLabel: node.label,
                 descendantCount: node.descendantCount,
                 isGroupRow: isGroup,
                 isExpanded: isGroup ? expandedGroupIds.has(id) : undefined,

package/lib/types/index.ts

@@ -29,6 +29,7 @@ export interface GridRowMeta {
     treeDepth?: number;
     groupingField?: string;
     groupingValue?: unknown;
+    groupLabel?: string;
     descendantCount?: number;
     isExpanded?: boolean;
     isGroupRow?: boolean;
@@ -81,16 +82,22 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
   field: string;
   /** Text displayed in the column header. */
   headerName?: string;
-  /** Tooltip or accessible description for the header. */
+  /** Tooltip shown on header hover — used as the column's accessibility label. */
   description?: string;
-
   /** If true, this column can be used as a grouping dimension. */
   groupable?: boolean;
 
+  /**
+   * Custom formatter for the group-header label when this column is used as a grouping field.
+   * Receives the field name and grouped value; return the string to display.
+   * Falls back to `"field: value"` when omitted.
+   */
+  groupingValueFormatter?: (params: { field: string; value: unknown }) => string;
+
   /** If true, this column can be summarized using aggregation functions. */
   aggregable?: boolean;
-  /** List of allowed aggregation functions (e.g., ['sum', 'avg']). */
-  availableAggregationFunctions?: string[]; 
+  /** Restricts which aggregation functions are offered for this column (e.g., ['sum', 'avg']). */
+  availableAggregationFunctions?: string[];
 
   /** Width in pixels or a percentage string. Defaults to automatic calculation. */
   width?: number | string;
@@ -608,6 +615,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   sortModel?: GridSortItem[];
   /** Callback fired when the sorting model changes. */
   onSortModelChange?: (model: GridSortItem[]) => void;
+  /**
+   * When true, clicking any sortable column header appends/cycles that column in the
+   * sort model instead of replacing it — no Shift key required. Plain click still
+   * cycles asc → desc → removed for that column while all other active sort keys stay.
+   * Shift+click continues to work regardless of this prop.
+   */
+  multiSort?: boolean;
 
   /** Filtering mode: 'client' (default) or 'server'. */
   filterMode?: 'client' | 'server';
@@ -641,8 +655,6 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Defines which rows are pinned to the top or bottom. */
   pinnedRows?: GridRowPinning;
-  /** Callback fired when row pinning changes. */
-  onPinnedRowsChange?: (model: GridRowPinning) => void;
 
   /** If true, a column of checkboxes is added for row selection. */
   checkboxSelection?: boolean;
@@ -720,8 +732,6 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Controlled state for row grouping. */
   rowGroupingModel?: GridRowGroupingModel;
-  /** Callback fired when row grouping changes. */
-  onRowGroupingModelChange?: (model: GridRowGroupingModel) => void;
   /** Controlled state for data aggregation (e.g., { salary: 'sum' }). */
   aggregationModel?: GridAggregationModel;
   /** Callback fired when aggregation model changes. */