@opencorestack/opengridx 3.0.1 → 3.1.0

package/docs/API_REFERENCE.md

@@ -294,6 +294,8 @@ Access these methods via the `apiRef` prop.
 | `setPage(page)` | `void` | Change current page (0-indexed). Fires `onPaginationModelChange`. |
 | `setPageSize(pageSize)` | `void` | Change the page size and go to page 0. Fires `onPaginationModelChange`. |
 | `scrollToIndexes(params)` | `void` | Scroll to specific row/column index. Uses the current layout, also when called from a layout effect right after an update (v3.0+). |
+| `autosizeColumn(field)` | `void` | Fit a column to its header and the cells in the current render window, clamped to `minWidth` (default 50px) / `maxWidth`; same as double-clicking its resize handle. No-op for `resizable: false` or a column that is not rendered. A flex column gets a fixed width (v3.1.0+). |
+| `autosizeColumns(fields?)` | `void` | `autosizeColumn` for several columns; every column when `fields` is omitted (v3.1.0+). |
 | `getAllColumns()` | `GridColDef[]` | Get all defined columns. |
 | `getAggregationResult()` | `Record<string, unknown> \| null` | Get current aggregation results (`null` without an `aggregationModel`, and in pivot mode). Live in a parent's `useLayoutEffect` on mount and current after every update (v3.0+; before, it was installed in a passive effect). The same holds for `getAggregationModel()` and `getGroupedExportRows()`. |
 | `getAggregationModel()` | `GridAggregationModel \| null` | Get the active aggregation configuration. |
@@ -391,8 +393,9 @@ Span values are floored; `Infinity` means "to the end"; `NaN`, `0` and negative
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `sortable` | `boolean` | `true` | Enable/disable sorting for this column. |
+| `sortComparator` | `(v1, v2, params1, params2) => number` | — | Custom ascending comparator for client-side sorting (v3.1.0+). `v1`/`v2` are `valueGetter` values **including `null`/`undefined`**; `params` are `GridSortCellParams` `{ id, field, row, value }`. Negated for `desc`, chained in multi-sort, used for group ordering under row grouping, tree-data siblings and pivot row labels. Throw / `NaN` reads as 0 (dev warning once). Ignored with `sortingMode="server"`. |
 | `filterable` | `boolean` | `true` | Enable/disable filtering for this column. `false` also removes it from the quick-filter search. |
-| `resizable` | `boolean` | `true` | Allow the user to drag-resize this column. |
+| `resizable` | `boolean` | `true` | Allow the user to drag-resize this column; double-click the handle (or Enter on it) to auto-size to content (v3.1.0+). |
 | `hideable` | `boolean` | `true` | Allow the user to hide this column from the UI. `false` removes it from the Columns panel (unless `showNonHideableColumns`) and removes **Hide Column** from its column menu. |
 | `pinnable` | `boolean` | `true` | Allow this column to be pinned via the UI. `false` removes the pin actions from its column menu. Does not affect drag-reordering (v3.0+). |
 | `disableColumnMenu` | `boolean` | `false` | Hide the column header kebab/context menu. |

package/docs/architecture/datagrid-orchestration.md

@@ -56,6 +56,7 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | 29 | `useGridSpanning` | `hooks/features/useGridSpanning.ts` | Row/column spans |
 | 30 | `useGridClipboardApi` | `hooks/core/useGridClipboardApi.ts` | Ctrl/Cmd+C and `copySelectedRows` |
 | 31 | `useGridScrollToIndexesApi` | `hooks/core/useGridScrollToIndexesApi.ts` | `scrollToIndexes` |
