@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/API_REFERENCE.md

@@ -12,40 +12,41 @@ The main component for displaying and interacting with data.
 #### Props
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `rows` | `GridRowModel[]` | `[]` | Array of data objects. |
-| `columns` | `GridColDef[]` | `[]` | Definitions for the columns. |
-| `getRowId` | `(row: GridRowModel) => GridRowId` | `row.id` | Returns a unique identifier for each row. |
-| `rowHeight` | `number` | `52` | Height of each row in pixels. |
-| `headerHeight` | `number` | `56` | Height of the header row. |
+| `rows` | `R[]` | — | **Required.** Array of data objects. `R` is your row type: any object type, interfaces included (see [Typing your rows](#typing-your-rows)). Pass `[]` when a `dataSource` supplies the rows. |
+| `columns` | `GridColDef<R>[]` or `GridColDef[]` | — | **Required.** Definitions for the columns: typed for your rows, or untyped. An inline array is fine (v3.0+): while every column is shallowly equal to the previous render's (same properties, callbacks compared by identity) the grid keeps its filter, sort and grouping results. A new inline callback (`valueGetter: (p) => …` written in the render) counts as a change. |
+| `getRowId` | `(row: R) => GridRowId` | `row.id` | Returns a unique identifier for each row. It only keys the grid's internal store: rows reach `renderCell`, events, `apiRef` and `processRowUpdate` unchanged, and the id is never written to `row.id` (v3.0+). Pass it to export functions as `getRowId` when you export `selectedRows`. It must not throw: an id is a programming contract, so a throw is not contained (for a `dataSource` row it fails that request with the error overlay). |
+| `rowHeight` | `number` | `52` | Height of each row in pixels. Without it, an enclosing `DataGridThemeProvider`'s `grid.rowHeightStandard` applies (v3.0+). |
+| `headerHeight` | `number` | `56` | Height of the header row. Without it, the theme's `grid.headerHeight` applies (v3.0+). |
 | `autoHeight` | `boolean` | `false` | Adjust grid height to match row total. |
 | `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
-| `loading` | `boolean` | `false` | Shows a loading skeleton overlay. |
+| `loading` | `boolean` | `false` | With no rows, the body shows skeleton rows (or `slots.loadingOverlay`). With rows already shown, they stay and a progress bar runs along the top of the grid (or `slots.loadingOverlay` is shown over them). Works in list view too. |
 | `checkboxSelection` | `boolean` | `false` | Enable row selection via checkboxes. |
-| `pagination` | `boolean` | `false` | Enable the bottom pagination bar. |
-| `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | How to handle paging. |
+| `pagination` | `boolean` | `false` | Enable the bottom pagination bar. Ignored while `rowGroupingModel` is active (dev-mode warning) and with `paginationMode="infinite"`. |
+| `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | How to handle paging. `'infinite'` appends rows from the `dataSource` as `paginationModel.page` grows and never shows a pager or slices rows (see [Infinite Scroll](features/infinite-scroll.md)). |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. |
-| `rowCount` | `number` | — | Total rows (required for server-side paging). |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. The uncontrolled default page size is 100 when offered, else the first option. |
+| `rowCount` | `number` | — | Server total for `paginationMode="server"` when you fetch pages yourself (read on every render). With a `dataSource`, the response's `rowCount` is used and this is only the fallback before the first response. |
 | `height` | `number \| string` | `undefined` | Total height of the grid container. |
-| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density. |
-| `initialState` | `GridInitialState` | `undefined` | Starting state for sorting, filters, etc. |
-| `slots` | `GridSlots` | `{}` | Custom component overrides. |
-| `slotProps` | `Record<string, unknown>` | `{}` | Props passed to custom slots. |
-| `filterModel` | `GridFilterModel` | `undefined` | Active filters. |
+| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density: compact = the theme's `grid.rowHeightCompact` or 32 px, standard = `rowHeight`, comfortable = the theme's `grid.rowHeightComfortable` or 72 px. |
+| `initialState` | `GridInitialState` | `undefined` | Starting state (sort, filter, pagination, columns, density), read on mount. Seeds the grid's uncontrolled state; see [State Persistence](features/state-persistence.md). |
+| `slots` | `GridSlots` | — | Custom component overrides: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`. See [`GridSlots`](#gridslots-and-gridslotprops) and the [Slots API](customization/slots-api.md). |
+| `slotProps` | `GridSlotProps` | — | Props passed to the slots, keyed like `slots`. `slotProps.toolbar` is typed as `Partial<GridToolbarProps>` (plus any extra keys your own toolbar reads), so `GridToolbar` render props are type-checked (v3.0+). |
+| `filterModel` | `GridFilterModel` | `undefined` | Active filters (controlled). Omit it to let the grid keep its own filter state, seeded from `initialState.filter` and changed by the toolbar or `apiRef.setFilterModel` (v3.0+). |
 | `sortModel` | `GridSortItem[]` | `undefined` | Active sorting. |
-| `onRowClick` | `(params: GridRowParams) => void` | — | Fired when a row is clicked. |
-| `onCellClick` | `(params: GridCellParams) => void` | — | Fired when a cell is clicked. |
-| `onStateChange` | `(state: GridState) => void` | — | Fired on any internal state update. |
-| `processRowUpdate` | `(new, old) => R \| Promise<R>` | — | Fired after a cell edit is committed. |
+| `onRowClick` | `(params: GridRowParams) => void` | — | Fired when a row is clicked. Tree-data parent rows are real rows: a click fires this and selects them (their chevron expands them). Not fired for synthetic rows (row-grouping group rows, subtotal rows, auto-created tree parents): clicking a group row toggles it. |
+| `onRowDoubleClick` | `(params: GridRowParams) => void` | — | Fired when a row is double-clicked (v2.1+). Also fires for group rows, and (v3.0+) for the double-click that opens an editor on an editable cell; not fired on the checkbox, expand icon, drag handle or inside an open editor. |
+| `onCellClick` | `(params: GridCellParams) => void` | — | Fired when a cell is clicked. Not fired for clicks inside an open editor (v3.0+). |
+| `onStateChange` | `(state: GridState) => void` | — | Fired on mount and whenever the value of the sort, filter, pagination, column or density state changes (not on re-renders with equal props). |
+| `processRowUpdate` | `(new, old) => R \| Promise<R>` | — | Called once per committed cell edit (Enter, Tab, blur, or the editor's cell leaving the grid). Return the row to store, or a Promise of it; the editor stays open until the Promise settles. Returning nothing is reported through `onProcessRowUpdateError`. See [Editing](features/editing-reordering.md#commit-and-cancel). |
 | `dataSource` | `GridDataSource` | — | Remote data provider interface. |
 
 #### Sorting, Filtering & Pagination
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `sortingMode` | `'client' \| 'server'` | `'client'` | Set to `'server'` when your backend handles sorting. The grid calls `onSortModelChange` but does not re-sort rows locally. |
-| `filterMode` | `'client' \| 'server'` | `'client'` | Set to `'server'` when your backend handles filtering. The grid calls `onFilterModelChange` but does not re-filter rows locally. |
+| `sortingMode` | `'client' \| 'server'` | `'client'` | Set to `'server'` when your backend handles sorting. The grid calls `onSortModelChange` but does not re-sort rows locally, with or without a `dataSource` (v3.0+). |
+| `filterMode` | `'client' \| 'server'` | `'client'` | Set to `'server'` when your backend handles filtering. The grid calls `onFilterModelChange` but does not re-filter rows locally, with or without a `dataSource` (v3.0+). |
 | `multiSort` | `boolean` | `false` | When `true`, clicking any sortable column header appends/cycles it in the sort model instead of replacing it — no Shift key required. Shift+click always appends regardless of this prop. |
 | `onSortModelChange` | `(model: GridSortItem[]) => void` | — | Fired when the active sort model changes. |
 | `onFilterModelChange` | `(model: GridFilterModel) => void` | — | Fired when the active filter model changes. |
@@ -57,7 +58,8 @@ The main component for displaying and interacting with data.
 | `rowSelectionModel` | `GridRowSelectionModel` | `[]` | Controlled selection state — array of selected row IDs. |
 | `onRowSelectionModelChange` | `(model: GridRowSelectionModel) => void` | — | Fired when the selection changes. |
 | `disableRowSelectionOnClick` | `boolean` | `false` | When `true`, clicking a row does not toggle its selection. |
-| `disableMultipleRowSelection` | `boolean` | `false` | When `true`, at most one row can be selected at a time. |
+| `disableMultipleRowSelection` | `boolean` | `false` | When `true`, at most one row can be selected at a time — by click, checkbox, Space or `apiRef` — and the header select-all checkbox is not shown. |
+| `disableClipboardCopy` | `boolean` | `false` | When `true`, Ctrl+C / Cmd+C does not copy the selected rows, so the page or your own handler owns the shortcut. `apiRef.current.copySelectedRows()` still works. See [Clipboard](features/clipboard.md). |
 
 #### Column Visibility
 
@@ -70,11 +72,12 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `disableColumnReorder` | `boolean` | `false` | Disables drag-and-drop column reordering. |
+| `disableColumnReorder` | `boolean` | `false` | Disables drag-and-drop and Columns-panel reordering. A controlled `columnOrder` or `initialState.columns.columnOrder` still applies. |
 | `columnOrder` | `GridColumnOrder` | — | Controlled ordered array of column field names. |
-| `onColumnOrderChange` | `(params: GridColumnOrderChangeParams) => void` | — | Fired after a column is dragged to a new position. |
+| `onColumnOrderChange` | `(params: GridColumnOrderChangeParams) => void` | — | Fired after the user moves one column (header drag or Columns panel drag). Indices are positions in the grid's full column order. |
+| `onColumnOrderModelChange` | `(columnOrder: GridColumnOrder) => void` | — | Fired with the whole new column order after every change, including the Columns panel's **Reset**. Use it to keep a controlled `columnOrder` in sync (v3.0+). Not fired for generated pivot columns. |
 | `rowReordering` | `boolean` | `false` | Enables drag-and-drop row reordering. |
-| `onRowOrderChange` | `(params: GridRowOrderChangeParams) => void` | — | Fired after a row is dragged to a new position. |
+| `onRowOrderChange` | `(params: GridRowOrderChangeParams) => void` | — | Fired after a row is dragged onto another row. Indices are positions in your `rows` prop. |
 
 #### Pinning
 
@@ -82,7 +85,7 @@ The main component for displaying and interacting with data.
 | :--- | :--- | :--- | :--- |
 | `pinnedColumns` | `GridColumnPinning` | — | Columns pinned to the left or right viewport edges. See [Column & Row Pinning](#-column--row-pinning). |
 | `onPinnedColumnsChange` | `(model: GridColumnPinning) => void` | — | Fired when column pinning changes. |
-| `pinnedRows` | `GridRowPinning` | — | Row IDs pinned to the top or bottom of the viewport. |
+| `pinnedRows` | `GridRowPinning` | — | Row IDs pinned to the top or bottom of the viewport. Pinned rows still have to pass the filter. Ignored (with a development warning) under tree data and row grouping, where the rows stay in the hierarchy. |
 | `pinCheckboxColumn` | `boolean` | `true` | Keeps the checkbox column visible during horizontal scrolling. |
 | `pinExpandColumn` | `boolean` | `true` | Keeps the Master-Detail expansion column visible during horizontal scrolling. |
 
@@ -90,15 +93,15 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `isCellEditable` | `(params: GridCellParams) => boolean` | — | Per-cell predicate. Return `false` to make a specific cell read-only even when the column has `editable: true`. |
-| `onProcessRowUpdateError` | `(error: unknown) => void` | — | Fired if `processRowUpdate` throws or returns a rejected Promise. Use to display validation errors or restore the previous row value. |
+| `isCellEditable` | `(params: GridCellParams) => boolean` | — | Per-cell predicate. Return `false` to make a specific cell read-only even when the column has `editable: true`. Applies to double-click, Enter, Tab stops and `aria-readonly` (v3.0+). It can only restrict: a column without `editable: true` is never editable. A predicate that throws counts as `false`. |
+| `onProcessRowUpdateError` | `(error: unknown) => void` | — | Fired if `processRowUpdate` (or `valueSetter`) throws, returns a rejected Promise, or returns something that is not a row. The editor stays open with the pending value. Use to display validation errors. |
 
 #### Master-Detail
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `getDetailPanelContent` | `(params: GridDetailPanelParams) => ReactNode` | — | Returns the JSX content rendered inside the expandable detail panel. |
-| `getDetailPanelHeight` | `(params: GridDetailPanelParams) => number \| 'auto'` | `'auto'` | Controls the panel height in pixels, or `'auto'` to fit content. |
+| `getDetailPanelHeight` | `(params: GridDetailPanelParams) => GridDetailPanelHeight` | `200` | Panel height in pixels (`0` is a 0px panel), or `'auto'` to fit the content. An `'auto'` panel is measured when it renders and whenever its size changes, and the rows below it are laid out at that height. Without this prop every panel is a fixed 200px scroll box. A callback that throws gets the 200px default (v3.0+, with a one-time development warning). |
 | `detailPanelExpandedRowIds` | `Set<GridRowId>` | — | Controlled set of currently-expanded detail panel row IDs. |
 | `onDetailPanelExpandedRowIdsChange` | `(ids: Set<GridRowId>) => void` | — | Fired when detail panels expand or collapse. |
 
@@ -107,8 +110,8 @@ The main component for displaying and interacting with data.
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `treeData` | `boolean` | `false` | Enables hierarchical tree data display. |
-| `getTreeDataPath` | `(row: R) => string[]` | — | Returns the hierarchy path for a row (e.g. `['Engineering', 'Frontend']`). |
-| `groupingColDef` | `Partial<GridColDef>` | — | Configures the dedicated `__group__` column prepended at position 0 (auto-pinned left) when row grouping is active. Accepts `headerName`, `width`, `renderCell`, and any non-system `GridColDef` field. The column's `field` is always `'__group__'`; it is never sorted, exported, hidden, or re-ordered. |
+| `getTreeDataPath` | `(row: R) => string[]` | — | Returns the hierarchy path for a row (e.g. `['Engineering', 'Frontend']`). Required with `treeData`: without it the rows are shown flat. Keep its identity stable (module scope or `useCallback`); a new function rebuilds the tree. It must not throw (a throw is not contained). |
+| `groupingColDef` | `Partial<GridColDef<R>>` | — | Configures the dedicated `__group__` column prepended at position 0 (auto-pinned left) when row grouping or tree data is active. Under tree data its cells show the last segment of each row's `getTreeDataPath` (override with `groupingColDef.valueGetter`). Accepts `headerName`, `width`, `renderCell`, and any non-system `GridColDef` field. Its `renderCell` is called for group rows too (check `params.rowMeta?.isGroupRow`); its output replaces the default group label next to the toggle, and returning `undefined` for a group row keeps the default label. The column's `field` is always `'__group__'` (no `field` is needed; one you pass is ignored); it is never sorted, filtered, pinned by the user, exported, hidden, or re-ordered. Defaults: `headerName: 'Group'`, `width: 220`. |
 | `defaultGroupingExpansionDepth` | `number` | `0` | Number of tree levels expanded on initial render (`-1` = all). |
 
 #### Row Grouping & Aggregation
@@ -118,13 +121,13 @@ The main component for displaying and interacting with data.
 | `rowGroupingModel` | `GridRowGroupingModel` | `[]` | Array of field names to group rows by (e.g. `['department', 'team']`). See [Row Grouping](#️-row-grouping). |
 | `aggregationModel` | `GridAggregationModel` | — | Map of `field → aggFn` (e.g. `{ salary: 'sum', age: 'avg' }`). See [Aggregation Reference](#-aggregation-reference). |
 | `onAggregationModelChange` | `(model: GridAggregationModel) => void` | — | Fired when the aggregation model changes. |
-| `getAggregationPosition` | `(groupNode: GridTreeNode \| null) => 'inline' \| 'footer' \| null` | — | Controls where aggregation results appear. `'inline'` = inside the group row, `'footer'` = a dedicated row below the group, `null` = hidden. Pass `null` groupNode = grand-total (root) position. |
+| `getAggregationPosition` | `(groupNode: GridTreeNode \| null) => 'inline' \| 'footer' \| null` | — | Controls where aggregation results appear. Called for every group node (with its current `isExpanded`) and once with `null` for the grand total. `'inline'` (group default) = on the group row, `'footer'` = on a subtotal row after the group's children while it is expanded (on the group row while collapsed), `null` = hidden. For the grand total, `null` hides the footer row. A callback that throws gets the default (`'inline'` for a group, `'footer'` for the grand total; v3.0+). See [the callback](#getaggregationposition-callback). |
 
 #### Pivot
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `pivotMode` | `boolean` | `false` | Switches the grid to multidimensional Pivot Mode. |
+| `pivotMode` | `boolean` | `false` | Switches the grid to multidimensional Pivot Mode (client-side: ignored when a `dataSource` is set; tree data and row grouping are turned off while pivoting). See [Aggregation & Pivot](features/aggregation-pivot.md#-pivot-mode). |
 | `pivotModel` | `GridPivotModel` | — | Controlled pivot configuration (row fields, column fields, value fields). |
 | `onPivotModelChange` | `(model: GridPivotModel) => void` | — | Fired when the pivot model changes. |
 
@@ -132,7 +135,7 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `onRowsScrollEnd` | `(params: GridRowScrollEndParams) => void` | — | Fired when the user scrolls to the bottom of the grid viewport. Use this to trigger the next page in infinite-scroll mode. |
+| `onRowsScrollEnd` | `(params: GridRowScrollEndParams) => void` | — | Fired once each time the viewport comes within 100px of the bottom of the rows: after a vertical scroll, and also when the rows change while the end is in view (including rows that do not fill the viewport). It fires again only after the viewport leaves that zone or the row count changes; horizontal scrolling never fires it. `listView` follows the same once-per-arrival rule for its list (it re-arms when the list leaves the zone or the row count changes). Use it to load the next page in infinite-scroll mode. |
 
 #### Accessibility & Appearance
 
@@ -147,7 +150,7 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `localeText` | `GridLocaleText` | — | Override user-visible strings in the Pagination component. See `GridLocaleText` for the full interface. |
+| `localeText` | `GridLocaleText` | — | Override user-visible strings: the Pagination labels and the empty-state label (`noRowsLabel`, which wins over the `noRowsLabel` prop). See [`GridLocaleText`](#gridlocaletext). |
 
 #### Imperative Ref
 
@@ -159,7 +162,7 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `listView` | `boolean` | `false` | Renders the grid as a single-column list of cards. Designed for mobile and responsive layouts. |
+| `listView` | `boolean` | `false` | Renders the grid as a single-column list of cards. Designed for mobile and responsive layouts. Requires `listViewColumn`; without it the grid view is shown and a dev warning is logged. |
 | `listViewColumn` | `GridListViewColDef` | — | Column definition for list view mode. Must provide a `renderCell` function. The `field` value is used as a key. |
 
 #### Column Group Headers
@@ -168,11 +171,57 @@ The main component for displaying and interacting with data.
 | :--- | :--- | :--- | :--- |
 | `columnGroupingModel` | `GridColumnGroupingModel` | — | Defines spanning header rows above the regular column headers. See [Column Group Headers](#️-column-group-headers). |
 
+### Typing your rows
+
+`DataGrid` and every generic type (`GridColDef<R>`, `GridRenderCellParams<R>`, `GridRowParams<R>` …) take your row type `R`. Since v3.0 `R` can be any object type (`GridValidRowModel`), so your own interfaces work directly: they need no index signature and do not have to extend `GridRowModel`. `R` is inferred from `rows`.
+
+```tsx
+import { DataGrid } from '@opencorestack/opengridx';
+import type { GridColDef } from '@opencorestack/opengridx';
+
+interface Employee { id: number; name: string; salary: number }
+
+// Typed columns: callbacks see `params.row` as Employee.
+const columns: GridColDef<Employee>[] = [
+  { field: 'name', renderCell: ({ row }) => row.name.toUpperCase() },
+  { field: 'salary', valueGetter: ({ row }) => row.salary * 12,
+    valueSetter: ({ row, value }) => ({ ...row, salary: Number(value) / 12 }) },
+];
+
+<DataGrid rows={employees} columns={columns} onRowClick={({ row }) => console.log(row.name)} />;
+```
+
+- **Untyped columns** (`GridColDef[]`, as in the README) work with rows of any type. Their callbacks see `params.row` as `GridRowModel` (any key, read as `unknown`). The `DataGridUntypedColumnsProps<R>` type describes these props.
+- **Inline column arrays** (`columns={[{ field: 'name', renderCell: ({ row }) => … }]}`) get `R` from `rows`.
+- **Rows without an `id`** need `getRowId`, e.g. `getRowId={(row) => row.code}`.
+- A `GridColDef<Row>` for a type-alias row (or an interface that extends `GridRowModel`) can be used where a `GridColDef` is expected: the row callbacks are declared as methods, so they are checked bivariantly.
+- `params.value` stays `unknown`; read typed values from `params.row`, or render `params.formattedValue`.
+- The export functions, `usePivot` and `useAggregation` accept the same typed or untyped columns, and their options' `getRowId` takes your row type.
+- `apiRef` methods (`getRow`, `getAllRows` …) return `GridRowModel`: the API object is not generic.
+- For the component's props type, use `DataGridProps<R>`. `React.ComponentProps<typeof DataGrid>` resolves to the untyped-columns overload.
+
+### `GridSlots` and `GridSlotProps`
+
+The types of the `slots` and `slotProps` props (v3.0+ exports). Each slot is typed with the props the grid passes it, so a slot component with its own typed props (e.g. `function Footer({ rowCount }: { rowCount: number })`) is checked, and an inline slot (`footer: (props) => …`) gets its parameter typed. A function component typed `(props: Record<string, unknown>)` is still accepted; a class, `memo` or `forwardRef` component needs the slot's props type (e.g. `GridToolbarSlotProps`). A prop the grid does not pass (one you supply through `slotProps`) must be optional in your component, or close over it in an inline slot.
+
+| Slot | Replaces | Receives |
+| :--- | :--- | :--- |
+| `toolbar` | Nothing by default: renders a toolbar above the grid. Use `GridToolbar` or your own component. | `GridToolbarSlotProps`: the toolbar props the grid owns (see [`GridToolbarProps`](#gridtoolbarprops)) plus `apiRef`, then `slotProps.toolbar`. |
+| `pagination` | The built-in `Pagination` bar (shown with `pagination`). | `GridPaginationSlotProps` (= `PaginationProps`: `page`, `pageSize`, `rowCount`, `pageSizeOptions`, `onPageChange`, `onPageSizeChange`, `localeText`), then `slotProps.pagination`. |
+| `noRowsOverlay` | The empty-state icon and label (shown when there are no rows and the grid is not loading). | `slotProps.noRowsOverlay` only (`GridOverlaySlotProps`). |
+| `loadingOverlay` | The loading indicator: the skeleton rows while loading with no rows, the progress bar while loading with rows shown (the slot is then shown over them). | `slotProps.loadingOverlay` only (`GridOverlaySlotProps`). |
+| `footer` | The pagination area. | `GridFooterSlotProps`: `apiRef`, `aggregationModel`, `aggregationResult`, `rowCount`, `pagination`, `paginationModel`, `pageSizeOptions`, `onPaginationModelChange`, then `slotProps.footer`. `rowCount` is the built-in pager's count (pinned rows excluded, v3.0+); under tree data or row grouping, the filtered data rows. |
+
+```ts
+type GridSlots = NonNullable<DataGridProps['slots']>;
+type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
+```
+
 ---
 
 ## 🛠️ `GridToolbar`
 
-The built-in toolbar component. Mount it via `slots={{ toolbar: GridToolbar }}`. All props below are passed through `slotProps.toolbar` (or directly when building a custom wrapper).
+The built-in toolbar component. Mount it via `slots={{ toolbar: GridToolbar }}`. The grid passes the models and change handlers it owns (plus `apiRef`), then spreads `slotProps.toolbar` over them, so any prop below can be set or overridden there (or directly when rendering `GridToolbar` yourself).
 
 ### `GridToolbarProps`
 
@@ -181,17 +230,18 @@ The built-in toolbar component. Mount it via `slots={{ toolbar: GridToolbar }}`.
 | `columns` | `GridColDef[]` | `[]` | Column definitions — injected automatically when used via `slots`. |
 | `baseColumns` | `GridColDef[]` | — | Pre-pivot columns shown in the Pivot panel instead of synthetic pivot columns. |
 | `aggregationModel` | `GridAggregationModel` | `{}` | Current aggregation configuration. |
-| `onAggregationModelChange` | `(model: GridAggregationModel) => void` | — | Called when the user changes aggregation settings. |
-| `pivotModel` | `GridPivotModel` | — | Current pivot configuration. Presence of this prop renders the Pivot button. |
-| `onPivotModelChange` | `(model: GridPivotModel) => void` | — | Called when the user changes pivot settings. |
-| `filterModel` | `GridFilterModel` | — | Current filter model. Presence of this prop renders the search bar and Filter button. |
-| `onFilterModelChange` | `(model: GridFilterModel) => void` | — | Called when the user changes filters or the quick-search value. |
+| `onAggregationModelChange` | `(model: GridAggregationModel) => void` | — | Called when the user changes aggregation settings. Presence of this prop renders the Summaries button; the grid always injects it when the toolbar is mounted via `slots`. |
+| `pivotModel` | `GridPivotModel` | — | Current pivot configuration. |
+| `onPivotModelChange` | `(model: GridPivotModel) => void` | — | Called when the user changes pivot settings. Presence of this prop renders the Pivot button; the grid injects it when `pivotMode`, `pivotModel` or `onPivotModelChange` is set. |
+| `filterModel` | `GridFilterModel` | — | Current filter model. |
+| `onFilterModelChange` | `(model: GridFilterModel) => void` | — | Called when the user changes filters or the quick-search value. Its presence renders the search bar and Filter button; the grid always injects it when the toolbar is mounted via `slots` (v3.0+). |
 | `columnVisibilityModel` | `Record<string, boolean>` | `{}` | Current column visibility map. |
-| `onColumnVisibilityModelChange` | `(model: Record<string, boolean>) => void` | — | Called when the user shows or hides a column. Presence renders the Columns button. |
+| `onColumnVisibilityModelChange` | `(model: Record<string, boolean>) => void` | — | Called when the user shows or hides a column. Presence renders the Columns button; the grid always injects it when the toolbar is mounted via `slots`. |
+| `showNonHideableColumns` | `boolean` | `false` | Show `hideable: false` columns in the Columns panel as disabled rows. |
 | `onColumnReorder` | `(from: string, to: string) => void` | — | Called when the user drags a column in the Columns panel. |
 | `onColumnOrderReset` | `() => void` | — | Called when the user clicks "Reset order" in the Columns panel. |
-| `forceColumnsOpen` | `boolean` | — | Forces the Columns panel open (used internally by the column header context menu). |
-| `onColumnsPanelClose` | `() => void` | — | Called when the Columns panel closes after a `forceColumnsOpen`. |
+| `forceColumnsOpen` | `boolean` | — | Opens the Columns panel when it becomes `true` (set by `DataGrid` for the column menu's **Manage columns**). If the toolbar slot does not render a `GridToolbar` that receives it, the grid opens its standalone Columns panel instead. |
+| `onColumnsPanelClose` | `() => void` | — | Called whenever the Columns panel closes (its button, a custom button, another panel opening, click-outside or Escape). |
 | `children` | `ReactNode` | — | Content rendered on the **left** side of the toolbar, before the spacer. |
 | `rightContent` | `ReactNode` | — | Content rendered on the **right** side, after all built-in buttons. |
 | `className` | `string` | — | Additional CSS class on the toolbar root `<div>`. Use for visual theme overrides. |
@@ -218,8 +268,8 @@ Passed to `renderQuickFilter`.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `value` | `string` | Current search string. |
-| `onChange` | `(value: string) => void` | Call with the updated string when the input changes. |
+| `value` | `string` | Current search string: `filterModel.quickFilterValues` joined with spaces. |
+| `onChange` | `(value: string) => void` | Call with the updated string when the input changes. The toolbar splits it on whitespace into `quickFilterValues` terms. |
 
 ---
 
@@ -229,44 +279,50 @@ Access these methods via the `apiRef` prop.
 
 | Method | Return | Description |
 | :--- | :--- | :--- |
-| `getRow(id)` | `GridRowModel \| null` | Get row data by ID. |
+| `getRow(id)` | `GridRowModel \| null` | Get row data by ID (your row object, unchanged). |
 | `getAllRows()` | `GridRowModel[]` | Get all loaded rows. |
-| `getVisibleRows()` | `GridRowModel[]` | Get rows after filtering/sorting. |
+| `getVisibleRows()` | `GridRowModel[]` | Get the rows on screen after filtering/sorting: pinned-top rows, the current page (or all rows without pagination), pinned-bottom rows. Under row grouping and tree data this is the visible hierarchy, group rows included. |
 | `getColumn(field)` | `GridColDef \| null` | Get column definition by field. |
-| `getVisibleColumns()` | `GridColDef[]` | Get currently visible columns. |
-| `selectRow(id, isSelected)` | `void` | Set selection for a single row. |
-| `selectRows(ids, isSelected)`| `void` | Set selection for multiple rows. |
+| `getVisibleColumns()` | `GridColDef[]` | Get the columns on screen, in render order (hidden columns excluded): left-pinned, unpinned, right-pinned, as the header shows them (v3.0+; before, pinned columns kept their unpinned position). |
+| `selectRow(id, isSelected = true)` | `void` | Set selection for a single row. Fires `onRowSelectionModelChange`, unless nothing changes (selecting a selected row, deselecting an unselected one; v3.0+). Ids of rows the grid made (group headers, subtotals, auto-created tree parents, the pivot Grand Total) are ignored, as they are for the checkbox, click and keyboard (v3.0+). |
+| `selectRows(ids, isSelected = true)`| `void` | Set selection for multiple rows. With `disableMultipleRowSelection`, selecting keeps only the last id. Same no-op and synthetic-id rules as `selectRow`. |
 | `getSelectedRows()` | `GridRowId[]` | Get IDs of all selected rows. |
-| `sortColumn(field, dir)` | `void` | Programmatically sort a column. |
-| `getSortModel()` | `GridSortItem[]` | Get active sorting state. |
-| `setFilterModel(model)` | `void` | Programmatically set filters. |
-| `getFilterModel()` | `GridFilterModel` | Get the current filter model. |
-| `setPage(page)` | `void` | Change current page (0-indexed). |
-| `setPageSize(pageSize)` | `void` | Change the current page size. |
-| `scrollToIndexes(params)` | `void` | Scroll to specific row/column index. |
+| `sortColumn(field, dir)` | `void` | Sort like a header click: replaces the sort model (or, with `multiSort`, updates/appends that field); `null` removes the field. Fires `onSortModelChange`. |
+| `getSortModel()` | `GridSortItem[]` | Get the sort model the grid is using (controlled or not). |
+| `setFilterModel(model)` | `void` | Set filters. Fires `onFilterModelChange`; with a controlled `filterModel`, update the prop from it. |
+| `getFilterModel()` | `GridFilterModel` | Get the filter model the grid is using (controlled or not). |
+| `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+). |
 | `getAllColumns()` | `GridColDef[]` | Get all defined columns. |
-| `getAggregationResult()` | `Record<string, unknown> \| null` | Get current aggregation results. |
+| `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. |
-| `getAllFilteredRows()` | `GridRowModel[]` | Get all filtered+sorted rows regardless of the current pagination window. Use for full-dataset exports. |
-| `getGroupedExportRows()` | `GridGroupedExportRow[] \| null` | Get a flat ordered list reflecting the active row-grouping tree (group-header, leaf, subtotal, grand-total). Returns `null` when row grouping is not active. |
-| `copySelectedRows()` | `Promise<void>` | Copy selected rows to clipboard as TSV. |
+| `getAllFilteredRows()` | `GridRowModel[]` | Get every row that passes the filter, sorted, regardless of pagination, including pinned rows. Under row grouping and tree data it returns the data rows (no group rows) in hierarchy order with every group expanded, ordered like the screen (also when sorting by the hierarchy column; v3.0+). With tree data and a filter, ancestors shown only to give a match its context are left out: the result is the set select-all and the aggregation footer act on (v3.0+). Use for full-dataset exports. |
+| `getGroupedExportRows()` | `GridGroupedExportRow[] \| null` | Get a flat ordered list reflecting the active row-grouping tree (group-header, leaf, subtotal, grand-total), sorted and filtered like the screen. Collapsed groups are included with their rows, and subtotals are computed over each group's exported rows. Group-header and subtotal entries carry `groupLabel`, the label the grid shows (v3.0+). Returns `null` when row grouping is not active. |
+| `copySelectedRows()` | `Promise<void>` | Copy every selected row that passes the filter (other pages, collapsed groups and pinned rows included) as TSV, with the visible columns in screen order. Resolves without writing when no selected row is found; rejects when the clipboard write fails. |
 
 ---
 
 ## 🌳 Internal Data Structures
 
 ### `GridTreeNode`
-Used in Tree Data and Row Grouping hierarchies.
+Used in Tree Data and Row Grouping hierarchies. This is what `getAggregationPosition` receives.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `id` | `GridRowId` | Unique ID of the row. |
-| `parentId` | `GridRowId \| null` | ID of the parent node. |
+| `parentId` | `GridRowId \| null` | ID of the parent node (`null` at the root). |
 | `depth` | `number` | Nesting level (0 for root). |
+| `groupingKey` | `string` | The key identifying this node within its parent. |
+| `groupingField` | `string` (optional) | Row grouping: the field this node groups by. |
+| `groupingValue` | `unknown` (optional) | The value this node is grouping by. |
 | `isExpanded` | `boolean` | Current expansion state. |
-| `children` | `GridRowId[]` | IDs of child nodes. |
-| `groupingValue` | `unknown` | The value this node is grouping by. |
-| `aggregatedValues` | `object` | Sums/Avgs computed for this group. |
+| `children` | `GridRowId[]` (optional) | IDs of the direct child nodes. |
+| `label` | `string` (optional) | Display label of the group. |
+| `aggregatedValues` | `Record<string, unknown>` (optional) | Aggregates computed for this group, keyed by field. |
+| `aggregationPosition` | `'inline' \| 'footer' \| null` (optional) | Where this group's aggregates are shown. |
+| `descendantCount` | `number` (optional) | Row grouping: leaf rows in the group that pass the filter (recursive). |
+| `serverChildrenCount` | `number` (optional) | Server-side tree data: the child count the server reported. |
 
 ---
 
@@ -282,42 +338,46 @@ Defines the behavior and appearance of a single column.
 | `field` | `string` | — | **Required.** Unique identifier matching the row object key. |
 | `headerName` | `string` | — | Text shown in the column header cell. |
 | `description` | `string` | — | Tooltip shown on column header hover (rendered as the HTML `title` attribute — improves accessibility). |
-| `width` | `number \| string` | `100` | Fixed width in pixels or a percentage string. |
-| `minWidth` | `number` | — | Minimum width in pixels (enforced during resize). |
-| `maxWidth` | `number` | — | Maximum width in pixels (enforced during resize). |
-| `flex` | `number` | — | Flex grow factor — distributes remaining space proportionally. Mutually exclusive with a fixed `width`. |
+| `width` | `number \| string` | unset: flexes | Fixed width in pixels, or a percentage string (`'30%'`): a share of the width left after the fixed-width columns, the same base for every percentage column. Unset (or `'auto'`), the column behaves like `flex: 1` and shares the free space with the flex columns (at least `minWidth`, 50px by default). Pinned and unpinned columns are sized the same way. Every width, including a manual resize, is clamped to `minWidth` / `maxWidth`. |
+| `minWidth` | `number` | — | Minimum width in pixels (enforced during resize; 50 when omitted, or the column's own width if that is smaller). |
+| `maxWidth` | `number` | — | Maximum width in pixels (enforced during resize; no limit when omitted). |
+| `flex` | `number` | — | Flex grow factor — distributes remaining space proportionally. When both are set, `flex` wins over `width` until the user resizes the column. |
 | `align` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of cell content. |
-| `headerAlign` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of the header cell content. |
+| `headerAlign` | `'left' \| 'center' \| 'right'` | `align` | Horizontal alignment of the header cell content. Falls back to the column's `align`, then `'left'`. |
+| `zIndex` | `number` | — | CSS `z-index` for the column's cells and header cell (pinned cells default to 3). |
 
 #### Data & Type
 
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `type` | `'string' \| 'number' \| 'date' \| 'boolean' \| 'singleSelect' \| 'image'` | `'string'` | Data type — determines default filter operators and cell formatting. |
-| `valueOptions` | `Array<string \| number \| { value: unknown; label: string }>` | — | Allowed values for `type: 'singleSelect'` — used in the filter dropdown and edit cell. |
-| `valueGetter` | `(params: GridValueGetterParams) => unknown` | — | Derive a computed value from the row object. Runs before `valueFormatter` and `renderCell`. |
-| `valueFormatter` | `(params: GridValueFormatterParams) => string` | — | Format the value into a display string (e.g. currency, dates). Does not affect editing or sorting. |
+| `type` | `'string' \| 'number' \| 'date' \| 'boolean' \| 'singleSelect' \| 'image'` | `'string'` | Data type: sets the default filter operators and, when the column has no `valueFormatter`, the default cell text: `date` shows the local calendar date (`toLocaleDateString()`), `boolean` shows Yes / No, `singleSelect` shows the `valueOptions` label, `image` renders an `<img>` of the URL. `number` and `string` show `String(value)`. The text exporters (CSV, Excel HTML, print, PDF) and list view use the same text. |
+| `valueOptions` | `Array<string \| number \| { value: unknown; label: string }>` | — | Allowed values for `type: 'singleSelect'` — the filter panel offers them as a (multi-)select, and the edit cell uses them; cells and exports show the option's label. |
+| `valueGetter` | `(params: GridValueGetterParams) => unknown` | — | Derive a computed value from the row object. Runs before `valueFormatter` and `renderCell`. Client-side sorting, column filters and the quick filter use this value, and editors start from it (double-click and Enter alike). Keep it pure: the quick filter caches each row's search text per row object and column set. A getter that throws for a row shows an error in that cell and reads as `undefined` for sorting, filtering, aggregation, grouping, pivot and list view (v3.0+, with a one-time development warning per column); before, it crashed the grid once the column was sorted, filtered or aggregated. |
+| `valueSetter` | `(params: GridValueSetterParams) => R` | — | v3.0+. Maps an edited value back onto the row (`{ value, row, field }` → updated row) when an edit is committed. Needed for editable `valueGetter` columns; without it the commit writes `row[field]` and a development warning is logged. |
+| `valueFormatter` | `(params: GridValueFormatterParams) => string` | — | Format the value into a display string (e.g. currency, dates). Does not affect editing, sorting or column filters; the quick filter also searches the formatted text. A formatter that throws leaves the value unformatted (the quick filter searches the raw value; v3.0+). |
 
 #### Rendering
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | Fully custom cell renderer. Receives `value`, `row`, `field`, `rowIndex`, `colIndex`. |
+| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | Fully custom cell renderer. Receives `value`, `formattedValue` (v2.1+, the `valueFormatter` output), `row`, `field`, `colDef`, `rowIndex`, `colIndex`, `rowMeta`. |
 | `renderHeader` | `(params: GridRenderHeaderParams) => ReactNode` | Custom header cell renderer. Use for icons, sort indicators, or rich headers. |
-| `renderEditCell` | `(params: GridRenderCellParams) => ReactNode` | Custom editor rendered when the cell enters edit mode. Requires `editable: true`. |
+| `renderEditCell` | `(params: GridRenderEditCellParams) => ReactNode` | Custom editor rendered when the cell enters edit mode. Requires `editable: true`. Receives the `renderCell` params (with `value` = the pending value) plus `onValueChange(value)`, `onCommit()` and `onCancel()` (v3.0+). Errors it throws are contained to the cell. |
 
 #### Editing
 
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `editable` | `boolean` | `false` | Enables inline cell editing. Commit is handled by `DataGrid.processRowUpdate`. |
+| `editable` | `boolean` | `false` | Enables inline cell editing (double-click or Enter). Commit is handled by `DataGrid.processRowUpdate`. Row-grouping group rows and auto-generated tree ancestors are never editable; tree-data parent rows are. |
 
 #### Spanning
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `colSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of columns this cell merges horizontally. |
-| `rowSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of rows this cell merges vertically. |
+| `colSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of columns this cell merges horizontally: the origin plus the next visible columns in render order, clamped to the end of its pinned section. `params.value` is the `valueGetter` result. |
+| `rowSpan` | `number \| ((params: GridRenderCellParams) => number)` | Number of rows this cell merges vertically, clamped to the end of its row section (top-pinned, scrolling or bottom-pinned rows) and to the first row with an expanded detail panel. |
+
+Span values are floored; `Infinity` means "to the end"; `NaN`, `0` and negative values mean no span. A span function that throws is treated as `1` (with a development warning). With both set, the origin covers the whole `colSpan × rowSpan` rectangle. See [Cell Spanning](features/cell-spanning.md).
 
 #### Styling
 
@@ -331,16 +391,16 @@ Defines the behavior and appearance of a single column.
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `sortable` | `boolean` | `true` | Enable/disable sorting for this column. |
-| `filterable` | `boolean` | `true` | Enable/disable filtering for this column. |
+| `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. |
-| `hideable` | `boolean` | `true` | Allow the user to hide this column via the panel. |
-| `pinnable` | `boolean` | `true` | Allow this column to be pinned via the UI. |
+| `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. |
-| `exportable` | `boolean` | `true` | Set to `false` to exclude from CSV, Excel, JSON, and Print exports. |
-| `groupable` | `boolean` | `true` | Allow this column to be used as a row grouping dimension. Set to `false` to prevent this field from being grouped, even when it appears in `rowGroupingModel`. |
-| `groupingValueFormatter` | `(params: { field: string; value: unknown }) => string` | — | Custom formatter for group-header labels when this column is the active grouping field. Falls back to `"field: value"` when omitted. |
-| `aggregable` | `boolean` | `true` | Allow this column to be aggregated. |
-| `availableAggregationFunctions` | `string[]` | all built-ins | Restrict which aggregation functions are computed and available for this column (e.g. `['sum', 'avg']`). Functions outside this list are skipped even if set in `aggregationModel`. |
+| `exportable` | `boolean` | `true` | Set to `false` to exclude from CSV, Excel, JSON, PDF and Print exports (including their subtotals and totals). |
+| `groupable` | `boolean` | `true` | Allow this column to be used as a row grouping dimension. Set to `false` to prevent this field from being grouped, even when it appears in `rowGroupingModel`, or used as a pivot row or column field (the pivot panel does not offer it). |
+| `groupingValueFormatter` | `(params: { field: string; value: unknown }) => string` | — | Custom formatter for group-header labels when this column is the active grouping field. Falls back to `"field: value"` when omitted or when it throws (v3.0+). |
+| `aggregable` | `boolean` | — | Whether this column can be aggregated. Unset, the toolbar's Summaries panel and the pivot panel's value fields offer it only for `type: 'number'` columns; `true` offers it for any type. `false` keeps it out of both panels, and an `aggregationModel` or `pivotModel` entry naming it is ignored (no footer total, group aggregate, pivot value or export total). |
+| `availableAggregationFunctions` | `string[]` | all built-ins | Restrict which aggregation functions are computed and available for this column (e.g. `['sum', 'avg']`). Functions outside this list are skipped even if set in `aggregationModel` or a pivot value field, the toolbar's Summaries panel and the pivot panel offer only these. |
 
 ---
 
@@ -348,11 +408,35 @@ Defines the behavior and appearance of a single column.
 
 | Function | Return | Description |
 | :--- | :--- | :--- |
-| `exportToCsv(rows, cols, options?)` | `void` | Triggers download of CSV file. |
-| `exportToJson(rows, cols, options?)` | `void` | Triggers download of JSON file. |
-| `exportToExcel(rows, cols, options?)` | `void` | Basic `.xls` export (zero-dep). |
-| `exportToExcelAdvanced(rows, cols, options?)` | `Promise<void>` | Real `.xlsx` export (styled, multi-sheet, lazy-loaded). |
-| `printGrid(rows, cols, title \| options)` | `void` | Opens browser print dialog. |
+| `exportToCsv(rows, cols, options?)` | `void` | Triggers download of a UTF-8 CSV file (with a byte-order mark and formula escaping by default, v3.0+). |
+| `exportToJson(rows, cols, options?)` | `void` | Triggers download of JSON file. Values, including aggregation values, are raw. |
+| `exportToExcel(rows, cols, options?)` | `void` | Basic `.xls` export (zero-dep HTML table). A `.xlsx` file name is renamed to `.xls` (v3.0+). |
+| `exportToExcelAdvanced(rows, cols, options?)` | `Promise<void>` | Real `.xlsx` export (styled, multi-sheet, lazy-loaded). Accepts `groupedRows` for outlined grouped reports (v2.1+). |
+| `exportToPdf(rows, cols, options?)` | `Promise<void>` | PDF report via the optional `jspdf` + `jspdf-autotable` peers. `font` registers a Unicode font (v3.0+). See [PDF Export](features/pdf-export.md). |
+| `printGrid(rows, cols, titleOrOptions?)` | `Promise<void>` | Opens the browser print dialog. The third argument is a title string or `PrintOptions`. |
+
+In every exporter, a non-empty `selectedRows` takes precedence over `groupedRows` (the selected rows are exported flat) and the totals are recomputed over the selected rows (v3.0+). See the [Export Guide](features/export-guide.md#selection-grouping-and-totals).
+
+Every exporter takes `columns` typed for your rows (`GridColDef<R>[]`) or untyped (`GridColDef[]`), and its options also accept `getRowId?: (row: R) => GridRowId`. Pass the grid's `getRowId` when you use one: `selectedRows` holds those ids, and since v3.0 the grid no longer copies them onto `row.id`.
+
+---
+
+## 🧩 Standalone Components
+
+The grid's building blocks are exported with their props types (the props types since v3.0). `DataGrid` renders all of them itself; import them to build your own layout or slot.
+
+| Component | Props type | Description |
+| :--- | :--- | :--- |
+| `ColumnVisibilityPanel` | `ColumnVisibilityPanelProps` | Controlled column show/hide (and optional reorder) list, for use outside the grid (v2.1+). See [Column Visibility](components/column-visibility.md). |
+| `GridToolbar` | `GridToolbarProps` | The built-in toolbar. See [`GridToolbar`](#️-gridtoolbar). |
+| `Pagination` | `PaginationProps` | The built-in pagination bar (v3.0+ export), e.g. to wrap in a `pagination` slot. See [Pagination](components/pagination.md). |
+| `FilterPanel` | `FilterPanelProps` | The filter rule editor (`filterModel`, `columns`, `onFilterModelChange`). See [Filter Panel](components/filter-panel.md). |
+| `GridTooltip` | `GridTooltipProps` | Tooltip wrapper. See [Tooltip](components/tooltip.md). |
+| `Header` | `HeaderProps` | The column header rows. See [Header](components/header.md). |
+| `Row` | `RowProps` | One body row. See [Row](components/row.md). |
+| `Cell` | `CellProps` | One body cell. See [Cell](components/cell.md). |
+| `Skeleton` | `SkeletonProps` | Loading placeholder (`rows`, `columns`, both default 5). |
+| `Button`, `Input`, `Checkbox` | `ButtonProps`, `InputProps`, `CheckboxProps` | The grid's form controls. `Button` defaults to `type="button"`. |
 
 ---
 
@@ -362,9 +446,14 @@ Defines the behavior and appearance of a single column.
 Context provider for overriding the grid's visual system.
 
 #### `GridTheme` Object
-- **Colors**: `primary`, `secondary`, `header`, `border`, `rowHover`, `rowSelected`.
-- **Typography**: `fontFamily`, `fontSize`, `fontWeight`.
-- **Spacing**: `cellPadding`, `headerHeight`, `rowHeight`.
+- **`mode`**: `'light'` (default) or `'dark'`: the complete base palette the provider pins before applying the other keys (v3.0+).
+- **`colors`**: `primary`, `primaryDark`, `primaryLight`, `primaryFocus`, `secondary*`, `success`, `warning`, `error`, `info`, `white`, `black`, `gray` (`{ 50 … 900 }`). Toolbar, menu, selection and focus accents derive from `primary*` unless set directly.
+- **`typography`**: `fontFamily`, `fontFamilyMono`, `fontSizeXs` … `fontSizeXl`.
+- **`spacing`**: `xs` … `xxl`. **`borders`**: `widthThin/Medium/Thick`, `radiusSm` … `radiusXl`, `color`, `colorHover`. **`shadows`**: `sm` … `xl`.
+- **`grid`**: surfaces (`background`, `borderColor`, `headerBackground`, `headerText`, `headerHoverBackground`, `headerSortedBackground`, `rowText`, `rowHoverBackground`, `rowAlternateBackground`, `rowSelectedBackground`, `rowSelectedHoverBackground`, `cellFocusBorder`, `pinnedLeftShadow`, `pinnedRightShadow`, `checkboxBg`, `checkboxBorder`), sizing (`rowHeightCompact`, `rowHeightStandard`, `rowHeightComfortable`, `headerHeight` in px, read by the grid's layout; the `rowHeight` / `headerHeight` props win), `cellPaddingX`, `cellPaddingY`, `cellFontSize`, `headerFontSize`.
+- **`toolbar`**, **`overlays`**, **`scrollbar`** (`thumbColor`, `trackColor`, `size`), **`skeleton`** (`baseColor`, `highlightColor`), **`transitions`**.
+
+Presets: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compactTheme`. See [Theming](customization/theming.md).
 
 ---
 
@@ -374,6 +463,8 @@ Context provider for overriding the grid's visual system.
 
 Creates a typed ref to pass to the `apiRef` prop. Gives you imperative access to the grid after mount.
 
+`apiRef.current` is never `null`: until the grid mounts it holds an API whose methods do nothing and whose getters return empty values. The grid installs the live API in a layout effect, so it is ready in your own `useLayoutEffect` / `useEffect` and in event handlers (v3.0+).
+
 ```tsx
 import { useGridApiRef } from '@opencorestack/opengridx';
 
@@ -409,10 +500,11 @@ const { aggregationResult, isLoading } = useAggregation({
 
 | Param | Type | Description |
 | :--- | :--- | :--- |
-| `rows` | `GridRowModel[]` | The rows to aggregate. |
+| `rows` | `R[]` | The rows to aggregate (already filtered: the hook aggregates every row it is given). Any object row type (v3.0+). |
 | `aggregationModel` | `GridAggregationModel` | Map of `field → aggFn` (e.g. `{ salary: 'sum' }`). |
-| `isServerSide` | `boolean` | If `true`, skips client computation and uses `serverAggregationResults`. |
-| `filterModel` | `GridFilterModel` | Optional — restricts aggregation to filtered rows. |
+| `isServerSide` | `boolean` | If `true`, skips client computation and uses `serverAggregationResults`, else the result of `dataSource.getAggregations`. The grid sets it whenever a `dataSource` drives the rows (server or infinite pagination, server sorting or server filtering). |
+| `columns` | `GridColDef[]` | Optional — column definitions, so values are read through each column's `valueGetter` and `availableAggregationFunctions` is honoured. |
+| `filterModel` | `GridFilterModel` | Optional — sent to `dataSource.getAggregations`. It does not filter `rows`. |
 | `sortModel` | `GridSortItem[]` | Optional — used when `dataSource` is provided. |
 | `dataSource` | `GridDataSource` | Optional — server-side data adapter for async aggregation. |
 | `serverAggregationResults` | `GridAggregationResult \| null` | Pre-fetched results when `isServerSide: true`. |
@@ -422,8 +514,8 @@ const { aggregationResult, isLoading } = useAggregation({
 | Field | Type | Description |
 | :--- | :--- | :--- |
 | `aggregationResult` | `GridAggregationResult` | Map of `field → computed value`. |
-| `isLoading` | `boolean` | `true` while a server-side fetch is in progress. |
-| `error` | `unknown` | Set if the server-side fetch threw. |
+| `isLoading` | `boolean` | `true` while the `getAggregations` request for the current model, filter and sort is pending. |
+| `error` | `unknown` | Set if the request for the current model, filter and sort failed. |
 
 **Built-in aggregation functions:** `sum`, `avg`, `min`, `max`, `count`, `unique`
 
@@ -433,7 +525,7 @@ You can also use `formatAggregationValue(value, fnName)` to produce a display st
 
 ### `usePivot(rawRows, rawCols, model, enabled)`
 
-Headless hook that transforms a flat dataset into pivot rows and pivot column definitions. Pass the output directly to `<DataGrid rows={} columns={} />` when `pivotMode` is active.
+Headless hook that transforms a flat dataset into pivot rows and pivot column definitions, with the same engine `<DataGrid pivotMode />` uses. Use it to pivot outside the grid (charts, custom exports). To show a pivot in the grid, prefer `pivotMode`: it also filters the source rows, keeps the Grand Total row last when sorting and leaves it out of select-all, which a grid given `pivotRows` as plain rows does not do.
 
 ```tsx
 import { usePivot } from '@opencorestack/opengridx';
@@ -459,7 +551,7 @@ const { pivotRows, pivotColumns, isValid } = usePivot(
 
 | Param | Type | Description |
 | :--- | :--- | :--- |
-| `rawRows` | `GridRowModel[]` | Original flat dataset. |
+| `rawRows` | `R[]` | Original flat dataset. Any object row type (v3.0+); `rawCols` may be `GridColDef<R>[]` or `GridColDef[]`. |
 | `rawCols` | `GridColDef[]` | Original column definitions. |
 | `model` | `GridPivotModel` | Pivot configuration — `rowFields`, `columnFields`, `valueFields`. |
 | `enabled` | `boolean` | When `false`, returns empty arrays immediately (no computation). |
@@ -468,10 +560,10 @@ const { pivotRows, pivotColumns, isValid } = usePivot(
 
 | Field | Type | Description |
 | :--- | :--- | :--- |
-| `pivotRows` | `GridRowModel[]` | Transformed rows ready for the grid. |
-| `pivotColumns` | `GridColDef[]` | Generated column definitions for each pivot key. |
-| `colKeys` | `string[]` | The distinct column pivot values used. |
-| `isValid` | `boolean` | `false` if the model is incomplete (e.g. no `rowFields` or `valueFields`). |
+| `pivotRows` | `GridRowModel[]` | One row per row-field combination (ids `'__pivot_row__:["value", …]'`, from its row-field values), then the Grand Total row (id `'__pivot_grand_total__'`). There is no Grand Total row when `rawRows` is empty. |
+| `pivotColumns` | `GridColDef[]` | Row-label columns (keeping the source column's formatter, renderer, type and alignment; `hideable: false`), then one value column per column key and value field. Value columns format aggregates like the footer. |
+| `colKeys` | `string[]` | The distinct column-field value combinations, ordered by value (numbers numerically, strings naturally, blanks last). `['']` when there are no column fields. |
+| `isValid` | `boolean` | `false` if the model has no usable row field or value field (fields on `groupable: false` columns and value fields whose function `availableAggregationFunctions` does not allow are skipped). |
 
 #### `GridPivotModel`
 
@@ -533,7 +625,9 @@ const { initialState, onStateChange, clearState } = useGridStateStorage({
 | :--- | :--- | :--- |
 | `initialState` | `GridState \| undefined` | Restored state from storage — pass to `DataGrid.initialState`. |
 | `onStateChange` | `(state: GridState) => void` | Callback to pass to `DataGrid.onStateChange`. |
-| `clearState` | `() => void` | Removes the saved state from storage. |
+| `clearState` | `() => void` | Removes the saved state from storage and cancels a pending write. |
+
+If the key can change while the grid stays mounted, remount the grid with it (`<DataGrid key={storageKey} … />`): the grid reads `initialState` only on mount. When the browser blocks storage, the hook falls back to no persistence.
 
 ---
 
@@ -569,13 +663,19 @@ interface GridPaginationModel {
 interface GridPivotModel {
   rowFields: string[];
   columnFields: string[];
-  valueFields: { field: string; aggFn: string; headerName?: string }[];
+  valueFields: GridPivotValueField[];
+}
+
+interface GridPivotValueField {
+  field: string;
+  aggFn: GridPivotAggFn; // 'sum' | 'avg' | 'count' | 'min' | 'max'
+  headerName?: string;
 }
 ```
 
 ### `GridLocaleText`
 
-Override user-visible strings in the Pagination component. All fields are optional.
+Override user-visible strings in the Pagination component and the empty state. All fields are optional.
 
 ```typescript
 interface GridLocaleText {
@@ -597,26 +697,53 @@ interface GridRowMeta {
   groupingField?: string;
   groupingValue?: unknown;
   groupLabel?: string;
-  descendantCount?: number;
+  descendantCount?: number; // data rows below, at any depth, that pass the filter
   isExpanded?: boolean;
-  isGroupRow?: boolean;
+  isGroupRow?: boolean;     // synthetic row: group, subtotal or auto-created tree parent
+  isGroupFooter?: boolean;  // v3.0: the subtotal row of a group ('footer' aggregation position)
 }
 ```
 
+### `GridGroupedExportRow`
+
+One entry of the list returned by `apiRef.current.getGroupedExportRows()`, and the element type of every exporter's `groupedRows` option. Traverse in array order to reproduce the grouping.
+
+```typescript
+interface GridGroupedExportRow {
+  type: 'group-header' | 'leaf' | 'group-subtotal' | 'grand-total';
+  depth: number;                              // 0 = top-level group
+  groupField?: string;                        // absent on 'leaf' and 'grand-total'
+  groupValue?: unknown;                       // absent on 'leaf' and 'grand-total'
+  groupLabel?: string;                        // v3.0: label as the grid shows it ('group-header', 'group-subtotal')
+  aggregatedValues?: Record<string, unknown>; // 'group-subtotal' and 'grand-total'
+  row?: GridRowModel;                         // 'leaf' only: your row object
+}
+```
+
+### `GridDetailPanelHeight`
+
+```typescript
+type GridDetailPanelHeight = number | 'auto';
+```
+
+Returned by `getDetailPanelHeight`.
+
 ---
 
 ## 📡 Event Callback Types
 
 These interfaces describe the parameter objects passed to every event callback prop.
 
+Keyboard activation uses the same callbacks: **Enter** on a cell that is not editable runs the row-click handling (`onRowClick`, click-to-select, group expansion). See [Keyboard & Accessibility](features/keyboard-navigation.md) for every key and the ARIA structure.
+
 ### `GridRowParams<R>`
-Passed to `onRowClick`.
+Passed to `onRowClick` and `onRowDoubleClick`.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `row` | `R` | The full row data object. |
 | `id` | `GridRowId` | Unique identifier of the row. |
-| `rowIndex` | `number` | Zero-based index of the row in the visible dataset. |
+| `rowIndex` | `number` | Zero-based index of the row among the rendered rows: top-pinned, then the current page, then bottom-pinned (the row's `data-rowindex`). |
 
 ### `GridCellParams<R>`
 Passed to `onCellClick` and `isCellEditable`.
@@ -627,8 +754,26 @@ Passed to `onCellClick` and `isCellEditable`.
 | `field` | `string` | The column field name. |
 | `value` | `unknown` | The cell value (after `valueGetter`, before `valueFormatter`). |
 | `colDef` | `GridColDef<R>` | The column definition. |
-| `rowIndex` | `number` | Zero-based row index in the visible dataset. |
-| `colIndex` | `number` | Zero-based column index. |
+| `rowIndex` | `number` | Zero-based index of the row among the rendered rows: top-pinned, then the current page, then bottom-pinned. |
+| `colIndex` | `number` | Zero-based position of the column among the visible data columns in render order (left-pinned, unpinned, right-pinned); system columns are not counted. It does not change with horizontal scrolling (v3.0). |
+
+### `GridRenderEditCellParams<R>`
+Passed to `renderEditCell` (v3.0+). Everything in `GridRenderCellParams` (`value` is the pending, uncommitted value), plus:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `onValueChange` | `(value: unknown) => void` | Updates the pending value. Nothing is saved until `onCommit`. |
+| `onCommit` | `() => void` | Commits the pending value through `processRowUpdate` and leaves edit mode. |
+| `onCancel` | `() => void` | Discards the pending value and leaves edit mode. |
+
+### `GridValueSetterParams<R>`
+Passed to `valueSetter` (v3.0+).
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `unknown` | The committed value from the editor. |
+| `row` | `R` | The row as it was before the edit. |
+| `field` | `string` | The column field name. |
 
 ### `GridColumnOrderChangeParams`
 Passed to `onColumnOrderChange`.
@@ -636,25 +781,27 @@ Passed to `onColumnOrderChange`.
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `column` | `GridColDef` | The column definition that was moved. |
-| `oldIndex` | `number` | Previous column index. |
-| `targetIndex` | `number` | New column index after the move. |
+| `oldIndex` | `number` | The column's position before the move, in the grid's full column order: every current column (hidden ones and the row-grouping `__group__` column included), in its current order. |
+| `targetIndex` | `number` | Its position after the move, in the same order. |
+
+Splicing the full order with these indices gives the new order. A controlled `columnOrder` that lists only some columns, or no `__group__`, is not that order: use `onColumnOrderModelChange`, which hands you the whole new order.
 
 ### `GridRowOrderChangeParams<R>`
 Passed to `onRowOrderChange`.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `row` | `R` | The row data object that was moved. |
-| `oldIndex` | `number` | Previous row index. |
-| `targetIndex` | `number` | New row index after the move. |
+| `row` | `R` | The row that was dragged: your own object from `rows`. |
+| `oldIndex` | `number` | Its position in your `rows` prop (`rows[oldIndex] === row`), whatever the sort, filter, page or pinned rows on screen. |
+| `targetIndex` | `number` | The position in `rows` of the row it was dropped on. Remove the row at `oldIndex` and insert it at `targetIndex`. |
 
 ### `GridRowScrollEndParams`
 Passed to `onRowsScrollEnd`.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `visibleTop` | `number` | Pixel offset of the topmost visible row. |
-| `visibleBottom` | `number` | Pixel offset of the bottommost visible row. |
+| `visibleTop` | `number` | Scroll offset (`scrollTop`) of the viewport's top edge, in pixels. |
+| `visibleBottom` | `number` | Offset of the viewport's bottom edge (`visibleTop + viewportHeight`). |
 | `viewportHeight` | `number` | Current height of the scroll viewport in pixels. |
 
 ### `GridDetailPanelParams<R>`
@@ -664,7 +811,7 @@ Passed to `getDetailPanelContent` and `getDetailPanelHeight`.
 | :--- | :--- | :--- |
 | `row` | `R` | The full row data object. |
 | `id` | `GridRowId` | Unique identifier of the row. |
-| `rowIndex` | `number` | Zero-based index of the row in the visible dataset. |
+| `rowIndex` | `number` | Zero-based index of the row among the rendered rows: top-pinned, then the current page, then bottom-pinned (the row's `data-rowindex`). |
 
 ---
 
@@ -684,8 +831,8 @@ The object passed to `getRows` by the grid on every data fetch.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `startRow` | `number` | Zero-based index of the first row to fetch (based on `page * pageSize`). |
-| `endRow` | `number` | Zero-based index of the last row to fetch (exclusive). |
+| `startRow` | `number` | Zero-based index of the first row to fetch. Server pagination: `page * pageSize`. Infinite scroll: the number of rows already loaded. Client pagination and tree children: `0`. |
+| `endRow` | `number` | Zero-based index just past the last row to fetch (exclusive), so `rows.slice(startRow, endRow)` is the requested range. Server pagination: `startRow + pageSize`. Infinite scroll: `(page + 1) * pageSize`. When the grid wants every row (client pagination, the children of a tree node) it is `Number.MAX_SAFE_INTEGER`. |
 | `sortModel` | `GridSortItem[]` | Active sort configuration. Empty array when no sort is applied. |
 | `filterModel` | `GridFilterModel` | Active filter state. Has empty `items` when no filters are applied. |
 | `groupKeys` | `string[]` | Path of grouping key values for the current group level (used in lazy-loaded tree/grouping). Empty array for the root level. |
@@ -712,7 +859,7 @@ import {
   GridColDef,
 } from '@opencorestack/opengridx';
 
-interface Employee extends GridRowModel {
+interface Employee {
   id: number;
   name: string;
   department: string;
@@ -764,7 +911,15 @@ export default function EmployeeGrid() {
 }
 ```
 
-**How the grid decides when to call `getRows`:** The hook fires (with a 300 ms debounce) whenever `paginationMode`, `sortingMode`, or `filterMode` is set to `'server'` AND a `dataSource` is provided. Any change to `sortModel`, `filterModel`, or `paginationModel` re-triggers the fetch. Stale responses from superseded requests are silently discarded — only the latest request updates the grid.
+**How the grid decides when to call `getRows`:** whenever a `dataSource` is provided, with a 300 ms debounce that collapses rapid changes into one request. The grid shows its loading state from the moment a request is scheduled, so the empty state never flashes up first.
+
+| `paginationMode` | Request | Refetches when |
+| :--- | :--- | :--- |
+| `'client'` (default) | Every row once (`startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`). The grid pages, and sorts/filters unless those modes are `'server'`. | A `'server'` sort or filter changes, or `getRows` changes. Page changes never refetch. |
+| `'server'` | One page. The response replaces the rows. | The page, page size, sort, filter or aggregation model changes, or `getRows` changes. |
+| `'infinite'` | The rows from the end of what is loaded up to the current page. Responses are appended; rows whose id is already loaded are skipped. | The page grows. A sort, filter, page-size or `getRows` change restarts the list at row 0 and reports page 0 through `onPaginationModelChange`; a smaller page reloads the list up to that page. |
+
+Models are compared by content, so inline `sortModel`/`filterModel`/`aggregationModel` objects and a `dataSource` object recreated with the same `getRows` function do not refetch. A response for parameters that have changed since (another page, sort, filter or `dataSource`, or a removed `dataSource`) is discarded. Fetched rows are keyed with `getRowId`. When `getRows` rejects, the error overlay shows the rejection's `message` (an `Error`, a string, or any object with a string `message`) and a **Retry** button that requests the rows again.
 
 ---
 
@@ -835,7 +990,7 @@ interface GridFilterModel {
 | :--- | :--- | :--- | :--- |
 | `items` | `(GridFilterItem \| GridFilterGroup)[]` | `[]` | Root-level filter conditions or nested groups. |
 | `logicOperator` | `'and' \| 'or'` | `'and'` | How to combine the root `items`. |
-| `quickFilterValues` | `string[]` | `[]` | Each string must match at least one field in the row (all strings must match). Applied before `items`. |
+| `quickFilterValues` | `string[]` | `[]` | Search terms. Every term must be found (case-insensitive substring) in at least one visible, filterable column, read through `valueGetter` and, if set, `valueFormatter`. The row `id` and non-column fields are not searched. Blank terms are ignored. Applied together with `items`. The toolbar search box splits the typed text on whitespace. |
 
 ### `GridFilterItem`
 
@@ -846,7 +1001,7 @@ A single column filter condition.
 | `id` | `string \| number` | No | Optional stable identifier for this item (useful for controlled updates). |
 | `field` | `string` | Yes | The column field to filter on. |
 | `operator` | `GridFilterOperator` | Yes | The comparison operator to apply. |
-| `value` | `unknown` | No | The value to compare against. Not required for `isEmpty` / `isNotEmpty`. |
+| `value` | `unknown` | No | The value to compare against. Not required for `isEmpty` / `isNotEmpty`. For every other operator, an empty value (`undefined`, `null`, a blank string or an empty array) means the item does not filter. |
 
 ### `GridFilterGroup`
 
@@ -864,13 +1019,25 @@ A nested group of filter conditions combined with a logical operator. Groups can
 type GridFilterOperator =
   | 'contains' | 'equals' | 'startsWith' | 'endsWith'
   | 'isEmpty'  | 'isNotEmpty' | 'isAnyOf'
-  | '>'  | '>=' | '<' | '<=' | '!='
-  | 'is' | 'not';
+  | '=' | '>'  | '>=' | '<' | '<=' | '!='
+  | 'is' | 'not'
+  | 'after' | 'onOrAfter' | 'before' | 'onOrBefore';
 ```
 
+| Operator | Matches when the cell… |
+| :--- | :--- |
+| `contains` / `startsWith` / `endsWith` / `equals` | contains / starts with / ends with / equals the value (case-insensitive text). |
+| `=` `!=` `>` `>=` `<` `<=` | compares numerically with the value (numeric strings accepted). A blank cell never matches, except for `!=`, which it always matches. |
+| `is` / `not` | equals / does not equal the value (case-insensitive). On `type: 'date'` columns and `Date` cells: the same / a different local calendar day. |
+| `after` / `onOrAfter` / `before` / `onOrBefore` | is a later / same-or-later / earlier / same-or-earlier local calendar day. |
+| `isAnyOf` | equals any value in the array (a single value counts as a one-element array). |
+| `isEmpty` / `isNotEmpty` | is / is not `null`, `undefined` or blank. No value needed. |
+
+Dates can be `Date` objects, epoch milliseconds or date strings; a `'YYYY-MM-DD'` string is read as a local date. Cells are read through the column's `valueGetter`.
+
 ### Default Operators per Column Type
 
-The filter panel shows only the operators relevant to each column's `type`. These are also the operators used when the grid applies client-side filtering.
+The filter panel shows only the operators relevant to each column's `type`; an operator set programmatically that the type does not list is still shown and applied. Every operator works in a programmatic `filterModel` on any column.
 
 | Column `type` | Default operator | Available operators |
 | :--- | :--- | :--- |
@@ -909,10 +1076,12 @@ const filterModel: GridFilterModel = {
 
 ## 💾 `GridInitialState` and `GridState`
 
-`GridInitialState` is a type alias for `GridState`. Pass it to `initialState` to restore persisted grid state on mount (e.g. from `localStorage`). Each key corresponds to a feature slice — all are optional.
+`GridInitialState` is `GridState` with every column field optional as well. Pass it to `initialState` to restore persisted grid state on mount (e.g. from `localStorage`). Each key corresponds to a feature slice — all are optional. A `GridState` from `onStateChange` is a valid `GridInitialState`.
 
 ```typescript
-type GridInitialState = GridState;
+interface GridInitialState extends Omit<GridState, 'columns'> {
+  columns?: Partial<GridColumnsState>; // e.g. { columnVisibilityModel: { age: false } }
+}
 
 interface GridState {
   sorting?:    GridSortingState;
@@ -999,16 +1168,18 @@ type GridAggregationResult = Record<string, unknown>;
 
 | Function | Input | Output | Description |
 | :--- | :--- | :--- | :--- |
-| `sum` | numeric values | `number` | Sum of all non-null numeric values in the group. |
-| `avg` | numeric values | `number \| null` | Arithmetic mean. Returns `null` if there are no numeric values. |
-| `min` | numeric values | `number \| null` | Smallest numeric value. Returns `null` if there are no numeric values. |
-| `max` | numeric values | `number \| null` | Largest numeric value. Returns `null` if there are no numeric values. |
-| `count` | any values | `number` | Count of non-null values. |
-| `unique` | any values | `number` | Count of distinct non-null values (uses a `Set`). |
+| `sum` | numeric values | `number` | Sum of the numeric values (numbers, numeric strings, `Date`s as timestamps). Blank cells, booleans and arrays are skipped. `0` when there are none. |
+| `avg` | numeric values | `number \| null` | Arithmetic mean of the same values. Returns `null` if there are none. |
+| `min` | numeric values | `number \| Date \| null` | Smallest value; a `Date` when the smallest value is a `Date`. Returns `null` if there are none. |
+| `max` | numeric values | `number \| Date \| null` | Largest value; a `Date` when the largest value is a `Date`. Returns `null` if there are none. |
+| `count` | any values | `number` | Count of values that are not `null`, `undefined` or a blank string. |
+| `unique` | any values | `number` | Count of distinct values, blanks excluded (uses a `Set`). |
+
+Cells are read through the column's `valueGetter`.
 
 All built-in functions are exported as the `BuiltInAggFn` type: `'sum' | 'avg' | 'count' | 'min' | 'max' | 'unique'`.
 
-Use `formatAggregationValue(value, fnName)` to turn a raw result into a display string. `avg` is formatted to 2 decimal places; all other numbers use `toLocaleString()`.
+Use `formatAggregationValue(value, fnName)` to turn a raw result into a display string: `'—'` for `null` / `undefined`, `avg` to at most 2 decimal places, other numbers with `toLocaleString()`, anything else with `String(value)`.
 
 ### `getAggregationPosition` Callback
 
@@ -1016,13 +1187,17 @@ Use `formatAggregationValue(value, fnName)` to turn a raw result into a display
 getAggregationPosition?: (groupNode: GridTreeNode | null) => 'inline' | 'footer' | null
 ```
 
-Called once per group node (and once with `null` for the grand-total / root level) to decide where the aggregated row appears:
+The return type is exported as `GridAggregationPosition` (`'inline' | 'footer' | null`, v3.0+).
 
-| Return value | Effect |
-| :--- | :--- |
-| `'inline'` | Aggregation values appear inside the group header row itself. |
-| `'footer'` | A separate aggregation row is rendered below the group's last row. |
-| `null` | Aggregation result is hidden for this group. |
+Called on every render for each group node, with the node's current `isExpanded`, and once with `null` for the grand total. Only the answers matter, so an inline arrow function is fine.
+
+| Return value | For a group | For the grand total (`null`) |
+| :--- | :--- | :--- |
+| `'inline'` | Aggregates on the group row (the default). | The footer row is shown. |
+| `'footer'` | Aggregates on a subtotal row placed after the group's children while the group is expanded; the group row shows none. While the group is collapsed there is no subtotal row, so the aggregates stay on the group row. | The footer row is shown (the default). |
+| `null` | No aggregates for this group, on screen or in `getGroupedExportRows()` (no `group-subtotal` entry). | The footer row is hidden, and `getGroupedExportRows()` has no `grand-total` entry. |
+
+Subtotal rows are synthetic: `params.rowMeta` has `isGroupRow: true` and `isGroupFooter: true` (plus the group's `groupingField`, `groupingValue`, `groupLabel`), they carry the aggregates under each column's field, and they are never selected, edited or given a detail panel. Their row element has the class `ogx__row--group-footer`. To show subtotals below expanded groups only: `getAggregationPosition={(node) => (node === null ? 'footer' : node.isExpanded ? 'footer' : 'inline')}`.
 
 ### Aggregation + Row Grouping Example
 
@@ -1036,7 +1211,7 @@ import {
   GridRowGroupingModel,
 } from '@opencorestack/opengridx';
 
-interface Employee extends GridRowModel {
+interface Employee {
   id: number;
   name: string;
   department: string;
@@ -1167,7 +1342,15 @@ export default function GroupedHeadersGrid() {
 }
 ```
 
-The grid renders two header rows: the spanning group row on top, and the regular per-column header row below. Groups that are not referenced in `columnGroupingModel` are rendered without a spanning header.
+The grid renders one group header row per nesting level above the regular per-column header row. Columns that are not referenced in `columnGroupingModel` get an empty filler cell in the group rows.
+
+Group rows follow the columns as they are rendered:
+
+- **Order, visibility and pinning** — a group covers its visible member columns in their current order. A group whose members are not adjacent (or that spans a pinned-section boundary) renders one group cell per run of adjacent members. Group cells over pinned columns are sticky, so they stay above their columns on horizontal scroll.
+- **Widths** — a group cell is exactly as wide as its member columns, including flex, `auto` and percentage widths and manual resizes.
+- **`headerClassName`** — added to the group cell's class list (next to `ogx-col-group-cell` and `ogx-col-group-cell--group`).
+- **Column reordering** — header drag and the toolbar / columns-panel reorder keep groups intact: a column can only be moved onto a column of the same innermost group, and an ungrouped column only onto another ungrouped column.
+- **Accessibility** — group cells are `role="columnheader"` with `aria-colspan` (visible member columns) and `aria-colindex`; filler cells are `aria-hidden`. The grid's `aria-rowcount` includes the group header rows.
 
 ---
 
@@ -1178,7 +1361,7 @@ List view renders the grid as a single-column list of cards, replacing all norma
 ### `GridListViewColDef<R>`
 
 ```typescript
-interface GridListViewColDef<R extends GridRowModel = GridRowModel> {
+interface GridListViewColDef<R extends GridValidRowModel = GridRowModel> {
   field: string;
   renderCell: (params: GridRenderCellParams<R>) => React.ReactNode;
 }
@@ -1189,9 +1372,9 @@ The `renderCell` function receives the full `GridRenderCellParams` (including `r
 ### Usage Example
 
 ```tsx
-import { DataGrid, GridListViewColDef, GridRenderCellParams } from '@opencorestack/opengridx';
+import { DataGrid, GridListViewColDef, GridRenderCellParams, GridRowModel } from '@opencorestack/opengridx';
 
-interface Employee extends GridRowModel {
+interface Employee {
   id: number;
   name: string;
   department: string;
@@ -1228,7 +1411,7 @@ export default function MobileGrid() {
 ### `exportToPdf`
 
 ```ts
-function exportToPdf<R extends GridRowModel>(
+function exportToPdf<R extends GridValidRowModel>(
     rows: R[],
     columns: GridColDef<R>[],
     options?: PdfExportOptions
@@ -1246,6 +1429,7 @@ interface PdfExportOptions {
     logoUrl?: string;
     orientation?: 'portrait' | 'landscape';
     selectedRows?: (string | number)[];
+    getRowId?: (row: GridRowModel) => GridRowId; // v3.0+
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     filterModel?: GridFilterModel | null;
@@ -1254,6 +1438,7 @@ interface PdfExportOptions {
     headerBackgroundColor?: string;
     headerTextColor?: string;
     fontSize?: number;
+    font?: { name: string; data: string; boldData?: string }; // v3.0+
 }
 ```
 
@@ -1263,12 +1448,14 @@ interface PdfExportOptions {
 | `title` | `string` | — | Adds a branded header block above the table |
 | `logoUrl` | `string` | — | Data URI or URL for a logo image (requires `title`) |
 | `orientation` | `'portrait' \| 'landscape'` | `'landscape'` | Page orientation |
-| `selectedRows` | `(string \| number)[]` | — | Export only rows with these IDs |
+| `selectedRows` | `(string \| number)[]` | — | Export only rows with these IDs. Takes precedence over `groupedRows`; footer totals are recomputed over the selection (v3.0+) |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, to match `selectedRows` against rows that keep their id elsewhere (v3.0+) |
 | `aggregationResult` | `Record<string, unknown>` | — | From `apiRef.current.getAggregationResult()` |
 | `aggregationModel` | `GridAggregationModel` | — | From `apiRef.current.getAggregationModel()` |
-| `filterModel` | `GridFilterModel` | — | From `apiRef.current.getFilterModel()` |
-| `groupedRows` | `GridGroupedExportRow[]` | — | Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`. When provided, the PDF table reflects the grouping structure (group-header, indented leaves, subtotals, grand total). |
+| `filterModel` | `GridFilterModel` | — | From `apiRef.current.getFilterModel()`. Nested groups, the logic operator and quick-search terms are summarised; rules without a value are skipped |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`. When provided (and `selectedRows` is empty), the PDF table reflects the grouping structure (group-header, indented leaves, subtotals, grand total). |
 | `alternateRowColor` | `boolean` | `true` | Alternating row background shading |
-| `headerBackgroundColor` | `string` | `'#4f46e5'` | Column header cell background (hex) |
-| `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (hex) |
+| `headerBackgroundColor` | `string` | `'#4f46e5'` | Column header cell background (`#rrggbb` / `#rgb`) |
+| `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+) |