@opencorestack/opengridx 3.0.1 → 3.2.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. |
@@ -1443,6 +1446,15 @@ interface PdfExportOptions {
     headerTextColor?: string;
     fontSize?: number;
     font?: { name: string; data: string; boldData?: string }; // v3.0+
+    onProgress?: (p: PdfExportProgress) => void; // v3.2+
+    signal?: AbortSignal; // v3.2+
+    maxRows?: number; // v3.2+, default 20000
+}
+
+interface PdfExportProgress {
+    phase: 'prepare' | 'render' | 'save';
+    done: number;
+    total: number;
 }
 ```
 
@@ -1463,3 +1475,8 @@ interface PdfExportOptions {
 | `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (`#rrggbb` / `#rgb`) |
 | `fontSize` | `number` | `9` | Body cell font size in points |
 | `font` | `{ name, data, boldData? }` | — | Base64 TrueType font for text outside Latin-1 (₹, CJK, Cyrillic…). Without it, such characters are replaced with `?` (v3.0+) |
+| `onProgress` | `(p: PdfExportProgress) => void` | — | Called per slice with `{ phase, done, total }`; phases `prepare` → `render` → `save`, `done` monotonic per phase and ending at `total` (v3.2+) |
+| `signal` | `AbortSignal` | — | Abort → the promise rejects with `DOMException` `'AbortError'`, no file saved. The final jsPDF save step cannot be interrupted (v3.2+) |
+| `maxRows` | `number` | `20000` | Above this many table rows a dev-mode `console.warn` recommends `exportToCsv` / `exportToExcelAdvanced`. Never throws; `Infinity` silences it (v3.2+) |
+
+The export yields to the event loop between ~30 ms slices while formatting and drawing (v3.2+), so the page stays responsive; only jsPDF's final save is one synchronous step. See [PDF Export › Large exports](./features/pdf-export.md#large-exports).

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/pdf-export.md