+| 31a | `useGridColumnAutosize` | `hooks/core/useGridColumnAutosize.ts` | `autosizeColumn` / `autosizeColumns` on the API, and the resize handle's auto-size handler (v3.1) |
 | 32 | `useGridViewport` | `hooks/core/useGridViewport.ts` | Scroll sync, viewport measurement, viewport callback ref |
 | 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window |
 | 34 | `useGridSortHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Header sort / shift-sort |

package/docs/components/column-resize.md

@@ -8,7 +8,8 @@ OpenGridX supports dynamic column resizing, allowing users to adjust the width o
 - **Keyboard**: with a column header focused, **Alt+ArrowRight** / **Alt+ArrowLeft** widen / narrow the column by 10px (hold **Shift** for 50px). The handle is a `role="separator"` that reports the width in `aria-valuenow` (and `aria-valuemin` / `aria-valuemax`).
 - **Constraints**: `minWidth` and `maxWidth` from your `GridColDef` apply. Without `minWidth` a column can be narrowed to 50px; a column that is already narrower (a 30px icon column) is never snapped up to 50px. Without `maxWidth` there is no upper limit.
 - **Clicks are not resizes**: pressing and releasing the handle without moving it changes nothing (a flex column stays flex), and ending a resize with the pointer over the header never sorts the column.
-- **Double-click** does nothing (it is swallowed, so it does not sort). There is no auto-size to content.
+- **Double-click to auto-size** (v3.1.0+): double-clicking the handle fits the column to its content — the header (title, sort icon, menu button) and the cells rendered right now, i.e. the rows and pinned rows in the current virtualization window, not the whole data set. The width is clamped to `minWidth` (default 50px) and `maxWidth`; a flex column gets a fixed width, like after a manual drag. The double-click never sorts. With the handle focused, **Enter** does the same. Columns with `resizable: false` have no handle and are never auto-sized.
+- **Programmatic auto-size**: `apiRef.current.autosizeColumn(field)` and `apiRef.current.autosizeColumns(fields?)` (every column when `fields` is omitted) use the same measurement. The new width lands in `columnWidths` state like a drag, so `onStateChange` reports it; there is no dedicated resize callback.
 
 ---
 
@@ -34,6 +35,17 @@ const columns: GridColDef[] = [
 ];
 ```
 
+### Auto-size to content
+
+```tsx
+const apiRef = useGridApiRef();
+
+<DataGrid apiRef={apiRef} rows={rows} columns={columns} />
+<button onClick={() => apiRef.current.autosizeColumns()}>Fit all columns</button>
+```
+
+Measurement reads the DOM (each cell's `.ogx__cell-content` laid out at `max-content`, plus the cell's padding and borders), so only rendered rows count: scroll first, or turn off virtualization for a small grid, if off-screen rows are wider. Cells that span several columns (`colSpan`) are skipped.
+
 ---
 
 ## ⚙️ How it Works

package/docs/features/sorting-pagination.md

@@ -48,6 +48,32 @@ Each active sort column shows a numbered priority badge (`1`, `2`, `3`…) next
 - A column that mixes kinds of value (numbers and strings, say) is ordered by kind first — numbers, dates, booleans, strings — so the order does not depend on the input order.
 - Ties keep the rows' original order.
 
