@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/features/keyboard-navigation.md

@@ -0,0 +1,83 @@
+# Keyboard Navigation & Accessibility
+
+The grid follows the [WAI-ARIA data grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/): it is a single Tab stop, and the arrow keys move a focused cell inside it. This page lists the keys, explains how focus behaves, and documents the ARIA structure the grid exposes (v3.0).
+
+## Focus model
+
+- **One Tab stop.** The grid viewport (`role="grid"`) is in the page Tab order. Tabbing in puts focus on the last focused cell, or on the first cell (the select-all header checkbox with `checkboxSelection`, the first column header when there are no rows). While focus is inside the grid the viewport leaves the Tab order, so **Tab** and **Shift+Tab** leave the grid in one press.
+- **Tab is not captured** outside edit mode. It moves to the next focusable element in the page, which may be a control you render in a cell (`renderCell`) or inside an expanded detail panel.
+- **Focus is remembered.** Leaving the grid (Tab, clicking elsewhere, switching window) keeps the focused cell; coming back restores it. The focus ring is only drawn while the grid has focus and the keyboard is in use.
+- **Focus survives virtualization.** When the focused row scrolls out of the render window, focus stays on the grid so keys keep working; the cell gets DOM focus back when it is rendered again. The grid never takes focus back from an element outside it.
+- **Rows and columns that disappear.** If the focused row is removed or filtered out, focus moves to the row now at the same position; if the focused column is hidden, to the first visible data column; with no rows left, to the header.
+- **Your own controls keep their keys.** Keys pressed in text inputs, textareas, selects and editable content rendered in cells, and anything inside a detail panel, are left to that element. On a button, link or checkbox rendered in a cell, **Enter** and **Space** activate it and the arrow keys still move grid focus.
+
+## Keys
+
+### Cells
+
+| Key | Action |
+| :--- | :--- |
+| **Arrow keys** | Move one cell. Left/Right wrap to the previous/next row. Up from the first row moves to the header. Merged (spanned) cells count as one cell. |
+| **Home** / **End** | First / last column of the row. |
+| **Ctrl+Home** / **Ctrl+End** (Cmd on macOS) | First column of the header row / last column of the last row. |
+| **PageUp** / **PageDown** | Up / down one page (`pageSize` with pagination, otherwise 10 rows). |
+| **Enter** | Editable cell: open the editor. Other cells of a row with children (group row or tree-data parent): expand or collapse it. Other cells: same as clicking the row — fires `onRowClick` and toggles selection unless `disableRowSelectionOnClick`. |
+| **Alt+ArrowRight** / **Alt+ArrowLeft** | Tree data / row grouping: expand / collapse the focused row. |
+| **Shift+Space** | Select or deselect the focused row (when rows can be selected: `checkboxSelection`, or click selection not disabled). Synthetic group rows are not selectable. |
+| **Space** | On the row checkbox: toggle the row. On the detail-panel toggle: expand or collapse the panel. Elsewhere it does nothing (it never scrolls the grid). |
+| **Ctrl+A** (Cmd+A) | Select every row, when several rows can be selected. |
+| **Ctrl+C** (Cmd+C) | Copy the selected rows (see [Clipboard](clipboard.md)). |
+
+Arrow, Home/End, PageUp/PageDown and Space are always consumed, so the viewport does not scroll natively when focus cannot move further.
+
+### While editing
+
+| Key | Action |
+| :--- | :--- |
+| **Enter** | Commit. |
+| **Escape** | Cancel. |
+| **Tab** / **Shift+Tab** | Commit and open the next / previous editable cell (checkbox, expand and reorder columns are skipped). With no editable cell left, focus leaves the grid and the edit commits. |
+
+When an edit ends, focus returns to the edited cell unless you moved it elsewhere.
+
+### Column headers
+
+| Key | Action |
+| :--- | :--- |
+| **Enter** / **Space** | Sort the column (asc → desc → none), replacing the sort model; with `multiSort`, or with **Shift** held, the column is added to (or updated or removed from) the sort model instead, as a header click or shift-click does. On the select-all header: select or clear all rows. |
+| **Alt+ArrowDown** or **Ctrl+Enter** (Cmd+Enter) | Open the column menu. |
+| **Alt+ArrowRight** / **Alt+ArrowLeft** | Widen / narrow the column by 10px (with **Shift**: 50px). Not for `resizable: false` columns. |
+| **ArrowDown** | Move to the first row. |
+
+In the column menu, **ArrowUp** / **ArrowDown** / **Home** / **End** move between items, **Enter** / **Space** choose one, and **Escape** or **Tab** closes the menu. Focus returns to the column header.
+
+### List view
+
+In `listView`, focus moves between whole rows instead of cells:
+
+| Key | Action |
+| :--- | :--- |
+| **Tab** | The list is one Tab stop: it lands on the last focused row (the first row at first). Row checkboxes are not separate Tab stops. |
+| **ArrowDown** / **ArrowUp** | Next / previous row. |
+| **Home** / **End** | First / last row. |
+| **PageDown** / **PageUp** | Ten rows down / up. |
+| **Enter** / **Space** | A row with children (tree-data parent, group row): expand or collapse it. Any other row: same as clicking it (`onRowClick`, and click selection unless `disableRowSelectionOnClick`). |
+| **Alt+ArrowRight** / **Alt+ArrowLeft** | Expand / collapse the focused parent row. |
+| **Shift+Space** | Select or deselect the focused row, when rows can be selected. |
+
+Keys pressed in content your `renderCell` puts in a row (inputs, buttons) are left to that content.
+
+## ARIA structure
+
+| Element | Attributes |
+| :--- | :--- |
+| Viewport | `role="grid"`, `aria-rowcount`, `aria-colcount`, `aria-multiselectable` (true when several rows can be selected), `aria-busy`. |
+| Header rows | `role="row"` with `aria-rowindex`: column-group rows first, then the column header row. |
+| Data rows | `role="row"`, `aria-rowindex` counted across the whole dataset (page 2 continues after page 1; bottom-pinned rows come after every page), `aria-selected`. Tree-data and row-grouping rows add `aria-level`; rows with children add `aria-expanded`. |
+| Cells and headers | `aria-colindex`, identical for a header and the body cells below it. The system columns (reorder handle, detail-panel toggle, checkbox) come first. |
+| Sorted headers | Only the primary sort column has `aria-sort="ascending"` / `"descending"`; with several sort keys every sorted header also gets an `aria-description` such as "Sorted descending, sort priority 2 of 2". |
+| Detail panel | A `role="row"` with one `role="gridcell"` spanning every column (`aria-colspan`). The expand cell has `aria-expanded` and, while open, `aria-controls` pointing at the panel. |
+
+`aria-rowcount` counts the header rows plus top-pinned, centre and bottom-pinned rows; under server-side pagination it uses `rowCount`. `aria-colcount` counts the rendered columns: visible data columns (including the `groupingColDef` column and generated pivot columns) plus the system columns.
+
+`GridCellParams.colIndex` / `GridRenderCellParams.colIndex` (and `renderHeader`'s `colIndex`) are the zero-based position of the column among the **visible data columns in render order** (left-pinned, unpinned, right-pinned). They do not change with horizontal scrolling. `aria-colindex` is `colIndex + 1 +` the number of system columns.

package/docs/features/list-view.md

@@ -6,9 +6,16 @@ Switch from a multi-column grid to a single-column detailed list. Perfect for mo
 
 ## 🏗️ Usage
 
-Enable List View by passing the `listView` prop. You must also provide a `listViewColumn` object which defines how each "Card" should be rendered.
+Enable List View by passing the `listView` prop. You must also provide a `listViewColumn` object which defines how each "Card" should be rendered. Without `listViewColumn` the grid view is shown instead and a dev warning is logged.
+
+List view honours `loading`, `slots.loadingOverlay`, `slots.noRowsOverlay` and `slots.footer` like the grid view: while loading it shows a progress bar (or your loading overlay) rather than the empty state, and `slots.footer` replaces its pagination controls.
 
 ```tsx
+import { DataGrid, type GridListViewColDef } from '@opencorestack/opengridx';
+
+// Your own row type: an interface or a type alias both work (v3+).
+interface Employee { id: number; name: string; role: string; status: string; avatar: string }
+
 const listColDef: GridListViewColDef<Employee> = {
   field: 'card',
   renderCell: (params) => <MyEmployeeCard row={params.row} />
@@ -32,10 +39,24 @@ When `listView` is active:
 - **Card Containers**: Each row maintains its standard selection and hover behaviors, but visually acts as a card.
 
 ### Custom Card Rendering
-The `renderCell` function in `listViewColumn` receives all standard `GridRenderCellParams`, allowing you to build rich, complex UIs for each item.
+The `renderCell` function in `listViewColumn` receives all standard `GridRenderCellParams`, allowing you to build rich, complex UIs for each item:
+
+| Param | Value |
+| :--- | :--- |
+| `row` | The consumer's row object. |
+| `field` | `listViewColumn.field`. |
+| `value` | The cell value for that field: the grid column with the same `field` reads it through its `valueGetter`; otherwise `row[field]` (so a synthetic field such as `'card'` gives `undefined`). |
+| `formattedValue` | That column's `valueFormatter` result, or `String(value)` (`''` for null/undefined). |
+| `colDef` | The grid column with the same `field`, or `listViewColumn` itself. |
+| `rowMeta` | Tree-data / row-grouping metadata (`treeDepth`, `hasChildren`, …), `undefined` for flat rows. |
+| `rowIndex` | Index of the row among the rendered rows (pinned rows first). |
+
+`renderCell` only ever receives real rows: while an infinite-scroll page loads, no placeholder rows are passed to it.
+
+Under row grouping (and for auto-created tree parents) `renderCell` is also called for group rows (`rowMeta.isGroupRow`). Returning `undefined` for one shows its `rowMeta.groupLabel`. Group rows have no selection checkbox, and the `N items` summary counts data rows only, as in the grid view (v3.0+). A `renderCell` that throws shows an error in that row only, and a throwing `valueGetter` / `valueFormatter` of the grid column reads as `undefined` / the unformatted value (v3.0+).
 
 ```tsx
-function MyEmployeeCard({ row }) {
+function MyEmployeeCard({ row }: { row: Employee }) {
   return (
     <div className="employee-card">
        <Avatar src={row.avatar} />
@@ -51,15 +72,47 @@ function MyEmployeeCard({ row }) {
 
 ---
 
+## 📄 Pagination and infinite scroll
+
+List view pages exactly like the grid view: with `pagination`, one page of the (unpinned) rows is shown between any pinned rows, also under tree data. The summary line above the list reads `N items · page X of Y`, where under server pagination (`paginationMode="server"` with a `dataSource`) `N` and the page count come from the server's `rowCount`.
+
+`onRowsScrollEnd` fires when the list is scrolled to within 100px of its bottom, so the [infinite scroll](./infinite-scroll.md) pattern works in list view too. As in the grid view, it fires once per arrival: it fires again only after the list leaves that zone or the row count changes (for example, when the next page has loaded).
+
+The list view is **not virtualized**: it renders every row it shows (one page with `pagination`, otherwise all rows). Use pagination for large datasets. `slots.footer` is rendered below the list (in place of its pagination controls); the aggregation footer row is not shown in list view.
+
+## ♿ Accessibility
+
+The list is a `role="grid"` whose rows carry an `aria-rowindex` over the whole data set (row 11 on the second page of 10) and whose `aria-rowcount` is the total number of rows. There is no header row in list view. Tree-data and grouped rows also carry `aria-level` and, for parents, `aria-expanded`; they are indented by depth, and parents show a chevron that expands or collapses them on click (the chevron is not a Tab stop).
+
+### Keyboard (v3.0)
+
+Rows are focusable with a roving tab stop:
+
+| Key | Action |
+| :--- | :--- |
+| **Tab** | The list is one Tab stop: it lands on the last focused row (the first row at first). Row checkboxes are not separate Tab stops. |
+| **ArrowDown** / **ArrowUp** | Next / previous row. |
+| **Home** / **End** | First / last row. |
+| **PageDown** / **PageUp** | Ten rows down / up. |
+| **Enter** / **Space** | A row with children (tree-data parent, group row): expand or collapse it. Any other row: same as clicking it (`onRowClick`, and click selection unless `disableRowSelectionOnClick`). |
+| **Alt+ArrowRight** / **Alt+ArrowLeft** | Expand / collapse the focused parent row. |
+| **Shift+Space** | Select or deselect the focused row, when rows can be selected. |
+
+Keys pressed in content your `renderCell` puts in a row (inputs, buttons) are left to that content.
+
+---
+
 ## 📱 Responsive Toggle
 
 A common pattern is to toggle List View based on screen width:
 
 ```tsx
-const isMobile = window.innerWidth < 768;
+const isMobile = window.innerWidth < 768; // read once; use a resize listener or matchMedia to follow changes
 
 <DataGrid
+  rows={rows}
+  columns={columns}
   listView={isMobile}
-  // ...
+  listViewColumn={listColDef}
 />
 ```

package/docs/features/loading-states.md

@@ -6,17 +6,22 @@ OpenGridX provides multiple ways to handle data loading, from initial shimmers t
 
 ## 🦴 Skeleton Loading
 
-The grid features a smart skeleton loader that automatically calculates the number of columns and rows needed to fill the viewport.
+While `loading` is true and there are no rows to show, the grid body shows ten animated skeleton rows laid out with the current columns.
 
 ### Usage
 ```tsx
-<DataGrid loading={true} />
+<DataGrid rows={[]} columns={columns} loading />
 ```
 
 ### Features
-- **Dynamic Calculation**: Skeletons match the current column widths and configuration.
+- **Column-aware**: Skeleton cells use the current column widths, plus the checkbox, detail-panel and drag-handle columns when those are enabled. With no columns yet, placeholder columns fill the width.
 - **Shimmer Animation**: Uses a CSS-optimized animation for a premium feel.
-- **Auto-Fill**: Fills the entire visible height if `rows` are empty.
+- **Custom overlay**: Pass `slots.loadingOverlay` to render your own component instead of the skeleton rows.
+
+### Loading with rows already shown
+When `loading` is true (or a data source request is running) and the grid already has rows, for example during a reload or a server-side sort, the rows stay visible and usable and a thin progress bar (`role="progressbar"`, class `ogx__loading-bar`) runs along the top of the grid. Pass `slots.loadingOverlay` to show your own indicator centred over the rows instead. Infinite scroll keeps its own indicator (skeleton rows at the bottom).
+
+List view follows the same rules: while loading it shows a progress bar or `slots.loadingOverlay`, never the "No rows" state.
 
 ---
 
@@ -24,45 +29,38 @@ The grid features a smart skeleton loader that automatically calculates the numb
 
 For large datasets, use the `paginationMode="infinite"` to load data as the user scrolls.
 
-- **Trigger**: Fired when the user scrolls near the bottom of the grid.
+- **Trigger**: `onRowsScrollEnd` fires when the user scrolls near the bottom; advance `paginationModel.page` there and the `dataSource` loads the next rows.
 - **Feedback**: Displays skeleton rows at the bottom while new data is being fetched.
 - **Guide**: See [Infinite Scroll Guide](./infinite-scroll.md) for full implementation details.
 
 ---
 
-## 💤 Lazy Loading (Viewport)
-
-Unlike infinite scroll which appends data to the end, Lazy Loading fetches specific chunks based on the user's current scroll position (viewport).
-
-- **Benefit**: Best for datasets with millions of records where users might "jump" to the middle of the scrollbar.
-- **Implementation**: Managed via the `GridDataSource` and `rowCount` props.
-
----
-
 ## 🔍 Global Search (Quick Filter)
 
-Quickly filter the entire dataset across all visible columns. This is managed via the `GridToolbar`.
+Quickly filter the rows across all visible, filterable columns. The search box is part of `GridToolbar`.
 
 ### Basic Setup
 
-Add the toolbar and wire a filter model — the toolbar's search bar activates automatically when `onFilterModelChange` is wired:
+Add the toolbar. The search box filters the grid on its own; pass `filterModel` / `onFilterModelChange` only when you want to control or observe the filter:
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   slots={{ toolbar: GridToolbar }}
-  filterModel={filterModel}
-  onFilterModelChange={setFilterModel}
 />
 ```
 
 ### Controlled Search
-You can also control the search value externally via the `filterModel`.
+You can also control the search value externally via the `filterModel`. Each entry is one term, and a row matches when every term is found in some visible column (the toolbar box splits typed text on whitespace the same way).
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   filterModel={{
     items: [],
-    quickFilterValues: ['search term']
+    quickFilterValues: ['john', 'london']
   }}
 />
 ```

package/docs/features/master-detail.md

@@ -6,7 +6,7 @@ Display supplementary information for a row in an expandable panel without leavi
 
 ## 🛠️ Basic Implementation
 
-To enable detail panels, provided two main props: `getDetailPanelContent` and `getDetailPanelHeight`.
+To enable detail panels, provide two main props: `getDetailPanelContent` and `getDetailPanelHeight`.
 
 ```tsx
 <DataGrid
@@ -14,14 +14,16 @@ To enable detail panels, provided two main props: `getDetailPanelContent` and `g
   columns={columns}
   getDetailPanelContent={(params) => (
     <div style={{ padding: '20px' }}>
-      <h3>Details for {params.row.name}</h3>
-      <p>{params.row.description}</p>
+      <h3>Details for {String(params.row.name)}</h3>
+      <p>{String(params.row.description)}</p>
     </div>
   )}
   getDetailPanelHeight={() => 'auto'} // or a fixed number
 />
 ```
 
+`getDetailPanelContent` and `getDetailPanelHeight` are called only for **expanded** rows, while they render (v3.0+). A collapsed row costs nothing, and the callbacks may read fields that only data rows have. Synthetic hierarchy rows (row-grouping group rows and generated tree-data parents) have no detail panel: they keep an empty cell in the expand column, are never passed to the callbacks, and their ids in `detailPanelExpandedRowIds` are ignored. Tree-data parents that are real rows do get a panel. If `getDetailPanelContent` throws, that panel shows an error marker and the rest of the grid keeps working.
+
 ---
 
 ## 🕹️ Controlled Expansion
@@ -29,7 +31,9 @@ To enable detail panels, provided two main props: `getDetailPanelContent` and `g
 You can manage which rows are expanded by using the `detailPanelExpandedRowIds` and `onDetailPanelExpandedRowIdsChange` props.
 
 ```tsx
-const [expandedIds, setExpandedIds] = useState(new Set());
+import type { GridRowId } from '@opencorestack/opengridx';
+
+const [expandedIds, setExpandedIds] = useState<Set<GridRowId>>(new Set());
 
 <DataGrid
   detailPanelExpandedRowIds={expandedIds}
@@ -43,4 +47,13 @@ const [expandedIds, setExpandedIds] = useState(new Set());
 
 - **Expansion Column**: A `+` icon is automatically added to the start of the row.
 - **Pinning**: The expansion column can be pinned using `pinExpandColumn={true}`. This ensures the expansion trigger is always visible even when scrolling horizontally.
-- **Virtualization**: The grid engine correctly accounts for variable row heights when detail panels are open.
+- **Height**: `getDetailPanelHeight` returns a pixel height (a fixed-height scroll box; `0` renders a 0px panel) or `'auto'`. Without the prop every panel is 200px. An `'auto'` panel is measured when it renders and whenever its content resizes, and the rows below are laid out at the measured height. Until a panel has rendered once, 200px is reserved for it.
+- **Virtualization**: The grid engine accounts for variable row heights when detail panels are open, including panels on pinned rows (keyboard navigation and `scrollToIndexes` keep rows clear of an expanded bottom-pinned panel).
+
+## ⌨️ Keyboard & Accessibility
+
+- **Space** or **Enter** on the expand cell toggles the panel (v3.0: Enter too).
+- Keys typed into content you render in the panel (inputs, selects, buttons) are left to that content: the grid does not react to them, so typing a space no longer collapses the panel and arrow keys move the caret.
+- **Tab** is not captured by the grid, so it reaches focusable content inside an open panel.
+- Keyboard scrolling brings the row itself into view, not the row plus its panel, so moving onto a row with a panel taller than the viewport keeps the row visible.
+- The panel is exposed as a `role="row"` containing one `role="gridcell"` that spans every column; the expand cell has `aria-expanded` and, while open, `aria-controls` pointing at the panel. The `+`/`−` button inside the cell is not a separate Tab stop.

package/docs/features/pdf-export.md

@@ -13,15 +13,18 @@ npm install jspdf jspdf-autotable
 ## 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 +34,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 +51,7 @@ function MyGrid() {
 
 ```tsx
 await exportToPdf(
-    apiRef.current.getVisibleRows(),
+    apiRef.current.getAllFilteredRows(),
     apiRef.current.getVisibleColumns(),
     {
         fileName: 'employee-report',
@@ -76,14 +78,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,7 +130,7 @@ 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
 
@@ -107,4 +144,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,20 @@ 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.
+- 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 +48,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 +72,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);
+  }}
+/>
 ```