@opencorestack/opengridx 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@
 
 ---
 
+## [3.2.0] — 2026-09-29
+
+### Added
+
+- **Non-blocking `exportToPdf`** — the export now works in ~30 ms slices and yields to the event loop between them, both while formatting rows (including grouped rows and WinAnsi conversion) and while drawing the table: the body is drawn by a series of `jspdf-autotable` calls that continue on the same page with fixed column widths, the header repeated on every new page and the footer only at the end. Pages, row positions, shading and page breaks are unchanged (verified against a single call in Chromium, Firefox and WebKit). Measured with 50,000 grouped rows in Chromium: longest main-thread block 6.3 s → ~0.4–0.6 s (jsPDF's final save, which cannot be split), total time about the same (~6–7 s), file size unchanged.
+- **`PdfExportOptions.onProgress`** — `({ phase: 'prepare' | 'render' | 'save', done, total }) => void`; new exported type `PdfExportProgress`.
+- **`PdfExportOptions.signal`** — an `AbortSignal`; aborting rejects the promise with a `DOMException` named `'AbortError'` and saves no file.
+- **`PdfExportOptions.maxRows`** (default 20,000) — above it a development-mode `console.warn` recommends `exportToCsv` / `exportToExcelAdvanced`. The export still runs; nothing is thrown.
+- Demo: the PDF export page has a row-count selector, a progress bar and a Cancel button.
+
+## [3.1.0] — 2026-09-29
+
+### Added
+
+- **`GridColDef.sortComparator(v1, v2, params1, params2)`** — a per-column ascending comparator for client-side sorting, used instead of the built-in type-aware comparison. `v1` / `v2` are the cell values after `valueGetter`, **including `null` / `undefined`** (the comparator decides where empty values go); `params` are the new exported `GridSortCellParams` `{ id, field, row, value }`. The grid negates the result for `desc`. It is used for flat sorting, as one key in a multi-sort chain, to order row-grouping groups by their grouping value (the grouping column's comparator), for tree-data siblings and for pivot row-label columns, so `getAllFilteredRows()`, exports and clipboard follow the same order. A comparator that throws or returns `NaN` reads as `0` with a one-time dev warning. Ignored with `sortingMode="server"`.
+- **Auto-size a column to its content** — double-click a column's resize handle (or press Enter with the handle focused) to fit the column to its header and the cells in the current render window (pinned rows included), measured in the DOM and clamped to `minWidth` (default 50px) / `maxWidth`. A flex column gets a fixed width, like after a drag; `resizable: false` columns are never auto-sized; the double-click never sorts. Works for left/right-pinned columns and under column groups. The width goes to `columnWidths` state, so `onStateChange` reports it.
+- **`apiRef.current.autosizeColumn(field)`** and **`apiRef.current.autosizeColumns(fields?)`** — the same measurement, programmatically (every column when `fields` is omitted).
+
+### Changed
+
+- Double-clicking a resize handle used to do nothing; it now auto-sizes the column.
+
+---
+
 ## [3.0.1] — 2026-09-29
 
 Fixes from a smoke test in a real application (Chromium, Firefox and WebKit).

package/README.md

@@ -153,8 +153,9 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 | `colSpan` | `number \| ((params) => number)` | — | Merge cells horizontally. |
 | `rowSpan` | `number \| ((params) => number)` | — | Merge cells vertically. |
 | `sortable` | `boolean` | `true` | Enable/disable column sorting. |
+| `sortComparator` | `(v1, v2, p1, p2) => number` | — | Custom ascending comparator (sees nulls; negated for desc). v3.1.0+ |
 | `filterable` | `boolean` | `true` | Enable/disable column filtering. |
-| `resizable` | `boolean` | `true` | Allow drag-resize. |
+| `resizable` | `boolean` | `true` | Allow drag-resize; double-click the handle to auto-size to content (v3.1.0+). |
 | `hideable` | `boolean` | `true` | Allow hiding via the column panel. |
 | `pinnable` | `boolean` | `true` | Allow pinning via the UI. |
 | `disableColumnMenu` | `boolean` | `false` | Hide the column header context menu. |
@@ -310,6 +311,7 @@ apiRef.current.setPageSize(50)
 
 // Scroll
 apiRef.current.scrollToIndexes({ rowIndex: 100, colIndex: 3 })
+apiRef.current.autosizeColumn('name')   // fit to content (v3.1.0+)
 
 // Clipboard
 apiRef.current.copySelectedRows()      // → Promise<void>, rejects if the clipboard write fails
@@ -435,7 +437,7 @@ printGrid(rows, columns, 'Report Title');
 
 > **Optional peer dependencies:** `exportToExcelAdvanced` requires ExcelJS (`npm install exceljs`); `exportToPdf` requires `npm install jspdf jspdf-autotable`.
 
-> **Large exports:** PDF generation runs on the main thread and grows fast (about 120 MB and 10–16 s for 50,000 grouped rows, with the page blocked meanwhile). For more than a few thousand rows export CSV or `.xlsx`. PDF's built-in font only covers Latin-1: pass the `font` option (a Unicode `.ttf`) for characters such as `₹`, otherwise they print as `?`. See [PDF Export](docs/features/pdf-export.md).
+> **Large exports:** PDF size and time grow fast (75–120 MB and several seconds for 50,000 grouped rows). Since v3.2 `exportToPdf` yields between slices so the page stays responsive, reports `onProgress` and accepts an abort `signal`; above `maxRows` (default 20,000) it warns in development. For more than a few thousand rows export CSV or `.xlsx`. PDF's built-in font only covers Latin-1: pass the `font` option (a Unicode `.ttf`) for characters such as `₹`, otherwise they print as `?`. See [PDF Export](docs/features/pdf-export.md).
 
 CSV and HTML-Excel exports neutralise spreadsheet formulas (text starting with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`; opt out with `escapeFormulas: false`), and CSV starts with a UTF-8 BOM (`bom: false` omits it). `exportToExcel` writes an HTML table, so a `.xlsx` file name is saved as `.xls`. To export what the grid shows, pass `apiRef.current.getAllFilteredRows()` and `apiRef.current.getVisibleColumns()`; with a custom `getRowId`, also pass `getRowId` in the options so `selectedRows` match. See the [Export Guide](docs/features/export-guide.md).
 

package/dist/index.d.ts

@@ -671,6 +671,15 @@ export declare interface GridApi<R extends GridValidRowModel = GridRowModel> {
         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
@@ -756,6 +765,16 @@ export declare 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. */
@@ -1200,6 +1219,18 @@ export declare type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
 /** The `slots` prop of `DataGrid`: components that replace built-in parts of the grid. */
 export declare type GridSlots = NonNullable<DataGridProps['slots']>;
 
+/**
+ * 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 declare interface GridSortCellParams<R extends GridValidRowModel = GridRowModel> {
+    id: GridRowId;
+    field: string;
+    row: R;
+    value: unknown;
+}
+
 export declare type GridSortDirection = 'asc' | 'desc' | null;
 
 export declare interface GridSortingState {
@@ -1576,6 +1607,8 @@ export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
         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;
@@ -1734,6 +1767,34 @@ export declare interface PdfExportOptions<R extends GridValidRowModel = GridRowM
      * 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 declare interface PdfExportProgress {
+    phase: 'prepare' | 'render' | 'save';
+    done: number;
+    total: number;
 }
 
 declare interface PivotResult {