+### Custom comparator: `sortComparator` (v3.1.0+)
+
+Give a column `sortComparator(v1, v2, params1, params2)` to replace the built-in comparison for that column. Return a negative number when `v1` sorts before `v2` **in ascending order**, a positive number when after, `0` when equal.
+
+```tsx
+const SIZE_ORDER: Record<string, number> = { S: 0, M: 1, L: 2, XL: 3 };
+
+const columns: GridColDef<Product>[] = [
+  {
+    field: 'size',
+    sortComparator: (a, b) => (SIZE_ORDER[String(a)] ?? 99) - (SIZE_ORDER[String(b)] ?? 99),
+  },
+];
+```
+
+- `v1` / `v2` are the cell values **after `valueGetter`** (the same values the built-in sort reads). `params1` / `params2` are `{ id, field, row, value }` (`GridSortCellParams`), for tie-breaking on other fields of the row.
+- **The comparator sees every value, including `null` and `undefined`**, so you decide where empty values go. The built-in "empty values last in asc" rule does not apply to a column with a comparator. (Why: a custom order often has its own idea of "empty" — `'N/A'`, `0`, a sentinel — and hiding nulls from the comparator would make those impossible to place consistently with real nulls.)
+- **Direction**: write the ascending order only. For `desc` the grid negates the result, so values the comparator puts last in asc (nulls, typically) come first in desc — the same as the built-in behaviour.
+- **Multi-sort**: the comparator is one key in the chain; when it returns `0` the next sort key decides, then the original row order.
+- **Row grouping**: sorting by the grouping column (or by the grouping/label column) orders the groups by their grouping value using the grouping column's comparator; for a group row, `params.row` is the synthetic group row. Leaf rows inside a group use the sorted column's comparator.
+- **Tree data**: siblings are sorted with the comparator at every level. Auto-created parents (no row of their own) are compared by label with the built-in comparison.
+- **Pivot**: sorting a pivot row-label column uses that source column's comparator on the label values.
+- Everything that reuses the pipeline order uses it too: `apiRef.getAllFilteredRows()`, exports, clipboard.
+- A comparator that throws, or returns `NaN`, reads as `0` (equal) with a one-time dev warning per column; the grid does not crash.
+- **Ignored with `sortingMode="server"`**: the server sorts, the grid shows `rows` as given.
+
 ```tsx
 // Controlled multi-sort — set programmatically or drive from UI with multiSort:
 const [sortModel, setSortModel] = useState<GridSortItem[]>([

package/docs/migration/v2-to-v3.md

@@ -284,7 +284,7 @@ Multi-sort:
 
 **Who is affected:** apps with snapshot tests of sorted output, or server code that expects the old client order.
 
-**Fix it:** update the snapshots. There is no per-column comparator; to sort by a different key, return that key from a `valueGetter` and format it for display with `valueFormatter` (or sort on the server with `sortingMode="server"`):
+**Fix it:** update the snapshots. Since **v3.1.0** a column can take a custom `sortComparator(v1, v2, params1, params2)` (see `docs/features/sorting-pagination.md`), which is the simplest way to get a custom order. On 3.0.x there is no per-column comparator; to sort by a different key, return that key from a `valueGetter` and format it for display with `valueFormatter` (or sort on the server with `sortingMode="server"`):
 
 ```tsx
 import type { GridColDef, GridRowModel } from '@opencorestack/opengridx';

package/lib/components/ColumnResizeHandle/ColumnResizeHandle.tsx

@@ -6,6 +6,8 @@ export interface ColumnResizeHandleProps {
     field: string;
     currentWidth: number;
     onResize: (field: string, newWidth: number) => void;
+    /** Fits the column to its content: called on double-click and on Enter. */
+    onAutosize?: (field: string) => void;
     /** Defaults to 50 (the layout's default minimum), or the current width if that is smaller. */
     minWidth?: number;
     /** Defaults to no limit. */
@@ -43,7 +45,7 @@ function suppressNextClick(): void {
 }
 
 export function ColumnResizeHandle(props: ColumnResizeHandleProps) {
-    const { field, currentWidth, onResize, minWidth, maxWidth, edge = 'end' } = props;
+    const { field, currentWidth, onResize, onAutosize, minWidth, maxWidth, edge = 'end' } = props;
     const [isDragging, setIsDragging] = useState(false);
     const activeRef = useRef<ActiveResize | null>(null);
 
@@ -103,17 +105,24 @@ export function ColumnResizeHandle(props: ColumnResizeHandleProps) {
     }, [field, onResize, widthAt]);
 
     const handleKeyDown = useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === 'Enter' && onAutosize) {
+            event.preventDefault();
+            event.stopPropagation();
+            onAutosize(field);
+            return;
+        }
         if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
         event.preventDefault();
         event.stopPropagation();
         const step = (event.shiftKey ? 50 : 10) * (event.key === 'ArrowRight' ? 1 : -1);
         onResize(field, clampResizeWidth(currentWidth + step, currentWidth, minWidth, maxWidth));
