@opencorestack/opengridx 3.0.0 → 3.1.0

package/lib/hooks/core/gridApiPlaceholder.ts

@@ -1,4 +1,4 @@
-import type { GridApi } from '../../types';
+import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
 
 const noop = () => {};
 
@@ -7,7 +7,7 @@ const noop = () => {};
  * `apiRef.current` is never null (its type says it is not) before the grid has mounted;
  * the grid replaces it with the live API when it mounts.
  */
-export function createGridApiPlaceholder(): GridApi {
+export function createGridApiPlaceholder<R extends GridValidRowModel = GridRowModel>(): GridApi<R> {
     return {
         getRow: () => null,
         getAllRows: () => [],
@@ -29,6 +29,8 @@ export function createGridApiPlaceholder(): GridApi {
         setPage: noop,
         setPageSize: noop,
         scrollToIndexes: noop,
+        autosizeColumn: noop,
+        autosizeColumns: noop,
         copySelectedRows: () => Promise.resolve(),
     };
 }

package/lib/hooks/core/useGridApiRef.ts

@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
-import type { GridApi } from '../../types';
+import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
 import { createGridApiPlaceholder } from './gridApiPlaceholder';
 
 /**
@@ -15,8 +15,11 @@ import { createGridApiPlaceholder } from './gridApiPlaceholder';
  * which matches `DataGridProps.apiRef` under both @types/react 18 and 19. Left to inference,
  * React 19's types emit `RefObject<GridApi>`, which React 18's types treat as read-only and
  * nullable, so `apiRef={useGridApiRef()}` failed to type-check on React 18.
+ *
+ * Pass your row type to have the row getters typed: `useGridApiRef<Invoice>().current.getRow(id)`
+ * returns `Invoice | null`.
  */
-export function useGridApiRef(): MutableRefObject<GridApi> {
-    const [placeholder] = useState(createGridApiPlaceholder);
-    return useRef<GridApi>(placeholder);
+export function useGridApiRef<R extends GridValidRowModel = GridRowModel>(): MutableRefObject<GridApi<R>> {
+    const [placeholder] = useState(createGridApiPlaceholder<R>);
+    return useRef<GridApi<R>>(placeholder);
 }

package/lib/hooks/core/useGridColumnAutosize.ts

@@ -0,0 +1,52 @@
+import { useCallback, useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import type { GridApi, GridColDef, GridValidRowModel } from '../../types';
+import { clampAutosizeWidth, measureColumnContentWidth } from '../../utils/columnAutosize';
+
+export interface UseGridColumnAutosizeParams<R extends GridValidRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    /** The grid root (`.ogx`). */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Every column the grid knows (hidden ones are measured as not rendered and left alone). */
+    columns: readonly GridColDef<R>[];
+    /** The width setter a manual resize uses. */
+    onColumnResize: (field: string, width: number) => void;
+}
+
+/**
+ * Auto-sizing of columns to their content: the header and the cells in the current render window,
+ * measured in the DOM, clamped to `minWidth` / `maxWidth`. Columns with `resizable: false` are left
+ * alone. A flex column gets a fixed width, like after a manual resize. Installs `autosizeColumn` /
+ * `autosizeColumns` on the API and returns `autosizeColumn` for the resize handle.
+ */
+export function useGridColumnAutosize<R extends GridValidRowModel>(params: UseGridColumnAutosizeParams<R>): (field: string) => void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const autosizeColumns = useCallback((fields?: readonly string[]) => {
+        const { containerRef, columns, onColumnResize } = latestRef.current;
+        const root = containerRef.current;
+        if (!root) return;
+        // Measure every column first: the reads all see the same layout, then the widths are set.
+        const widths: Array<[string, number]> = [];
+        for (const field of fields ?? columns.map(c => c.field)) {
+            const colDef = columns.find(c => c.field === field);
+            if (!colDef || colDef.resizable === false) continue;
+            const measured = measureColumnContentWidth(root, field);
+            if (measured !== null) widths.push([field, clampAutosizeWidth(measured, colDef.minWidth, colDef.maxWidth)]);
+        }
+        for (const [field, width] of widths) onColumnResize(field, width);
+    }, []);
+
+    const autosizeColumn = useCallback((field: string) => autosizeColumns([field]), [autosizeColumns]);
+
+    useLayoutEffect(() => {
+        apiRef.current.autosizeColumn = autosizeColumn;
+        apiRef.current.autosizeColumns = autosizeColumns;
+    }, [apiRef, autosizeColumn, autosizeColumns]);
+
+    return autosizeColumn;
+}

package/lib/hooks/core/useGridDevWarnings.ts

@@ -14,11 +14,16 @@ export interface UseGridDevWarningsParams {
     scrollHeight?: number;
     /** `listView` is set but `listViewColumn` is not, so the grid view is shown. */
     listViewWithoutColumn?: boolean;
+    /** Number of items the list view renders (0 when the list view is not shown). It does not virtualize. */
+    listViewRowCount?: number;
 }
 
 // Below this many rows, rendering everything is harmless, so an unbounded container is not worth a warning.
 const UNBOUNDED_WARN_THRESHOLD = 200;
 
+/** The list view renders every item; above this many the page slows down noticeably. */
+export const LIST_VIEW_WARN_THRESHOLD = 2000;
+
 /**
  * Browsers cap element heights (Firefox at about 17.9M px, Chromium and Safari at about 33.5M px):
  * rows laid out below the cap cannot be scrolled to.
@@ -26,12 +31,22 @@ const UNBOUNDED_WARN_THRESHOLD = 200;
 export const MAX_SCROLLABLE_HEIGHT = 17_800_000;
 
 export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
-    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false } = params;
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
     const warnedPaginationRef = useRef(false);
     const warnedUnboundedRef = useRef(false);
     const warnedPinnedRowsRef = useRef(false);
     const warnedHeightRef = useRef(false);
     const warnedListViewRef = useRef(false);
+    const warnedListViewSizeRef = useRef(false);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedListViewSizeRef.current || listViewRowCount <= LIST_VIEW_WARN_THRESHOLD) return;
+        warnedListViewSizeRef.current = true;
+        console.warn(
+            `[OpenGridX] The list view is rendering all ${listViewRowCount} items: it does not virtualize. ` +
+            'Above a few thousand items use `pagination`, server-side loading, or the grid view. See docs/features/list-view.md.'
+        );
+    }, [listViewRowCount]);
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedListViewRef.current || !listViewWithoutColumn) return;
@@ -74,15 +89,18 @@ export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedUnboundedRef.current || autoHeight) return;
-        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount) {
+        // Really unbounded: every row is rendered and the viewport is at least as tall as the rows, so it never scrolls.
+        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount && viewportHeight >= scrollHeight) {
             warnedUnboundedRef.current = true;
             console.warn(
                 `[OpenGridX] The grid viewport is ${Math.round(viewportHeight)}px tall and is rendering all ${totalRowCount} rows, ` +
-                'so row virtualization is effectively off. The grid container has no bounded height: it grows to fit its ' +
-                'content. Give it a fixed height, or if it is a flex child add `min-height: 0`. See docs/features/virtualization.md.'
+                'so row virtualization is effectively off: the grid fills its container, and the container grows to fit every row. ' +
+                'Give the container a definite height (for example `height: 600px` or `100vh`). If the container, or any ancestor ' +
+                'up to the sized one, is a flex or grid item, add `min-height: 0` to it. Alternatively pass a `height` prop, ' +
+                'or `autoHeight` if rendering every row is intended. See docs/features/virtualization.md.'
             );
         }
-    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount]);
+    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount, scrollHeight]);
 }
 
 /**

package/lib/hooks/core/useGridRowPipeline.ts

@@ -103,8 +103,8 @@ export function useGridRowPipeline<R extends GridRowModel>(
     const sortedUnpinnedRows = useMemo<R[]>(() => {
         if (activeHierarchyHandlers) return unpinnedRows;
         if (sortingMode === 'server') return unpinnedRows;
-        return sortRows(unpinnedRows, sortModel, columnLookup) as R[];
-    }, [unpinnedRows, sortModel, activeHierarchyHandlers, sortingMode, columnLookup]);
+        return sortRows(unpinnedRows, sortModel, columnLookup, getRowId) as R[];
+    }, [unpinnedRows, sortModel, activeHierarchyHandlers, sortingMode, columnLookup, getRowId]);
 
     const isClientPaged = pagination && paginationMode !== 'server';
     const pageSize = normalizePageSize(effectivePaginationModel.pageSize);

package/lib/hooks/useRowGrouping.ts

@@ -362,10 +362,20 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
 
         const readSortValue = (id: GridRowId, sortItem: GridSortItem): GridSortValue => {
             const node = treeNodes.get(id);
-            if (node && groupRowVariants.has(id)) {
+            const groupVariants = groupRowVariants.get(id);
+            if (node && groupVariants) {
                 const groupingField = node.groupingField ?? '';
                 if (sortItem.field === groupingField || sortItem.field === labelField) {
-                    return { value: node.groupingValue, type: columnLookup?.byField.get(groupingField)?.type };
+                    const groupingColDef = columnLookup?.byField.get(groupingField);
+                    const comparator = groupingColDef?.sortComparator;
+                    return {
+                        value: node.groupingValue,
+                        type: groupingColDef?.type,
+                        comparator,
+                        params: comparator
+                            ? { id, field: groupingField, row: groupVariants.inline, value: node.groupingValue }
+                            : undefined,
+                    };
                 }
                 if (node.aggregatedValues && Object.prototype.hasOwnProperty.call(node.aggregatedValues, sortItem.field)) {
                     return { value: node.aggregatedValues[sortItem.field], type: columnLookup?.byField.get(sortItem.field)?.type };
@@ -374,7 +384,14 @@ export function useRowGrouping<R extends GridRowModel>(params: UseRowGroupingPar
             }
             const row = rowLookup.get(id);
             const colDef = columnLookup?.byField.get(sortItem.field);
-            return { value: row ? getCellValue(row, sortItem.field, colDef) : undefined, type: colDef?.type };
+            const value = row ? getCellValue(row, sortItem.field, colDef) : undefined;
+            const comparator = colDef?.sortComparator;
+            return {
+                value,
+                type: colDef?.type,
+                comparator,
+                params: comparator && row ? { id, field: sortItem.field, row, value } : undefined,
+            };
         };
 
         const result: R[] = [];

package/lib/hooks/useTreeData.ts

@@ -333,7 +333,14 @@ export function useTreeData<R extends GridRowModel>(props: UseTreeDataProps<R>)
             }
             const row = rowLookup.get(id);
             const colDef = columnLookup?.byField.get(sortItem.field);
-            return { value: row ? getCellValue(row, sortItem.field, colDef) : undefined, type: colDef?.type };
+            const value = row ? getCellValue(row, sortItem.field, colDef) : undefined;
+            const comparator = colDef?.sortComparator;
+            return {
+                value,
+                type: colDef?.type,
+                comparator,
+                params: comparator && row ? { id, field: sortItem.field, row, value } : undefined,
+            };
         };
 
         const result: GridRowModel[] = [];

package/lib/index.ts

@@ -89,6 +89,7 @@ export type {
     GridRenderEditCellParams,
     GridRenderHeaderParams,
     GridValueGetterParams,
+    GridSortCellParams,
     GridValueSetterParams,
     GridValueFormatterParams,
     GridRowParams,

package/lib/types/index.ts

@@ -172,6 +172,16 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @since v3.0
    */
   valueSetter?(params: GridValueSetterParams<R>): R;
+  /**
+   * Custom ascending comparator for client-side sorting by this column, used instead of the built-in
+   * type-aware comparison. `v1` / `v2` are the cell values (`valueGetter` applied) and **include
+   * `null` / `undefined`**, so the comparator decides where empty values go. The grid reverses the
+   * result for 'desc' and chains it with the other sort keys in a multi-sort. Row grouping uses the
+   * grouping column's comparator to order groups by their grouping value. A comparator that throws
+   * or returns NaN is read as 0 (with a one-time dev warning). Ignored with `sortingMode="server"`.
+   * @since v3.1
+   */
+  sortComparator?(v1: unknown, v2: unknown, params1: GridSortCellParams<R>, params2: GridSortCellParams<R>): number;
   /** Function to format a value into a human-readable string. */
   valueFormatter?(params: GridValueFormatterParams<R>): string;
   /** Custom component or element to render in the cell. */
@@ -262,6 +272,18 @@ export interface GridColumnGroup {
 export type GridColumnGroupingModel = GridColumnGroup[];
 
 
+/**
+ * Parameters passed to `GridColDef.sortComparator` for each side of a comparison. For a row-grouping
+ * group row, `row` is the synthetic group row and `value` its grouping value.
+ * @since v3.1
+ */
+export interface GridSortCellParams<R extends GridValidRowModel = GridRowModel> {
+  id: GridRowId;
+  field: string;
+  row: R;
+  value: unknown;
+}
+
 /** Parameters passed to the `valueGetter` function. */
 export interface GridValueGetterParams<R extends GridValidRowModel = GridRowModel> {
   /** The row object. */
@@ -912,8 +934,11 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   /** Callback fired when scrolling reaches the bottom of the grid viewport. */
   onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
 
-  /** Advanced: Reactive reference to the internal API for imperative control. */
-  apiRef?: React.MutableRefObject<GridApi>;
+  /**
+   * Advanced: reactive reference to the internal API for imperative control. Pass
+   * `useGridApiRef<MyRow>()` to have the row getters typed as `MyRow`; a plain `useGridApiRef()` also works.
+   */
+  apiRef?: React.MutableRefObject<GridApi<R>> | React.MutableRefObject<GridApi>;
 
   /** Custom components to replace internal grid parts. */
   slots?: {
@@ -1052,18 +1077,22 @@ export type GridDetailPanelHeight = number | 'auto';
  * The Imperative API for interacting with the DataGrid.
  * Access this via the `apiRef` prop or a ref passed to the component.
  */
-export interface GridApi {
+/**
+ * The imperative grid API. `R` types the row getters (`getRow`, `getAllRows`, `getVisibleRows`,
+ * `getAllFilteredRows`); it defaults to `GridRowModel`, so `GridApi` alone keeps working.
+ */
+export interface GridApi<R extends GridValidRowModel = GridRowModel> {
   /**
    * Returns the row model with the given ID.
    * @param id The row unique ID.
    */
-  getRow: (id: GridRowId) => GridRowModel | null;
+  getRow: (id: GridRowId) => R | null;
   /** Returns all rows currently loaded into the grid. */
-  getAllRows: () => GridRowModel[];
+  getAllRows: () => R[];
   /** Returns all rows currently visible after filtering and sorting. */
-  getVisibleRows: () => GridRowModel[];
+  getVisibleRows: () => R[];
   /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
-  getAllFilteredRows: () => GridRowModel[];
+  getAllFilteredRows: () => R[];
   /**
    * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
    * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a
@@ -1120,6 +1149,16 @@ export interface GridApi {
   /** Scrolls the grid viewport to a specific row or column index. */
   scrollToIndexes: (params: { rowIndex?: number; colIndex?: number }) => void;
 
+  /**
+   * Sizes a column to fit its header and the cells rendered right now (the virtualization window),
+   * clamped to `minWidth` (default 50px) / `maxWidth`, like double-clicking its resize handle.
+   * Does nothing for `resizable: false` columns or a column that is not rendered.
+   * A flex column gets a fixed width. @since v3.1
+   */
+  autosizeColumn: (field: string) => void;
+  /** `autosizeColumn` for several columns (default: every column). @since v3.1 */
+  autosizeColumns: (fields?: readonly string[]) => void;
+
   /**
    * Programmatically copies all currently selected rows to the clipboard as TSV: every selected
    * row that passes the filter (other pages, collapsed groups and pinned rows included), with the

package/lib/utils/columnAutosize.ts

@@ -0,0 +1,56 @@
+import { DEFAULT_MIN_COLUMN_WIDTH } from '../components/ColumnResizeHandle/clampResizeWidth';
+
+/** The grid root an element belongs to, so a nested grid (in a detail panel) is never measured. */
+const ROOT_SELECTOR = '.ogx';
+
+/**
+ * The width `content` needs to show without clipping, plus the horizontal padding and borders of
+ * `cell`. `content` is laid out at `max-content` for the read and restored right after, so the
+ * reading works for a column that is too wide (shrinks) as well as one that is too narrow (grows).
+ */
+function measureCell(cell: HTMLElement, content: HTMLElement): number {
+    const saved = content.style.cssText;
+    content.style.width = 'max-content';
+    content.style.minWidth = '0';
+    content.style.maxWidth = 'none';
+    content.style.flex = 'none';
+    const contentWidth = content.getBoundingClientRect().width;
+    content.style.cssText = saved;
+
+    const style = getComputedStyle(cell);
+    const extra = [style.paddingLeft, style.paddingRight, style.borderLeftWidth, style.borderRightWidth]
+        .reduce((sum, value) => sum + (parseFloat(value) || 0), 0);
+    return contentWidth + extra;
+}
+
+/**
+ * The width a column needs to fit its header and the cells rendered right now (the virtualization
+ * window, pinned rows included), measured in the DOM. Cells spanning several columns and cells
+ * hidden by a row span are skipped. Returns null when nothing of the column is rendered.
+ */
+export function measureColumnContentWidth(root: HTMLElement, field: string): number | null {
+    const escaped = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(field) : field.replace(/"/g, '\\"');
+    const ownedByRoot = (el: Element) => el.closest(ROOT_SELECTOR) === root;
+    let width: number | null = null;
+    const take = (w: number) => { width = width === null ? w : Math.max(width, w); };
+
+    root.querySelectorAll<HTMLElement>(`[role="columnheader"][data-field="${escaped}"]`).forEach(header => {
+        if (!ownedByRoot(header)) return;
+        const content = header.querySelector<HTMLElement>('.ogx__header-cell-content');
+        if (content) take(measureCell(header, content));
+    });
+
+    root.querySelectorAll<HTMLElement>(`[role="gridcell"][data-field="${escaped}"]`).forEach(cell => {
+        if (!ownedByRoot(cell) || cell.hasAttribute('aria-colspan')) return;
+        const content = cell.querySelector<HTMLElement>(':scope > .ogx__cell-content');
+        if (content) take(measureCell(cell, content));
+    });
+
+    return width === null ? null : Math.ceil(width);
+}
+
+/** Clamps an autosized width to the column's `minWidth` (default 50px) and `maxWidth`. */
+export function clampAutosizeWidth(width: number, minWidth?: number, maxWidth?: number): number {
+    const min = minWidth ?? DEFAULT_MIN_COLUMN_WIDTH;
+    return Math.max(min, Math.min(maxWidth ?? Infinity, width));
+}

package/lib/utils/pivot/index.ts

@@ -18,7 +18,7 @@ import {
     isEmptyAggregateValue,
 } from '../aggregation';
 import { createRowFilter } from '../filtering';
-import { compareValues } from '../sorting';
+import { applySortDirection, callSortComparator, compareValues } from '../sorting';
 import { buildColumnLookup } from '../columnLookup';
 import { getCellValue, getFormattedValue } from '../values';
 
@@ -256,7 +256,16 @@ export function computePivot(
     if (sortModel && sortModel.length > 0) {
         kept = [...kept].sort((a, b) => {
             for (const item of sortModel) {
-                const c = compareValues(sortValue(a.row, item.field), sortValue(b.row, item.field), item.sort, typeOf(item.field));
+                const va = sortValue(a.row, item.field);
+                const vb = sortValue(b.row, item.field);
+                const comparator = isRowField(item.field) ? colDefMap.get(item.field)?.sortComparator : undefined;
+                const c = comparator
+                    ? applySortDirection(callSortComparator(
+                        comparator,
+                        { id: a.row.id, field: item.field, row: a.row, value: va },
+                        { id: b.row.id, field: item.field, row: b.row, value: vb },
+                    ), item.sort)
+                    : compareValues(va, vb, item.sort, typeOf(item.field));
                 if (c !== 0) return c;
             }
             return 0;

package/lib/utils/sorting/index.ts

@@ -1,7 +1,7 @@
 
-import type { GridColDef, GridRowModel, GridSortDirection, GridSortItem } from '../../types';
+import type { GridColDef, GridRowId, GridRowModel, GridSortCellParams, GridSortDirection, GridSortItem } from '../../types';
 import type { GridColumnLookup } from '../columnLookup';
-import { getCellValue, toDate, toNumber } from '../values';
+import { getCellValue, toDate, toNumber, warnCallbackFailure } from '../values';
 
 /**
  * Language-aware string order: accented letters sort next to their base letter instead of after
@@ -68,7 +68,8 @@ function compareSortKeys(a: SortKey, b: SortKey): number {
   return a.num < b.num ? -1 : a.num > b.num ? 1 : 0;
 }
 
-function applyDirection(comparison: number, direction: 'asc' | 'desc'): number {
+/** Reverse an ascending comparison for 'desc'. */
+export function applySortDirection(comparison: number, direction: 'asc' | 'desc'): number {
   if (comparison === 0) return 0;
   return direction === 'asc' ? comparison : -comparison;
 }
@@ -83,27 +84,62 @@ export function compareValues(
   direction: 'asc' | 'desc',
   type?: GridColDef['type']
 ): number {
-  return applyDirection(compareSortKeys(toSortKey(a, type), toSortKey(b, type)), direction);
+  return applySortDirection(compareSortKeys(toSortKey(a, type), toSortKey(b, type)), direction);
 }
 
+/** A column's `sortComparator`, as the sorting utils call it. */
+export type GridSortComparatorFn = NonNullable<GridColDef['sortComparator']>;
+
+/**
+ * Call a consumer `sortComparator`, containing failures: a throw or a non-finite result reads as 0
+ * (equal), with a one-time dev warning per column, so one bad comparison cannot break the sort.
+ */
+export function callSortComparator(
+  comparator: GridSortComparatorFn,
+  a: GridSortCellParams,
+  b: GridSortCellParams
+): number {
+  let result: number;
+  try {
+    result = comparator(a.value, b.value, a, b);
+  } catch (error) {
+    warnCallbackFailure(`sortComparator:${a.field}`, `sortComparator for column "${a.field}" threw; the values are treated as equal`, error);
+    return 0;
+  }
+  if (typeof result !== 'number' || Number.isNaN(result)) {
+    warnCallbackFailure(`sortComparator:${a.field}:nan`, `sortComparator for column "${a.field}" returned ${String(result)}; the values are treated as equal`, undefined);
+    return 0;
+  }
+  return result;
+}
+
+const defaultRowId = (row: GridRowModel): GridRowId => row.id;
+
 /**
  * Compare two rows by a sort model, reading cells through `valueGetter` and using each column's
- * `type`. Returns 0 when every key is equal.
+ * `type` (or its `sortComparator`). Returns 0 when every key is equal.
  */
 export function compareRowsBySortModel(
   a: GridRowModel,
   b: GridRowModel,
   sortModel: readonly GridSortItem[],
-  columns?: GridColumnLookup
+  columns?: GridColumnLookup,
+  getRowId: (row: GridRowModel) => GridRowId = defaultRowId
 ): number {
   for (const sortItem of sortModel) {
     const colDef = columns?.byField.get(sortItem.field);
-    const comparison = compareValues(
-      getCellValue(a, sortItem.field, colDef),
-      getCellValue(b, sortItem.field, colDef),
-      sortItem.sort,
-      colDef?.type
-    );
+    const va = getCellValue(a, sortItem.field, colDef);
+    const vb = getCellValue(b, sortItem.field, colDef);
+    const comparison = colDef?.sortComparator
+      ? applySortDirection(
+          callSortComparator(
+            colDef.sortComparator,
+            { id: getRowId(a), field: sortItem.field, row: a, value: va },
+            { id: getRowId(b), field: sortItem.field, row: b, value: vb }
+          ),
+          sortItem.sort
+        )
+      : compareValues(va, vb, sortItem.sort, colDef?.type);
     if (comparison !== 0) return comparison;
   }
   return 0;
@@ -112,28 +148,42 @@ export function compareRowsBySortModel(
 export function sortRows<R extends GridRowModel>(
   rows: R[],
   sortModel: GridSortItem[],
-  columns?: GridColumnLookup
+  columns?: GridColumnLookup,
+  getRowId: (row: R) => GridRowId = defaultRowId
 ): R[] {
   if (sortModel.length === 0) {
     return rows;
   }
   return sortItemsBySortModel(rows, sortModel, (row, sortItem) => {
     const colDef = columns?.byField.get(sortItem.field);
-    return { value: getCellValue(row, sortItem.field, colDef), type: colDef?.type };
+    const value = getCellValue(row, sortItem.field, colDef);
+    return {
+      value,
+      type: colDef?.type,
+      comparator: colDef?.sortComparator,
+      params: colDef?.sortComparator ? { id: getRowId(row), field: sortItem.field, row, value } : undefined,
+    };
   });
 }
 
-/** The value an item sorts by for one sort key, and the column type used to compare it. */
+/** The value an item sorts by for one sort key, and how to compare it. */
 export interface GridSortValue {
   value: unknown;
   type?: GridColDef['type'];
+  /**
+   * The column's `sortComparator`. Two items are compared with it when both carry the same one
+   * (with their `params`); otherwise the built-in comparison of `value` / `type` applies.
+   */
+  comparator?: GridSortComparatorFn;
+  /** The params passed to `comparator` for this item; `value` here is what the comparator sees. */
+  params?: GridSortCellParams;
 }
 
 /**
- * Stable sort of any items by a sort model. `readValue` gives the value (and column type) an item
- * sorts by for each sort key; it is called once per item and key, not once per comparison. Used by
- * the flat pipeline and by tree data / row grouping, whose synthetic group rows sort by their
- * grouping value or label instead of a cell.
+ * Stable sort of any items by a sort model. `readValue` gives the value (and column type or
+ * comparator) an item sorts by for each sort key; it is called once per item and key, not once per
+ * comparison. Used by the flat pipeline and by tree data / row grouping, whose synthetic group rows
+ * sort by their grouping value or label instead of a cell.
  */
 export function sortItemsBySortModel<T>(
   items: readonly T[],
@@ -146,15 +196,18 @@ export function sortItemsBySortModel<T>(
 
   // Read and normalize every sort value once, instead of calling valueGetter and parsing dates
   // O(n log n) times inside the comparator.
-  const keys = sortModel.map(sortItem => items.map(item => {
-    const { value, type } = readValue(item, sortItem);
-    return toSortKey(value, type);
-  }));
+  const values = sortModel.map(sortItem => items.map(item => readValue(item, sortItem)));
+  const keys = values.map(column => column.map(({ value, type }) => toSortKey(value, type)));
 
   const order = items.map((_, index) => index);
   order.sort((ia, ib) => {
     for (let k = 0; k < sortModel.length; k++) {
-      const comparison = applyDirection(compareSortKeys(keys[k][ia], keys[k][ib]), sortModel[k].sort);
+      const a = values[k][ia];
+      const b = values[k][ib];
+      const ascending = a.comparator && a.comparator === b.comparator && a.params && b.params
+        ? callSortComparator(a.comparator, a.params, b.params)
+        : compareSortKeys(keys[k][ia], keys[k][ib]);
+      const comparison = applySortDirection(ascending, sortModel[k].sort);
       if (comparison !== 0) return comparison;
     }
     return ia - ib;