@@ -16,7 +16,7 @@ npm install jspdf jspdf-autotable
 > await exportToPdf(rows, columns, { fileName: 'invoices', font: { name: 'NotoSans', data: notoSansBase64 } });
 > ```
 
-> **Large datasets:** PDF generation runs on the main thread, and time and file size grow with every row: 50,000 grouped rows took 10–16 s (the page is unresponsive meanwhile) and produced a file of about 120 MB. For more than a few thousand rows, export CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) instead, or export a filtered subset.
+> **Large datasets:** time and file size grow with every row (50,000 grouped rows: several seconds and a file of 75–120 MB). Since v3.2 the export is sliced so the page stays responsive, and it reports progress and can be cancelled, but for more than a few thousand rows CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) is still the better format. See [Large exports](#large-exports).
 
 ## Basic Usage
 
@@ -97,6 +97,42 @@ await exportToPdf(
 | `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (`#rrggbb` or `#rgb`). Invalid values fall back to the default |
 | `fontSize` | `number` | `9` | Body cell font size in points |
 | `font` | `{ name: string; data: string; boldData?: string }` | — | A TrueType font (base64 `.ttf`) for text outside Latin-1 (v3.0+). See [Non-Latin text](#non-latin-text-and-unicode-fonts) |
+| `onProgress` | `(p: PdfExportProgress) => void` | — | Progress: `{ phase: 'prepare' \| 'render' \| 'save', done, total }` (v3.2+). See [Large exports](#large-exports) |
+| `signal` | `AbortSignal` | — | Cancels the export: the promise rejects with a `DOMException` named `'AbortError'` and nothing is saved (v3.2+) |
+| `maxRows` | `number` | `20000` | Table-row count above which a development-mode warning recommends CSV / `.xlsx`. The export still runs; `Infinity` silences it (v3.2+) |
+
+## Large exports
+
+`exportToPdf` returns a `Promise<void>`. Since v3.2 it works in slices of about 30 ms and yields to the event loop between them, both while formatting the rows and while drawing the table, so the page keeps painting and handling input. Pass `onProgress` for a progress bar and `signal` for a Cancel button:
+
+```tsx
+const controllerRef = useRef<AbortController | null>(null);
+const [progress, setProgress] = useState<PdfExportProgress | null>(null);
+
+const onExport = async () => {
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    try {
+        await exportToPdf(rows, columns, {
+            groupedRows: apiRef.current.getGroupedExportRows() ?? undefined,
+            signal: controller.signal,
+            onProgress: setProgress,
+        });
+    } catch (error) {
+        if (!(error instanceof DOMException && error.name === 'AbortError')) throw error;
+    } finally {
+        setProgress(null);
+    }
+};
+// <button onClick={() => controllerRef.current?.abort()}>Cancel</button>
+```
+
+- **Phases.** `prepare` formats the rows (`total` = rows, or grouped entries with `groupedRows`); `render` draws the table (`total` = table body rows); `save` is reported as `0/1` before the file is written and `1/1` after. Within a phase `done` never decreases and ends at `total`.
+- **Cancel.** When `signal` aborts, the promise rejects with `DOMException` `'AbortError'` at the next slice boundary and no file is saved. An already aborted signal rejects before jsPDF is loaded.
+- **The last step still blocks.** jsPDF builds the whole file in one synchronous call when saving; that step cannot be split or cancelled. It is short next to the rest (about 0.4–0.6 s for 50,000 grouped rows in Chromium), but it grows with the file.
+- **Same output.** The table is drawn as a series of `jspdf-autotable` calls that continue on the same page, with fixed column widths, the header repeated on every page and the footer only at the end. Pages, row positions, shading and page breaks are the same as a single call; the file is marginally larger (repeated style operators).
+- **`maxRows` (default 20,000).** Above it a console warning in development recommends `exportToCsv` or `exportToExcelAdvanced`; nothing is thrown, so existing exports keep working. 20,000 rows is roughly where a PDF passes 30 MB and a few seconds to build, and where viewers start to struggle to open it. Pass a larger value (or `Infinity`) to silence the warning when a large PDF is intended.
+- **Total time.** Slicing makes an export slightly slower overall, not faster. Formatting is a small part of the work; drawing the table dominates.
 
 ## Totals and filter summary
 
@@ -148,7 +184,7 @@ Pass the `font` option with a Unicode TrueType font. See [Non-Latin text](#non-l
 
 **Export is slow or the file is huge**
 
-PDF is not suited to tens of thousands of rows (see Installation above). Use CSV or `.xlsx` for large exports.
+PDF is not suited to tens of thousands of rows. Show progress and a Cancel button (see [Large exports](#large-exports)), or use CSV or `.xlsx` for large exports.
 
 **Error: "exportToPdf requires 'jspdf' and 'jspdf-autotable'"**
 

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,
@@ -135,4 +136,5 @@ export type {
     GridRowMeta,
     GridLocaleText,
     PdfExportOptions,
+    PdfExportProgress,
 } from './types';

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. */
@@ -505,6 +527,37 @@ export interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
    * Has no effect when the grid has no active `rowGroupingModel`, or when `selectedRows` is non-empty.
    */
   groupedRows?: GridGroupedExportRow[];
+
+  /**
+   * Called as the export advances: `prepare` (formatting rows; `total` = source rows or grouped
+   * entries), `render` (drawing table rows; `total` = table body rows) and `save` (`0/1` before the
+   * file is written, `1/1` after). `done` never decreases within a phase and ends at `total`.
+   * @since v3.2
+   */
+  onProgress?: (progress: PdfExportProgress) => void;
+
+  /**
+   * Cancels the export. When aborted, the returned promise rejects with a `DOMException` named
+   * `'AbortError'` and no file is saved. Checked between slices of work, so cancellation takes
+   * effect within one slice; the final save step cannot be interrupted once started.
+   * @since v3.2
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Table-row count above which a development-mode warning recommends `exportToCsv` or
+   * `exportToExcelAdvanced`. The export still runs (nothing is thrown). Pass `Infinity` to silence it.
+   * Default: 20000
+   * @since v3.2
+   */
+  maxRows?: number;
+}
+
+/** Progress reported by `PdfExportOptions.onProgress`. @since v3.2 */
+export interface PdfExportProgress {
+  phase: 'prepare' | 'render' | 'save';
+  done: number;
+  total: number;
 }
 
 /**
@@ -1127,6 +1180,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));
+}