-    }, [field, currentWidth, onResize, minWidth, maxWidth]);
+    }, [field, currentWidth, onResize, onAutosize, minWidth, maxWidth]);
 
     const handleDoubleClick = useCallback((event: React.MouseEvent) => {
         event.preventDefault();
         event.stopPropagation();
-    }, []);
+        onAutosize?.(field);
+    }, [field, onAutosize]);
 
     const classNames = [
         'ogx-column-resize-handle',

package/lib/components/DataGrid/DataGrid.tsx

@@ -51,6 +51,7 @@ import { useStableColumns } from '../../hooks/core/useStableColumns';
 import { useGridAggregationApi } from '../../hooks/core/useGridAggregationApi';
 import { useGridClipboardApi } from '../../hooks/core/useGridClipboardApi';
 import { useGridScrollToIndexesApi } from '../../hooks/core/useGridScrollToIndexesApi';
+import { useGridColumnAutosize } from '../../hooks/core/useGridColumnAutosize';
 import { useGridSortHandlers, useGridColumnMenuHandlers } from '../../hooks/core/useGridHeaderHandlers';
 import { useGridKeyboardMode, useGridPointerFocusHandlers } from '../../hooks/core/useGridFocusHandlers';
 import { getPaginationRowCount, pickPaginationLocaleText } from '../../utils/pagination';
@@ -500,6 +501,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         disableKeyboardShortcut: disableClipboardCopy,
     });
     useGridScrollToIndexesApi<R>({ apiRef, viewportRef, layout, rowHeight: effectiveRowHeight });
+    const handleColumnAutosize = useGridColumnAutosize<R>({ apiRef, containerRef, columns: orderedColumns, onColumnResize: handleColumnResize });
 
     const { scrollTop, scrollLeft, overscanRows, handleScroll, setViewportElement } = useGridViewport({
         onRowsScrollEnd, overscanRowCount, rowCount: layout.unpinnedRowsLength, autoHeight, setDimensions, viewportRef,
@@ -779,6 +781,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                                 multiSort={multiSort}
 
                                 onColumnResize={handleColumnResize}
+                                onColumnAutosize={handleColumnAutosize}
                                 columnWidths={columnWidths}
                                 pinnedColumns={effectivePinnedColumns}
 

package/lib/components/Header/Header.tsx

@@ -43,6 +43,8 @@ export interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onSort?: (field: string, direction: GridSortDirection) => void;
     sortModel?: Array<{ field: string; sort: 'asc' | 'desc' }>;
     onColumnResize?: (field: string, newWidth: number) => void;
+    /** Fits a column to its content (double-click or Enter on its resize handle). */
+    onColumnAutosize?: (field: string) => void;
     columnWidths?: Record<string, number>;
     pinnedColumns?: GridColumnPinning;
     hasDetailPanel?: boolean;
@@ -81,6 +83,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
         onSort,
         sortModel = [],
         onColumnResize,
+        onColumnAutosize,
         columnWidths = {},
         pinnedColumns,
         hasDetailPanel = false,
@@ -525,6 +528,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                                     field={colDef.field}
                                     currentWidth={getRenderedColumnWidth(colDef, columnWidths)}
                                     onResize={onColumnResize}
+                                    onAutosize={onColumnAutosize}
                                     minWidth={colDef.minWidth}
                                     maxWidth={colDef.maxWidth}
                                     edge={pinnedPosition === 'right' ? 'start' : 'end'}

package/lib/hooks/core/gridApiPlaceholder.ts

@@ -29,6 +29,8 @@ export function createGridApiPlaceholder<R extends GridValidRowModel = GridRowMo
         setPage: noop,
         setPageSize: noop,
         scrollToIndexes: noop,
+        autosizeColumn: noop,
+        autosizeColumns: noop,
         copySelectedRows: () => Promise.resolve(),
     };
 }

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/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. */
@@ -1127,6 +1149,16 @@ export interface GridApi<R extends GridValidRowModel = GridRowModel> {
   /** 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;