@opencorestack/opengridx 2.1.0 → 3.0.1

package/docs/features/pdf-export.md

@@ -10,18 +10,29 @@ Generate a styled PDF report from grid data using `exportToPdf()`.
 npm install jspdf jspdf-autotable
 ```
 
+> **Currency symbols such as `₹` print as `?` by default.** The built-in Helvetica font only covers Latin-1. Pass the [`font` option](#non-latin-text-and-unicode-fonts) with a Unicode `.ttf`:
+>
+> ```ts
+> await exportToPdf(rows, columns, { fileName: 'invoices', font: { name: 'NotoSans', data: notoSansBase64 } });
+> ```
+
+> **Large datasets:** PDF generation runs on the main thread, and time and file size grow with every row: 50,000 grouped rows took 10–16 s (the page is unresponsive meanwhile) and produced a file of about 120 MB. For more than a few thousand rows, export CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) instead, or export a filtered subset.
+
 ## Basic Usage
 
 ```tsx
-import { exportToPdf, useGridApiRef } from '@opencorestack/opengridx';
+import {
+    DataGrid, GridToolbar, exportToPdf, useGridApiRef,
+    type GridColDef, type GridRowModel,
+} from '@opencorestack/opengridx';
 
-function MyGrid() {
+function MyGrid({ rows, columns }: { rows: GridRowModel[]; columns: GridColDef[] }) {
     const apiRef = useGridApiRef();
 
     const handleExport = async () => {
         await exportToPdf(
-            apiRef.current.getVisibleRows(),
-            apiRef.current.getVisibleColumns(),
+            apiRef.current.getAllFilteredRows(),  // every row passing the filter, all pages
+            apiRef.current.getVisibleColumns(),   // on-screen columns, in display order
             { fileName: 'my-report', title: 'Sales Report' }
         );
     };
@@ -31,14 +42,13 @@ function MyGrid() {
             apiRef={apiRef}
             rows={rows}
             columns={columns}
-            slots={{
-                toolbar: () => (
-                    <GridToolbar
-                        renderExportButton={() => (
-                            <button onClick={handleExport}>Export PDF</button>
-                        )}
-                    />
-                ),
+            slots={{ toolbar: GridToolbar }}
+            slotProps={{
+                toolbar: {
+                    renderExportButton: () => (
+                        <button onClick={handleExport}>Export PDF</button>
+                    ),
+                },
             }}
         />
     );
@@ -49,7 +59,7 @@ function MyGrid() {
 
 ```tsx
 await exportToPdf(
-    apiRef.current.getVisibleRows(),
+    apiRef.current.getAllFilteredRows(),
     apiRef.current.getVisibleColumns(),
     {
         fileName: 'employee-report',
@@ -76,14 +86,49 @@ await exportToPdf(
 | `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`; the footer totals are recomputed over the selected rows (v3.0+) |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, when it has one, so `selectedRows` match rows that keep their id in another field (v3.0+) |
 | `aggregationResult` | `Record<string, unknown>` | — | From `apiRef.current.getAggregationResult()` |
 | `aggregationModel` | `GridAggregationModel` | — | From `apiRef.current.getAggregationModel()` |
-| `filterModel` | `GridFilterModel` | — | From `apiRef.current.getFilterModel()` |
+| `filterModel` | `GridFilterModel` | — | From `apiRef.current.getFilterModel()`. Summarised under the title (see below) |
+| `groupedRows` | `GridGroupedExportRow[]` | — | From `apiRef.current.getGroupedExportRows()`: group headers, subtotals and a grand-total footer |
 | `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` or `#rgb`). Invalid values fall back to the default |
+| `headerTextColor` | `string` | `'#ffffff'` | Column header cell text color (`#rrggbb` or `#rgb`). Invalid values fall back to the default |
 | `fontSize` | `number` | `9` | Body cell font size in points |
+| `font` | `{ name: string; data: string; boldData?: string }` | — | A TrueType font (base64 `.ttf`) for text outside Latin-1 (v3.0+). See [Non-Latin text](#non-latin-text-and-unicode-fonts) |
+
+## Totals and filter summary
+
+- The footer shows `TOTAL` in the first column; when the first column has its own aggregate, the value is kept next to it (`TOTAL: 30`). Grouped `Subtotal` and `Grand Total` rows do the same.
+- `count` and `unique` are plain counts, not run through the column's `valueFormatter`. `sum`, `avg`, `min` and `max` use the formatter; if it throws (e.g. it reads a data-row field), the value is formatted like the grid footer instead of aborting the export. See [Aggregate values](export-guide.md#aggregate-values).
+- The filter line under the title lists the applied filter as the grid evaluates it: `A equals "1" OR (B contains "x" AND C isEmpty) • Search: "acme"` — nested groups in parentheses, the model's logic operator, and the quick-search terms. Rules without a value (an unfinished row in the filter panel) are left out. Long titles and filter lines wrap within the page margins.
+
+## Non-latin text and Unicode fonts
+
+jsPDF's built-in Helvetica font only covers Latin-1 and the WinAnsi punctuation (`é`, `ü`, `€`, `“ ”`, `•`). A string with any other character used to come out entirely garbled; since v3.0 only the undrawable characters are replaced with `?` (special spaces and the minus sign become their ASCII forms, so `fr-FR` totals such as `1 234 567` print correctly) and a console warning is logged.
+
+To print `₹`, Greek, Cyrillic, CJK or Devanagari text, pass a Unicode TrueType font such as [Noto Sans](https://fonts.google.com/noto) as base64:
+
+```tsx
+const toBase64 = async (url: string) => {
+    const bytes = new Uint8Array(await (await fetch(url)).arrayBuffer());
+    let binary = '';
+    bytes.forEach(b => { binary += String.fromCharCode(b); });
+    return btoa(binary);
+};
+
+await exportToPdf(rows, columns, {
+    title: 'बिक्री रिपोर्ट',
+    font: {
+        name: 'NotoSans',
+        data: await toBase64('/fonts/NotoSans-Regular.ttf'),
+        boldData: await toBase64('/fonts/NotoSans-Bold.ttf'), // optional; the regular face is used for bold otherwise
+    },
+});
+```
+
+jsPDF does not shape complex scripts, so Devanagari or Arabic conjuncts may not join.
 
 ## Column Exclusion
 
@@ -93,10 +138,18 @@ Columns with `exportable: false` are excluded automatically:
 { field: 'internalNotes', headerName: 'Notes', exportable: false }
 ```
 
-System columns (`__check__`, `__actions__`) are also always excluded.
+System columns (`__check__`, `__actions__`) and spacer columns (`isSpacer: true`) are also always excluded.
 
 ## Troubleshooting
 
+**`₹` or other characters print as `?`**
+
+Pass the `font` option with a Unicode TrueType font. See [Non-Latin text](#non-latin-text-and-unicode-fonts).
+
+**Export is slow or the file is huge**
+
+PDF is not suited to tens of thousands of rows (see Installation above). Use CSV or `.xlsx` for large exports.
+
 **Error: "exportToPdf requires 'jspdf' and 'jspdf-autotable'"**
 
 Run: `npm install jspdf jspdf-autotable`
@@ -107,4 +160,4 @@ Ensure `logoUrl` is a data URI (base64-encoded) or an absolute URL that is CORS-
 
 ## Exporting unfiltered data
 
-`getVisibleRows()` returns only rows that pass the current filter. Use `getAllRows()` if you want to export all data regardless of active filters.
+`getVisibleRows()` returns the rows on screen: those that pass the current filter, only the current page when pagination is on, plus pinned rows. `getAllFilteredRows()` returns every filtered row regardless of pagination (and, under grouping or tree data, of expansion), in the grid's sort order with top- and bottom-pinned rows first and last; it is the right source for a full export. Use `getAllRows()` if you want to export all data regardless of active filters. `getVisibleColumns()` returns the columns on screen (hidden columns omitted), in display order. `getFilterModel()` returns the live filter model, including filters applied from the toolbar or filter panel.

package/docs/features/pinning.md

@@ -18,12 +18,21 @@ Columns can be pinned to the left or right edges of the grid. Pinned columns rem
 />
 ```
 
+### Order and widths
+- Pinned columns render in the order of `pinnedColumns.left` / `pinnedColumns.right`, not in column order. Pinning from the column menu appends the column to the end of its side, so it lands next to the scrolling columns.
+- When the columns are narrower than the grid, right-pinned columns sit at the grid's right edge, and the free space is between the scrolling columns and them (v3.0.1+).
+- A pinned column is sized exactly as it would be unpinned: numbers, percentages, `flex` and `'auto'` all apply, clamped to `minWidth` / `maxWidth`. The sticky offsets use those widths, so pinned columns never overlap.
+
 ### Column Configuration
-Individual columns can be marked as non-pinnable:
+Individual columns can be marked as non-pinnable. Their column menu has no pin actions:
 ```typescript
 { field: 'id', pinnable: false }
 ```
 
+`pinnable: false` only affects the UI; a column listed in `pinnedColumns` is still pinned. It does not block drag-reordering (v3.0+).
+
+Pinned column headers are not draggable and are not drop targets for header drag-reorder: to move a pinned column, change the order in `pinnedColumns`.
+
 ---
 
 ## ⬆️ Row Pinning
@@ -40,8 +49,13 @@ Rows can be pinned to the top or bottom of the grid. Pinned rows remain visible
 />
 ```
 
+### Behaviour
+- Pinned rows are split out after filtering: a pinned row that does not match the active filter or quick filter is hidden. They are never sorted; they keep the order of `pinnedRows.top` / `.bottom`.
+- `pinnedRows` is **ignored while `treeData` or `rowGroupingModel` is active**: the rows stay in their place in the hierarchy, and a development warning is logged.
+- Top-pinned rows stick directly below the whole header, including column group header rows. Bottom-pinned rows stick directly above the aggregation footer; both stay visible.
+
 ### Use Cases
-- **Header Summary**: Keep a "Totals" or "Averages" row at the top.
+- **Header Summary**: Keep a summary row at the top (for grid-wide totals that follow the filter, prefer `aggregationModel`, whose footer never scrolls away).
 - **Comparison**: Pin a specific row to compare it against other data.
 - **Actions footer**: Pin a specialized row for bulk actions at the bottom.
 
@@ -59,8 +73,13 @@ Rows can be pinned to the top or bottom of the grid. Pinned rows remain visible
 ---
 
 ## 🎨 Styling Pinning
-Pinned elements have specific CSS shadow classes applied to indicate depth:
-- `.ogx-column--pinned-left--last`
-- `.ogx-column--pinned-right--first`
+The last left-pinned cell and the first right-pinned cell of each row carry section-edge classes (the body cells draw an edge shadow):
+- body cells: `.ogx__cell--pinned-left-last`, `.ogx__cell--pinned-right-first`
+- header cells: `.ogx__header-cell--pinned-left-last`, `.ogx__header-cell--pinned-right-first`
+- aggregation footer: `.ogx__aggregation-cell--pinned-left-last`, `.ogx__aggregation-cell--pinned-right-first`
+
+The edge is the last / first pinned column that is actually shown, so hiding a pinned column moves it. All pinned cells also carry `.ogx__cell--pinned-left` / `--pinned-right` (`.ogx__header-cell--pinned-left` / `--pinned-right`).
+
+Sticky row areas are wrapped (v3.0+): the header and the top-pinned rows sit in `div.ogx__sticky-top`, and the bottom-pinned rows and the aggregation footer sit in `div.ogx__sticky-bottom`. The `.ogx__pinned-rows--top` / `.ogx__pinned-rows--bottom` containers inside them are no longer sticky themselves, so custom sticky CSS belongs on the wrappers.
 
 These can be customized via your theme or global CSS.

package/docs/features/selection.md

@@ -19,6 +19,8 @@ OpenGridX provides various ways for users to select one or multiple rows.
 ### Enable Checkbox Selection
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   checkboxSelection
   pinCheckboxColumn // Optional: keeps checkbox on the left during horizontal scroll
 />
@@ -31,6 +33,8 @@ Use the `rowSelectionModel` to control the selection state from your parent comp
 const [selection, setSelection] = useState<GridRowId[]>([]);
 
 <DataGrid
+  rows={rows}
+  columns={columns}
   rowSelectionModel={selection}
   onRowSelectionModelChange={(newSelection) => setSelection(newSelection)}
 />
@@ -42,6 +46,8 @@ Use `disableRowSelectionOnClick` to prevent clicking a row from changing the sel
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   checkboxSelection
   disableRowSelectionOnClick
 />
@@ -49,15 +55,41 @@ Use `disableRowSelectionOnClick` to prevent clicking a row from changing the sel
 
 ### Single-Row Selection Only
 
-Use `disableMultipleRowSelection` to cap selection to one row at a time. Clicking a second row deselects the first; clicking an already-selected row deselects it.
+Use `disableMultipleRowSelection` to cap selection to one row at a time. Clicking a second row deselects the first; clicking an already-selected row deselects it. The cap applies to row clicks, row checkboxes, the Space key and `apiRef.selectRow` / `selectRows` alike, and the header select-all checkbox is not shown.
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   disableMultipleRowSelection
   onRowSelectionModelChange={(model) => console.log('selected:', model)}
 />
 ```
 
+### Select All
+
+With `checkboxSelection`, the header checkbox selects the rows that pass the current filter (including pinned rows) and adds them to the selection; unchecking it removes those rows again. Rows hidden by the filter keep their selection state, and under row grouping group rows are not part of select-all. Synthetic rows (row-grouping group and subtotal rows, auto-created tree-data parents, the pivot Grand Total) have no checkbox and are never selected, by click, checkbox, Space key or `apiRef.selectRow` / `selectRows` (v3.0+ for the Grand Total and `apiRef`); tree-data parents that are your own rows are selectable like any row. A click on the Grand Total still fires `onRowClick`. `apiRef.selectRow` on a row that is already selected reports nothing, as a click on the checkbox would not. The header shows checked when every such row is selected and indeterminate when only some are, so ids of rows that are no longer in `rows` do not affect it.
+
+### Removed Rows
+
+When rows leave `rows`, their ids leave the selection (v3.0+): `apiRef.current.getSelectedRows()`, the header checkbox and the next model a click produces no longer contain them, and the pruned model is reported once through `onRowSelectionModelChange`. An uncontrolled selection forgets the ids, so a row that comes back is not selected again; a controlled model should adopt the reported value. This applies when the grid holds every row: without a `dataSource`, with client pagination and filtering, and outside pivot mode. With `paginationMode="server"`, `filterMode="server"` or a `dataSource`, ids of rows that are not loaded are kept, so a selection survives paging.
+
+In pivot mode the pivot rows have their own ids (`'__pivot_row__:["North"]'`, derived from the row-field values), so a selection made on the source rows never marks a pivot row, and leaving pivot mode gives the source selection back.
+
+### Keyboard Selection
+
+With focus in the grid (see [Keyboard & Accessibility](keyboard-navigation.md)):
+
+| Key | Action |
+| :--- | :--- |
+| **Shift+Space** | Select or deselect the focused row. Available when rows can be selected at all (`checkboxSelection`, or click selection not disabled with `disableRowSelectionOnClick`). |
+| **Space** / **Enter** on a row checkbox | Toggle that row. |
+| **Space** / **Enter** on the select-all header | Select or clear all rows, like clicking it. |
+| **Enter** on a non-editable cell | Same as clicking the row: `onRowClick`, then click-to-select unless `disableRowSelectionOnClick`. |
+| **Ctrl+A** / **Cmd+A** | Select every row, unless `disableMultipleRowSelection` (or selection is not possible). |
+
+Synthetic rows (row-grouping groups and subtotals, auto-created tree parents, the pivot Grand Total) are never selected from the keyboard. The grid sets `aria-multiselectable="true"` when several rows can be selected.
+
 ---
 
 ## ⚙️ API Reference
@@ -77,17 +109,25 @@ Use `disableMultipleRowSelection` to cap selection to one row at a time. Clickin
 ## 🖱️ Interaction Callbacks
 
 ### `onRowClick`
-Fired when a row is clicked (even if selection is disabled on click).
-```typescript
-onRowClick: (params: GridRowParams) => {
-  console.log('Row clicked:', params.id, params.row);
-}
+Fired when a row is clicked, or Enter is pressed on one of its non-editable cells, even if selection is disabled on click. It is not fired for synthetic row-grouping group rows (a click toggles them instead).
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  onRowClick={(params: GridRowParams) => {
+    console.log('Row clicked:', params.id, params.row);
+  }}
+/>
 ```
 
 ### `onCellClick`
 Fired when a specific cell is clicked.
-```typescript
-onCellClick: (params: GridCellParams) => {
-  console.log('Cell clicked:', params.field, params.value);
-}
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  onCellClick={(params: GridCellParams) => {
+    console.log('Cell clicked:', params.field, params.value);
+  }}
+/>
 ```

package/docs/features/sorting-pagination.md

@@ -1,6 +1,6 @@
 # 🔢 Sorting & Pagination
 
-Efficiently naviagte and organize through large datasets using OpenGridX's sorting and pagination engines.
+Efficiently navigate and organize through large datasets using OpenGridX's sorting and pagination engines.
 
 ---
 
@@ -34,18 +34,32 @@ OpenGridX supports two modes of multi-column sorting:
 
 Each active sort column shows a numbered priority badge (`1`, `2`, `3`…) next to its arrow.
 
-- Clicking (or shift-clicking) an already-sorted column cycles its direction: `asc → desc → removed`.
+- Clicking (or shift-clicking) an already-sorted column cycles its direction: `asc → desc → removed`. The column keeps its priority while its direction changes; it is not moved to the end of the sort model.
 - A plain click *without* `multiSort` and without Shift always resets to a single-key sort on that column.
+- The column menu acts on that column only: **Unsort** removes just that key, and **Sort Ascending / Descending** on a column that is already sorted changes its direction in place. On a column that is not sorted yet it appends with `multiSort` and replaces the model without it, like a plain click.
 - Set `sortable: false` on a column to exclude it entirely.
 
+### How values are compared (client-side)
+
+- Cells are read through the column's `valueGetter`, so computed columns sort by the value they display.
+- `type: 'number'` columns compare numerically even when the data holds numeric strings (`'9'` sorts before `'10'`). `type: 'date'` columns parse date strings (`'YYYY-MM-DD'` is read as a local date) and compare chronologically.
+- Strings use language-aware ordering (`Intl.Collator`): case is ignored, accented letters sort next to their base letter (`'Émile'` between `'Adam'` and `'Zoe'`), and digit runs compare by value (`'item9'` before `'item10'`).
+- `null`, `undefined`, `NaN`, an Invalid Date and, in number / date columns, values that cannot be parsed are "empty": they sort last in ascending order and first in descending order.
+- A column that mixes kinds of value (numbers and strings, say) is ordered by kind first — numbers, dates, booleans, strings — so the order does not depend on the input order.
+- Ties keep the rows' original order.
+
 ```tsx
 // Controlled multi-sort — set programmatically or drive from UI with multiSort:
+const [sortModel, setSortModel] = useState<GridSortItem[]>([
+  { field: 'department', sort: 'asc' },
+  { field: 'salary', sort: 'desc' },
+]);
+
 <DataGrid
+  rows={rows}
+  columns={columns}
   multiSort
-  sortModel={[
-    { field: 'department', sort: 'asc' },
-    { field: 'salary', sort: 'desc' },
-  ]}
+  sortModel={sortModel}
   onSortModelChange={setSortModel}
 />
 ```
@@ -66,25 +80,60 @@ OpenGridX supports standard page-based pagination and infinite scrolling.
 
 ### Usage
 ```tsx
+// Uncontrolled: the grid keeps the page; initialState sets where it starts
 <DataGrid
+  rows={rows}
+  columns={columns}
   pagination
-  paginationModel={{ page: 0, pageSize: 10 }}
   pageSizeOptions={[5, 10, 20, 50]}
+  initialState={{ pagination: { paginationModel: { page: 0, pageSize: 10 } } }}
+/>
+
+// Controlled: pass onPaginationModelChange too, or the pager cannot change page
+const [paginationModel, setPaginationModel] = useState({ page: 0, pageSize: 10 });
+<DataGrid
+  rows={rows}
+  columns={columns}
+  pagination
+  paginationModel={paginationModel}
+  onPaginationModelChange={setPaginationModel}
 />
 ```
 
+The pager counts the rows being paged: the rows that pass the filter, excluding pinned rows (pinned rows show on every page).
+
+Without `paginationModel` or `initialState.pagination`, the page size is 100 when `pageSizeOptions` offers it and otherwise the first option, so the rows-per-page select always matches the rows shown.
+
+### When the rows shrink
+If the current page ends up past the last page (new `rows`, a filter, collapsed tree nodes), the grid shows the last page and reports the corrected model through `onPaginationModelChange`, so Previous and Next continue from the page on screen. The correction waits until rows are present and nothing is loading, so a restored page (for example from `initialState.pagination`) survives an initially empty `rows` array. Under server pagination the server's `rowCount` decides; the grid does not clamp.
+
+### Page sizes outside `pageSizeOptions`
+When the page size in use is not one of `pageSizeOptions` (for example a controlled `paginationModel={{ page: 0, pageSize: 20 }}` with `pageSizeOptions={[10, 25, 50]}`), the rows-per-page select adds it as an extra option, so it shows the size actually used. A page size below 1 is treated as 1.
+
 ### Server-Side Pagination
-When using `paginationMode="server"`, you must provide the `rowCount` and handle page changes in your `dataSource`.
+With `paginationMode="server"` the grid does not slice rows: `rows` is the current page. There are two ways to supply it.
+
+**Fetch the page yourself** — control `paginationModel`, pass the page's rows and the server total as `rowCount`. `rowCount` is read on every render, so update it when the total changes.
 
 ```tsx
+const [paginationModel, setPaginationModel] = useState({ page: 0, pageSize: 10 });
+const { rows, total } = usePageQuery(paginationModel); // your data fetching
+
 <DataGrid
+  rows={rows}               // only the current page
+  columns={columns}
   pagination
   paginationMode="server"
-  rowCount={1000} // Total rows on server
-  onPaginationModelChange={(model) => fetchNextPage(model)}
+  rowCount={total}          // total rows on the server
+  paginationModel={paginationModel}
+  onPaginationModelChange={setPaginationModel}
 />
 ```
 
+**Or use a `dataSource`** — the grid calls `getRows` with `startRow` / `endRow` and uses the response's `rowCount` as the total (the `rowCount` prop is only a fallback until the first response). See [Server-Side Data](./data-source.md).
+
+`sortingMode="server"` and `filterMode="server"` work the same way: the grid fires `onSortModelChange` / `onFilterModelChange` and shows `rows` as given, without re-sorting or re-filtering them, with or without a `dataSource`.
+
 ### Props
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
@@ -92,14 +141,15 @@ When using `paginationMode="server"`, you must provide the `rowCount` and handle
 | `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | Location of the pagination logic. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the rows-per-page selector. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the rows-per-page selector. The uncontrolled default page size is 100 when offered, else the first option. |
+| `rowCount` | `number` | — | Server total for `paginationMode="server"` without a `dataSource` (with one, the response's `rowCount` is used). |
 
 ---
 
 ## ⚡ Infinite Scrolling
 For a more modern experience, use infinite scroll combined with virtualization.
 
-1. Set `paginationMode="infinite"`.
-2. Implement `onRowsScrollEnd` or use the `dataSource.getRows` method to fetch data as the user scrolls.
+1. Set `paginationMode="infinite"` and pass a `dataSource`.
+2. Advance `paginationModel.page` from `onRowsScrollEnd`; the grid requests the next rows from `dataSource.getRows` and appends them. The pager is not shown and rows are not sliced.
 
-📖 **[Full Infinite Scroll Guide](docs/features/infinite-scroll.md)**
+📖 **[Full Infinite Scroll Guide](./infinite-scroll.md)**

package/docs/features/state-persistence.md

@@ -6,18 +6,29 @@ Save and restore the grid's configuration (sorting, filtering, column order, etc
 
 ## 🏗️ The `initialState` Prop
 
-You can pre-configure the grid status on mount using the `initialState` prop.
+You can pre-configure the grid status on mount using the `initialState` prop. Every part is optional, including each field of `columns`.
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   initialState={{
     sorting: {
       sortModel: [{ field: 'name', sort: 'asc' }]
-    }
+    },
+    filter: {
+      filterModel: { items: [{ field: 'age', operator: '>', value: 30 }] }
+    },
+    columns: {
+      columnVisibilityModel: { age: false }
+    },
+    density: { density: 'compact' }
   }}
 />
 ```
 
+`initialState` is read once, when the grid mounts. It seeds the grid's own (uncontrolled) state, so it has no effect on a model you also pass as a prop (`sortModel`, `filterModel`, `paginationModel`, …), and the `density` prop wins over `initialState.density`.
+
 ---
 
 ## ⚓ The `useGridStateStorage` Hook
@@ -28,26 +39,81 @@ OpenGridX provides a built-in hook to simplify `localStorage` persistence.
 import { DataGrid, useGridStateStorage } from '@opencorestack/opengridx';
 
 export default function MyGrid() {
-  const { initialState, onStateChange } = useGridStateStorage('my-app-storage-key');
+  const { initialState, onStateChange, clearState } = useGridStateStorage('my-app-storage-key');
 
   return (
-    <DataGrid
-      initialState={initialState}
-      onStateChange={onStateChange}
-      // ...
-    />
+    <>
+      <button type="button" onClick={clearState}>Forget saved layout</button>
+      <DataGrid
+        rows={rows}
+        columns={columns}
+        initialState={initialState}
+        onStateChange={onStateChange}
+      />
+    </>
   );
 }
 ```
 
+Writes are debounced (`debounceMs`, default 300 ms), and a pending write is flushed when the component unmounts. When the browser blocks storage (cookie blocking, sandboxed iframes), the hook falls back to no persistence instead of throwing.
+
+Options (pass an object instead of the key string):
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `key` | `string` | — | Storage key. |
+| `debounceMs` | `number` | `300` | Delay before a state change is written. |
+| `include` | `(keyof GridState)[]` | all | Only persist these parts, e.g. `['sorting', 'columns']`. |
+| `storage` | `{ getItem, setItem, removeItem }` | `window.localStorage` | Any Storage-like object (e.g. `sessionStorage`). |
+
+`clearState()` removes the saved state and cancels any pending write, so the old state is not written back afterwards. It does not reset the mounted grid, and the grid's next state change is saved again; remount the grid (for example with a new `key`) to start from defaults.
+
+### Server-side rendering (Next.js, Remix)
+
+`useGridStateStorage` is client-only. It reads storage in its initial render, so on the server `initialState` is empty while the browser's first render already has the saved state: when saved state exists, React reports a hydration mismatch (the sort arrows, column order or page differ). Render the persisted grid only after mount, for example:
+
+```tsx
+function PersistedGrid() {
+  const { initialState, onStateChange } = useGridStateStorage('my-app-storage-key');
+  return <DataGrid rows={rows} columns={columns} initialState={initialState} onStateChange={onStateChange} />;
+}
+
+export default function Page() {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  return mounted ? <PersistedGrid /> : <GridPlaceholder />;
+}
+```
+
+In Next.js, `dynamic(() => import('./PersistedGrid'), { ssr: false })` does the same.
+
+### Changing the key
+
+The grid reads `initialState` only when it mounts. If the key can change while the grid stays on screen (a per-user or per-view key), remount the grid with the key so it starts from the new key's saved state:
+
+```tsx
+const storageKey = `grid-${userId}`;
+const { initialState, onStateChange } = useGridStateStorage(storageKey);
+
+<DataGrid key={storageKey} rows={rows} columns={columns} initialState={initialState} onStateChange={onStateChange} />
+```
+
+Without the remount the grid keeps its current state, and its next change is saved under the new key.
+
+### Server-side rendering
+
+The hook reads storage during the first render. On the server there is no storage, so the server HTML uses the default state while the client's first render uses the saved one, and React reports a hydration mismatch. If users can have saved state, render the persisted grid on the client only (for example after mount, or with Next.js `dynamic(..., { ssr: false })`). The [migration guide, §26](../migration/v2-to-v3.md#26-state-persistence) has a complete example.
+
 ---
 
 ## 📡 Tracking Changes
 
-Use the `onStateChange` callback to listen for any modifications to the grid state and save them to `localStorage` or a database.
+Use the `onStateChange` callback to listen for modifications to the grid state and save them to `localStorage` or a database. It fires once on mount and then whenever the state's *value* changes — re-rendering the grid with equal (even inline) props does not fire it, so storing the state in parent React state is safe.
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   onStateChange={(state) => {
     localStorage.setItem('grid-state', JSON.stringify(state));
   }}
@@ -58,9 +124,11 @@ Use the `onStateChange` callback to listen for any modifications to the grid sta
 
 ## 🧩 Supported State Objects
 
-The following features support state persistence:
+The following features support state persistence (they appear in the `onStateChange` payload and are restored from `initialState`):
 - **Sorting**: `sortModel`
 - **Filtering**: `filterModel`
 - **Pagination**: `paginationModel`
 - **Columns**: `columnVisibilityModel`, `columnOrder`, `pinnedColumns`, `columnWidths`
 - **Density**: `density`
+
+Only your own columns appear in the column state: the grid's synthetic grouping column (added by `groupingColDef`) is never included.