@opencorestack/opengridx 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@
 
 ---
 
+## [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

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;