@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/components/column-resize.md

@@ -1,12 +1,14 @@
 # `<ColumnResizeHandle />` & Resizing
 
-OpenGridX supports dynamic column resizing, allowing users to adjust the width of any column on the fly for better visibility of data. This is facilitated by the `ColumnResizeHandle`, which sits invisibly between adjacent column headers.
+OpenGridX supports dynamic column resizing, allowing users to adjust the width of any column on the fly for better visibility of data. This is facilitated by the `ColumnResizeHandle`, an internal component (not exported) that `<Header />` renders invisibly on the edge of each resizable column header.
 
 ## 📑 Overview
-- **Inter-Header Interaction**: A handle is placed on the right edge of each resizable column header.
-- **Visual Feedback**: On hover and during drag, the grid provides immediate visual cues.
-- **Constraints**: Supports `minWidth` and `maxWidth` values defined in your `GridColDef`.
-- **Double-Click Action**: Support for auto-sizing columns to fit their longest content is built-in.
+- **Where the handle is**: on the right edge of each resizable column header. Right-pinned columns are anchored to the right edge of the grid and grow leftwards, so their handle is on their **left** edge, and the edge you grab follows the pointer.
+- **Mouse, touch and pen**: the handle uses pointer events with pointer capture, so a resize keeps following the pointer outside the header and works on tablets and phones.
+- **Keyboard**: with a column header focused, **Alt+ArrowRight** / **Alt+ArrowLeft** widen / narrow the column by 10px (hold **Shift** for 50px). The handle is a `role="separator"` that reports the width in `aria-valuenow` (and `aria-valuemin` / `aria-valuemax`).
+- **Constraints**: `minWidth` and `maxWidth` from your `GridColDef` apply. Without `minWidth` a column can be narrowed to 50px; a column that is already narrower (a 30px icon column) is never snapped up to 50px. Without `maxWidth` there is no upper limit.
+- **Clicks are not resizes**: pressing and releasing the handle without moving it changes nothing (a flex column stays flex), and ending a resize with the pointer over the header never sorts the column.
+- **Double-click** does nothing (it is swallowed, so it does not sort). There is no auto-size to content.
 
 ---
 
@@ -36,12 +38,10 @@ const columns: GridColDef[] = [
 
 ## ⚙️ How it Works
 
-1. **Handle Deployment**: At the end of each `Header` component, a `ColumnResizeHandle` is mounted.
-2. **Drag Event Processing**: When the handle is dragged:
-   - It calculates the change in horizontal position (`deltaX`).
-   - It applies this change to the column's current width in the grid's state.
-3. **Boundaries Enforcement**: If the new width is less than `minWidth` (default 50px) or more than `maxWidth`, the change is rejected.
-4. **Finalization**: On mouse up, the new column width is persisted to the grid's `columnVisibilityModel` equivalents.
+1. **Handle Deployment**: every resizable header cell renders a `ColumnResizeHandle`.
+2. **Pointer processing**: on `pointerdown` the handle captures the pointer and remembers the column's current width. Each `pointermove` (throttled to one update per frame) sets the width to that start width plus the horizontal distance moved (minus it for a right-pinned column).
+3. **Boundaries Enforcement**: the width is clamped to the column's `minWidth` / `maxWidth` (see above).
+4. **Finalization**: on `pointerup` the final width is stored in the grid's `columnWidths` state (part of the `onStateChange` snapshot and of `initialState.columns.columnWidths`). A cancelled pointer (the browser took the gesture over) keeps the last width shown.
 
 ---
 
@@ -50,13 +50,17 @@ const columns: GridColDef[] = [
 The resize handle is not replaceable via the slots API. Style it through CSS:
 
 ```css
-.ogx__resize-handle {
+.ogx-column-resize-handle__line {
   width: 4px;
   background: #6366f1;
 }
+/* The handle of a right-pinned column, on its left edge */
+.ogx-column-resize-handle--start { }
+/* While a resize is in progress */
+.ogx-column-resize-handle--dragging { }
 ```
 
 ## 📝 Best Practices
-- **Define Min Widths**: Always set a reasonable `minWidth` so columns don't accidentally become 0px wide.
+- **Define Min Widths**: set a `minWidth` that fits your column's content.
 - **Persistence**: Use `onStateChange` to capture the current `columnWidths` from the state snapshot and save the user's preferred layout for their next visit.
 - **Content Fit**: Remember that large data values might hide behind narrow columns; use tooltips for overflow coverage.

package/docs/components/column-visibility.md

@@ -6,48 +6,71 @@ The `ColumnVisibilityPanel` provides an interactive list for users to toggle the
 - **Auto-Generating List**: It automatically builds a list of all togglable columns from the grid's state.
 - **Searchable Interface**: Includes a quick search to find specific columns in grids with many fields.
 - **Toggle State**: Synchronizes instantly with the grid's `columnVisibilityModel`.
-- **Exclusion Logic**: Automatically hides special internal columns (e.g., checkboxes) and columns marked with `hideable: false`.
+- **Exclusion Logic**: Lists only the columns it is given, leaving out those marked `hideable: false` (unless `showNonHideableColumns`). The grid's system columns (checkbox, expand, drag handle) are not columns, and its row-grouping `__group__` column is `hideable: false`, so neither appears.
+- **Accessible names**: Each checkbox is labelled with its column's `headerName` (or `field`), and the footer checkbox with "Show/Hide All"; clicking the name toggles the column.
 
 ---
 
 ## 🛠️ Usage
 
-### Toolbar Integration
-The most common way to use the visibility panel is within a dropdown menu in the grid's toolbar.
+The grid's toolbar and header menu already include this panel. The column menu's **Manage columns** opens the toolbar's Columns panel when `slots.toolbar` renders a `GridToolbar` that receives the grid's slot props; otherwise (no toolbar, or a custom toolbar without `GridToolbar`) it opens a standalone panel at the grid's top-right corner. Both close on Escape or a click outside. Import it yourself (exported since v2.1) only when you want the list somewhere else, such as a sidebar or modal. It is a controlled component: you own the visibility model and pass it in.
 
 ```tsx
-import { ColumnVisibilityPanel } from '@opencorestack/opengridx';
-
-// In your Toolbar component
-<Dropdown content={<ColumnVisibilityPanel />}>
-  <button>Columns</button>
-</Dropdown>
+import { useMemo, useState } from 'react';
+import { DataGrid, ColumnVisibilityPanel } from '@opencorestack/opengridx';
+import type { GridColDef } from '@opencorestack/opengridx';
+
+function Report({ rows, columns }: { rows: Row[]; columns: GridColDef<Row>[] }) {
+  const [visibility, setVisibility] = useState<Record<string, boolean>>({});
+  const visibleColumns = useMemo(
+    () => new Set(columns.filter(c => visibility[c.field] !== false).map(c => c.field)),
+    [columns, visibility],
+  );
+  const setAll = (visible: boolean) =>
+    setVisibility(Object.fromEntries(columns.filter(c => c.hideable !== false).map(c => [c.field, visible])));
+
+  return (
+    <div style={{ display: 'flex' }}>
+      <aside className="my-column-sidebar">
+        <ColumnVisibilityPanel
+          columns={columns}
+          visibleColumns={visibleColumns}
+          onVisibilityChange={(field, isVisible) => setVisibility(v => ({ ...v, [field]: isVisible }))}
+          onShowAll={() => setAll(true)}
+          onHideAll={() => setAll(false)}
+        />
+      </aside>
+      <DataGrid rows={rows} columns={columns} columnVisibilityModel={visibility} onColumnVisibilityModelChange={setVisibility} />
+    </div>
+  );
+}
 ```
 
-### Direct Integration
-You can also render it persistently beside the grid or within a custom modal.
+### Props (`ColumnVisibilityPanelProps`)
 
-```tsx
-<div className="my-column-sidebar">
-  <ColumnVisibilityPanel />
-</div>
-```
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `columns` | `GridColDef[]` | Columns to list |
+| `visibleColumns` | `Set<string>` | Fields currently visible |
+| `onVisibilityChange` | `(field, isVisible) => void` | Toggle one column |
+| `onShowAll` / `onHideAll` | `() => void` | Bulk actions (only `hideable` columns are affected) |
+| `onColumnReorder` | `(fromField, toField) => void` | Optional — enables drag-to-reorder in the list |
+| `onColumnOrderReset` | `() => void` | Optional — shows a reset-order action |
+| `showNonHideableColumns` | `boolean` | Show `hideable: false` columns as disabled rows. Default `false` |
 
 ---
 
 ## ⚙️ How it Works
 
-1. **Column Resolution**: The panel retrieves all columns defined in the `DataGrid`.
-2. **Filtration**: It ignores columns that should not be visible in the list:
-   - Columns starting with `__` (internal types).
-   - Columns explicitly marked as `hideable: false` in the `GridColDef`.
-3. **State Management**: When a user toggles a switch, it triggers an update to the grid's `columnVisibilityModel`, causing the grid to re-render only the affected columns.
+1. **Column Resolution**: The panel lists the `columns` it receives, in that order (the grid passes its current column order).
+2. **Filtration**: It leaves out columns marked `hideable: false`, unless `showNonHideableColumns` is set (then they are shown as disabled rows). There is no filtering by field name: a field starting with `__` is listed like any other.
+3. **State Management**: Toggling a checkbox calls `onVisibilityChange(field, isVisible)`; inside the grid that updates `columnVisibilityModel` and fires `onColumnVisibilityModelChange`.
 
 ---
 
 ## 🎨 Controlling Visibility Programmatically
 
-The column visibility panel is an internal component; it cannot be replaced via the slots API. Use the controlled props to drive visibility from outside:
+The built-in panel cannot be replaced through the slots API. To drive visibility from outside, use the controlled props, optionally together with a standalone `ColumnVisibilityPanel` as shown above:
 
 ```tsx
 <DataGrid

package/docs/components/datagrid.md

@@ -22,19 +22,20 @@ function MyGrid() {
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `rows` | `R[]` | `[]` | The dataset to display. |
-| `columns` | `GridColDef[]` | `[]` | Column definitions. |
-| `getRowId` | `(row: R) => GridRowId` | `row.id` | Unique ID for each row. |
+| `rows` | `R[]` | — | **Required.** The dataset to display (`[]` when a `dataSource` supplies the rows). |
+| `columns` | `GridColDef<R>[]` | — | **Required.** Column definitions. |
+| `getRowId` | `(row: R) => GridRowId` | `row.id` | Unique ID for each row. Only keys the grid's store; row objects are never copied or given an `id` (v3.0+). Duplicate ids keep the first row and log a development warning. |
 | `height` | `number \| string` | `undefined` | Height of the grid container. |
 | `loading` | `boolean` | `false` | Displays a loading skeleton/shimmer. |
-| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Row height preset: compact = 32 px, standard = `rowHeight`, comfortable = 72 px. |
+| `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Row height preset: compact = 32 px, standard = `rowHeight`, comfortable = 72 px. Inside a `DataGridThemeProvider`, the theme's `grid.rowHeightCompact` / `rowHeightStandard` / `rowHeightComfortable` replace these defaults (an explicit `rowHeight` still wins for standard). |
 | `checkboxSelection` | `boolean` | `false` | Enable row checkboxes. |
 | `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. |
+| `disableClipboardCopy` | `boolean` | `false` | When `true`, Ctrl+C / Cmd+C does not copy the selected rows. `apiRef.current.copySelectedRows()` still works. |
 | `pagination` | `boolean` | `false` | Enable/Disable bottom pagination bar. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). Omit for uncontrolled; use `initialState` to set the initial page/pageSize. |
 | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. |
-| `initialState` | `GridInitialState` | `undefined` | Initial configuration (sorting, columns, pagination, etc). |
+| `initialState` | `GridInitialState` | `undefined` | Initial configuration (sorting, filter, columns, pagination, density), read on mount. |
 | `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. |
 
 ## 🔃 Sorting
@@ -50,21 +51,22 @@ function MyGrid() {
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `rowGroupingModel` | `string[]` | `[]` | Fields to group by (in order). |
-| `groupingColDef` | `GridColDef` | — | Config for the dedicated `__group__` column created at position 0, auto-pinned left, when grouping is active. |
+| `groupingColDef` | `Partial<GridColDef<R>>` | — | Config for the dedicated `__group__` column created at position 0, auto-pinned left, when row grouping or tree data is active. Every key is optional; `field` is always `'__group__'`. |
 
 ## 🖱️ Interaction & Events
 
 | Prop | Type | Description |
 | :--- | :--- | :--- |
-| `onRowClick` | `(params) => void` | Fired when clicking a row body. |
-| `onCellClick` | `(params) => void` | Fired when clicking a specific cell. |
+| `onRowClick` | `(params: GridRowParams) => void` | Fired when clicking a row body (not for synthetic group rows, which toggle instead). |
+| `onRowDoubleClick` | `(params: GridRowParams) => void` | Fired when double-clicking a row. |
+| `onCellClick` | `(params: GridCellParams) => void` | Fired when clicking a specific cell. |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | Fired when page or page size changes. |
-| `onStateChange` | `(state) => void` | Fired on any internal state update. |
-| `processRowUpdate` | `(new, old) => R \| Promise<R>` | Fired after a cell edit is committed. |
+| `onStateChange` | `(state: GridState) => void` | Fired on mount and whenever the value of the sort, filter, pagination, column or density state changes. |
+| `processRowUpdate` | `(new, old) => R \| Promise<R>` | Called once per committed cell edit; return the row to store (or a Promise of it). See [Editing](../features/editing-reordering.md#commit-and-cancel). |
 
 ## 📦 Slots
 
-Customize internal components using the `slots` prop.
+Customize internal components using the `slots` prop (`GridSlots`: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`) and pass them props with `slotProps`. See [`GridSlots`](../API_REFERENCE.md#gridslots-and-gridslotprops).
 
 ```tsx
 <DataGrid
@@ -87,7 +89,7 @@ Customize internal components using the `slots` prop.
 - [Pagination](pagination.md)
 - [Tooltip](tooltip.md)
 - [Column Visibility](column-visibility.md)
-- [Column Grouping](column-group-header.md)
+- [Column Group Headers](column-group-header.md)
 - [Column Resizing](column-resize.md)
 - [Empty State](empty-state.md)
 - [Error Overlay](error-overlay.md)

package/docs/components/empty-state.md

@@ -8,10 +8,11 @@ Internal component rendered when the grid has no rows to display. Replaces the r
 | :--- | :--- | :--- |
 | `noRowsLabel` | `string` | Text shown beneath the empty-state icon. Controlled by the `noRowsLabel` DataGrid prop. |
 | `width` | `number` | Pixel width of the empty-state container, matched to the grid's total column width. |
+| `overlay` | `ReactNode` | The rendered `noRowsOverlay` slot, shown instead of the icon and label. |
 
 ## 🔄 When it renders
 
-`GridEmptyState` renders when `allRenderableRows.length === 0` and the grid is not in a loading state. The loading skeleton takes precedence — if `loading={true}` the skeleton rows are shown instead.
+`GridEmptyState` renders when no row passes the filter, the grid is not loading and no data-source error is shown. The loading state takes precedence — while `loading` (or a `dataSource` request) is pending the skeleton rows (or the `loadingOverlay` slot) are shown instead, and a `dataSource` error shows the error overlay.
 
 ## 🎨 Customizing via slot
 

package/docs/components/error-overlay.md

@@ -1,30 +1,35 @@
 # `<GridErrorOverlay />`
 
-Internal component rendered when a `GridDataSource` fetch fails. Displays an error icon, a human-readable message, and a **Retry** button that calls `window.location.reload()`.
+Internal component rendered when a `GridDataSource` fetch fails. Displays an error icon, a human-readable message, and a **Retry** button that runs the failed `getRows` request again (v3.0+; it used to reload the whole page).
 
 ## ⚙️ Props
 
 | Prop | Type | Description |
 | :--- | :--- | :--- |
-| `error` | `{ message?: string } \| null` | The error object from `state.dataSource.error`. When `null` the component renders nothing (`null` return). |
+| `error` | `unknown` | The value the fetch rejected with (`state.dataSource.error`). When falsy the component renders nothing. |
+| `onRetry` | `() => void` | Re-runs the request. DataGrid passes it whenever a `dataSource` is set; without it the Retry button is not shown. |
 
 ## 🔄 When it renders
 
-`GridErrorOverlay` only appears when using a server-side `dataSource` prop. When a fetch throws, DataGrid catches the error and stores it in internal state. The overlay replaces the row viewport until the user retries.
+`GridErrorOverlay` only appears when using a server-side `dataSource` prop. When a fetch throws, DataGrid catches the error and stores it in internal state. The overlay replaces the row viewport until a request succeeds: **Retry**, or any change that refetches (page, sort, filter). A failed children request of a server-side tree node does not show it.
 
 ```tsx
 <DataGrid
     dataSource={{
-        getRows: async ({ filterModel, sortModel, paginationModel }) => {
-            const res = await fetch('/api/employees');
+        getRows: async ({ startRow, endRow, sortModel, filterModel }) => {
+            const res = await fetch('/api/employees', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ startRow, endRow, sortModel, filterModel }),
+            });
             if (!res.ok) throw new Error(`HTTP ${res.status}`);
-            return res.json();
+            return res.json(); // { rows, rowCount }
         }
     }}
 />
 ```
 
-If `getRows` throws, the overlay renders with the thrown error's `message`.
+If `getRows` throws, the overlay renders the rejection's `message`: an `Error`, a string, or any object with a string `message` (such as an HTTP-client error). Otherwise it shows a generic message.
 
 ## ♿ Accessibility
 

package/docs/components/filter-panel.md

@@ -24,16 +24,36 @@ renderCell: (params) => {
 
 ## 🔌 Integration
 
-The `<DataGrid />` manages the visibility of the Filter Panel via its internal state. It is usually triggered from the Column Menu or the Toolbar.
+Inside the grid, the Filter Panel opens from the toolbar's **Filters** button (`slots={{ toolbar: GridToolbar }}`). `FilterPanel` and `FilterPanelProps` are also exported, to host the editor yourself:
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `filterModel` | `GridFilterModel` | The model to edit. |
+| `columns` | `GridColDef[]` | The columns offered (those with `filterable: false` are left out). |
+| `onFilterModelChange` | `(model: GridFilterModel) => void` | Called with the edited model. |
 
 ## 📝 Configuration
 
-Filter operators are automatically determined based on the column's `type`:
-- `string`: contains, equals, startsWith, endsWith, isAnyOf.
-- `number`: =, !=, >, >=, <, <=.
-- `date` / `dateTime`: is, isNot, isAfter, isBefore.
-- `boolean`: isTrue, isFalse.
+The panel shows one row per column with `filterable !== false` (the synthetic row-grouping column is not filterable). Operators and the value control depend on the column's `type`:
+
+| `type` | Operators (first = default) | Value control |
+| :--- | :--- | :--- |
+| `string` (default) | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty` | Text input |
+| `number` | `=`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` | Text input |
+| `date` | `is`, `not`, `after`, `onOrAfter`, `before`, `onOrBefore`, `isEmpty`, `isNotEmpty` | Date input (`YYYY-MM-DD`) |
+| `boolean` | `is` | Select: **Any** (no filter), `true`, `false` |
+| `singleSelect` | `isAnyOf`, `is`, `not` | Built from `valueOptions`: a multi-select for `isAnyOf` (the value is an array of option values), a select with **Any** for `is` / `not`. Option values keep their type, labels are shown. Without `valueOptions`, a text input (comma-separated for `isAnyOf`). |
+
+`isEmpty` / `isNotEmpty` hide the value control. An item whose operator the column type does not list (set programmatically) is shown with that operator.
+
+## 🔄 How edits reach the model
+
+- Typing is debounced by 300 ms before `onFilterModelChange` fires. Opening the panel never emits anything and never rewrites existing values (arrays, numbers and dates stay as they are).
+- Changing the operator right after typing keeps the typed text.
+- Each row edits the **first** root-level item for its column and replaces it in place. Filter groups (`GridFilterGroup`) and further items for the same column are passed through untouched; the panel notes how many such conditions it does not show.
+- Picking an operator without typing, or clearing the input, leaves an item with an empty value, which does not filter. The row's **×** button removes the item.
+- If the model is changed from outside the panel (the toolbar's **Clear all**, or your own code) while typing is still pending, the pending text is dropped instead of being re-applied.
 
-## 🎨 Slot Usage
+## 🎨 Customizing
 
-While the Filter Panel is a complex internal component, its appearance can be influenced by CSS variables or by providing a custom implementation to the `filterPanel` slot in advanced use cases.
+There is no slot for the Filter Panel. Restyle it with CSS (its classes start with `ogx-filter`) and the theme's overlay colours, replace only the toolbar's trigger with `renderFilterButton`, or render your own editor that writes a `GridFilterModel` to the grid's `filterModel` prop.

package/docs/components/header.md

@@ -4,21 +4,29 @@ Manages the column headers, sorting triggers, column resizing, and column groupi
 
 ## ⚙️ Props
 
+`Header` and its props type `HeaderProps` are exported. The main props:
+
 | Prop | Type | Description |
 | :--- | :--- | :--- |
 | `columns` | `GridColDef[]` | Column definitions for the visible viewport. |
+| `allColumns` | `GridColDef[]` | Every rendered data column in render order (left-pinned, unpinned, right-pinned) with its resolved `width`. Column group rows are laid out over these. Defaults to `columns`. |
 | `columnGroupingModel` | `GridColumnGroupingModel` | Hierarchy for multi-level header spanning. |
-| `sortModel` | `GridSortModel` | Current sorting state for highlight and icons. |
+| `sortModel` | `GridSortItem[]` | Current sorting state for highlight, icons and priority badges. |
 | `onSort` | `(field, direction) => void` | Callback triggered on a plain click — replaces the sort model with a single key. |
-| `onSortAdd` | `(field, direction) => void` | Callback triggered on Shift+click or when `multiSort` is active — appends/cycles the key without replacing others. |
+| `onSortAdd` | `(field, direction) => void` | Callback triggered on Shift+click or when `multiSort` is active — appends/cycles the key without replacing others (an existing key keeps its priority). Also used by the column menu for **Unsort** and for a direction change on an already-sorted column. |
 | `multiSort` | `boolean` | When `true`, every click routes to `onSortAdd` instead of `onSort`. Wired from the `multiSort` prop on `<DataGrid>`. |
-| `onColumnResize` | `Function` | Callback for manual column width changes. |
+| `onColumnResize` | `(field: string, newWidth: number) => void` | Callback for manual column width changes. Without it, headers are not resizable. |
+| `onHideColumn` / `onPinColumn` / `onManageColumns` | `(field) => void` / `(field, side \| null) => void` / `() => void` | Column menu actions. |
 | `pinnedColumns` | `GridColumnPinning` | Coordinates sticky positioning for headers. |
-| `checkboxSelection` | `boolean` | Renders the "Select All" checkbox. |
+| `checkboxSelection` | `boolean` | Reserves the checkbox column. The "Select All" checkbox is rendered only when `onSelectAll` is also passed (the grid omits it with `disableMultipleRowSelection`). |
+| `onSelectAll` | `(isSelected: boolean) => void` | Called by the "Select All" checkbox. |
+| `allSelected` / `someSelected` | `boolean` | Checked / indeterminate state of the "Select All" checkbox. |
+| `focusedCell` | `{ id: GridRowId \| null; field: string } \| null` | The grid's focus position. `id: null` means the header cell of `field` is focused (v3.0; it used to be the string `'HEADER'`, which a real row id could collide with). DOM focus is moved by the grid, not by `<Header />`. |
+| `columnIndexMap` | `Map<string, number>` | Position of each visible data column in render order. Used for `aria-colindex` and the `colIndex` passed to `renderHeader`, so they match the body cells and do not change with horizontal scrolling. |
 
 ## 📐 Column Grouping
 
-The `<Header />` dynamically calculates the nesting depth of your `columnGroupingModel` and renders additional [Column Group Headers](column-group-header.md) above the main column headers.
+The `<Header />` dynamically calculates the nesting depth of your `columnGroupingModel` and renders one group row per level above the main column headers. Group cells are sized from `allColumns`, so they match their member columns' resolved widths; cells over pinned columns are sticky. See [Column Group Headers](../API_REFERENCE.md#️-column-group-headers) for the full behaviour.
 
 ```tsx
 const columnGroupingModel = [
@@ -35,7 +43,18 @@ const columnGroupingModel = [
 Unless `disableColumnMenu` is set to `true` in a column's `GridColDef`, each header cell renders a menu icon. In addition, the header facilitates manual [Column Resizing](column-resize.md).
 
 Clicking the menu icon opens a popover with actions to:
-- Sort Asc/Desc
-- Pin Left/Right/None
-- Hide Column
-- Manage Columns (Open [Visibility Panel](column-visibility.md))
+- Sort Asc/Desc/Unsort (acts on that column only; other sort keys are kept)
+- Pin Left/Right/None (left out for columns with `pinnable: false`)
+- Hide Column (left out for columns with `hideable: false`)
+- Manage Columns (opens the toolbar's Columns panel when `slots.toolbar` renders `GridToolbar`, otherwise the standalone [Visibility Panel](column-visibility.md))
+
+**Keyboard** (v3.0): with a header cell focused, **Alt+ArrowDown** or **Ctrl+Enter** / **Cmd+Enter** opens its menu. Focus moves to the first item (also when the menu is opened with the mouse); **ArrowUp** / **ArrowDown** / **Home** / **End** move between items, and **Escape**, **Tab** or choosing an item closes the menu and returns focus to the header cell. See [Keyboard & Accessibility](../features/keyboard-navigation.md).
+
+**Alt+ArrowRight** / **Alt+ArrowLeft** on a focused header widen / narrow its column by 10px (**Shift** for 50px), unless the column has `resizable: false`.
+
+**Drag-reorder**: unpinned headers are draggable. Pinned headers (and the row-grouping column) are not, and are not drop targets.
+
+## ♿ Accessibility
+
+- Header rows carry `aria-rowindex` (column-group rows first). Header cells carry `aria-colindex`, matching the body cells of the same column; the system columns (reorder, detail-panel toggle, select-all) come first and are focusable from the keyboard.
+- Only the primary sort column has `aria-sort="ascending"` / `"descending"`; other sortable headers have `aria-sort="none"`. With multi-sort each sorted header also has an `aria-description` such as "Sorted descending, sort priority 2 of 2".

package/docs/components/pagination.md

@@ -1,26 +1,32 @@
 # `<Pagination />`
 
-Handles row limit selection and page navigation. Compatible with both client-side and server-side data modes.
+Handles row limit selection and page navigation. Compatible with both client-side and server-side data modes. `DataGrid` renders it when `pagination` is set. `Pagination` and `PaginationProps` are exported (v3.0+), so a `pagination` slot can wrap or restyle it; the slot receives the same props.
 
 ## ⚙️ Props
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `page` | `number` | `0` | The current active page (0-indexed). |
-| `pageSize` | `number` | `100` | Number of rows per page. |
-| `rowCount` | `number` | `0` | Total number of rows (used to calculate page count). |
-| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the "Rows per page" dropdown. |
+| `page` | `number` | — | **Required.** The current active page (0-indexed). |
+| `pageSize` | `number` | — | **Required.** Number of rows per page. |
+| `rowCount` | `number` | — | **Required.** Total number of rows (used to calculate page count). |
+| `onPageChange` | `(page: number) => void` | — | **Required.** Called with the new page. |
+| `onPageSizeChange` | `(pageSize: number) => void` | — | **Required.** Called with the new page size (the grid then goes to page 0). |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options for the "Rows per page" dropdown. When `pageSize` is not one of them it is added as an extra option, so the select always shows the size in use. |
+| `showFirstButton` / `showLastButton` | `boolean` | `true` | Show the first-page / last-page buttons. |
+| `localeText` | `Pick<GridLocaleText, 'paginationRowsPerPage' \| 'paginationOf' \| 'paginationPage'>` | — | Label overrides (see below). |
+
+A `page` outside `0 … pageCount - 1` is displayed as the nearest valid page (the last page for a page past the end), and Previous/Next move from the displayed page. A `pageSize` below 1 (0, negative, `NaN`) is treated as 1.
 
 ## 🕹️ Interaction
 
 The pagination component communicates state changes back to the `<DataGrid />` via:
-- `onPageChange`: Triggered when clicking Next/Prev or a page number.
+- `onPageChange`: Triggered by the first / previous / next / last buttons.
 - `onPageSizeChange`: Triggered when changing the rows-per-page limit.
 
 ## 🔄 Modes
 
 - **Client-side**: Pagination happens automatically on the local `rows` array.
-- **Server-side**: Pagination state is passed to the `GridDataSource` to fetch new chunks of data.
+- **Server-side**: With `paginationMode="server"`, page changes are passed to the `GridDataSource` (or to your `onPaginationModelChange`) to fetch the page; `rowCount` is the server total.
 
 ## 🎨 Customizing
 You can replace the internal pagination UI using the `pagination` slot:
@@ -35,7 +41,7 @@ You can replace the internal pagination UI using the `pagination` slot:
 
 ## 🌍 Internationalisation
 
-Pass `localeText` on `<DataGrid />` to override the text labels in the Pagination component (rows-per-page, range, and page-counter labels). Note: ARIA labels (`aria-label="Pagination"`, `aria-label="Rows per page"`) and button titles (`title="Previous page"`, `title="Next page"`) are currently hardcoded and not overrideable via `localeText`.
+Pass `localeText` on `<DataGrid />` to override the text labels in the Pagination component (rows-per-page, range, and page-counter labels). The rows-per-page select takes its accessible name from the `paginationRowsPerPage` label. The navigation landmark label (`aria-label="Pagination"`) and the button labels and titles (`Go to next page`, `Next page`, …) are hardcoded and not overrideable via `localeText`.
 
 | Key | Type | Default |
 | :--- | :--- | :--- |

package/docs/components/row.md

@@ -4,9 +4,12 @@ Manages a horizontal collection of cells. Includes support for selection, expans
 
 ## ⚙️ Props
 
+`Row` and its props type `RowProps` are exported. The main props (see `RowProps` for the rest, such as the drag, edit and spanning callbacks the grid wires):
+
 | Prop | Type | Description |
 | :--- | :--- | :--- |
 | `row` | `GridRowModel` | The data object for this row. |
+| `rowId` | `GridRowId` | The row's id (from the grid's `getRowId`). Defaults to `row.id`; the grid always passes it (v3.0+). |
 | `columns` | `GridColDef[]` | Columns currently visible in the viewport. |
 | `rowIndex` | `number` | Index used for virtualization and alternating colors. |
 | `isSelected` | `boolean` | Checkbox / Selection state. |
@@ -15,6 +18,19 @@ Manages a horizontal collection of cells. Includes support for selection, expans
 | `isDetailPanelExpanded` | `boolean` | Current expansion state. |
 | `rowReordering` | `boolean` | Enables the drag handle for reordering rows. |
 | `rowHeight` | `number` | Height in pixels (default: 52). |
+| `rowMeta` | `GridRowMeta` | Hierarchy metadata for the row (tree data / row grouping), passed to cells as `params.rowMeta`. |
+| `onRowClick` / `onRowDoubleClick` | `(params: GridRowParams) => void` | Row click handlers. |
+| `onCellClick` | `(params: GridCellParams) => void` | Cell click handler. |
+| `onSelectionChange` | `(rowId: GridRowId, isSelected: boolean) => void` | Called by the row's checkbox. |
+| `isCellEditable` | `(params: GridCellParams) => boolean` | Per-cell editability predicate, combined with `colDef.editable` and the row's `rowMeta` to decide each cell's `isEditable`. |
+| `columnIndexMap` | `Map<string, number>` | Position of each visible data column in render order. Gives cells their `colIndex` / `aria-colindex` independently of the horizontal render window. |
+| `ariaRowIndex` | `number` | 1-based `aria-rowindex` in the whole grid (header rows and earlier pages included). Defaults to `rowIndex + 2`. |
+
+## ♿ Accessibility
+
+- `aria-rowindex` (from `ariaRowIndex`), `aria-selected`; with tree data or row grouping, `aria-level` (depth + 1) and, on rows with children, `aria-expanded`.
+- The reorder handle, detail-panel toggle and checkbox cells have `data-field` (`__reorder_col__`, `__expand_col__`, `__checkbox_col__`), `tabIndex={-1}` and `aria-colindex`, so they are keyboard focus stops like data cells.
+- The detail panel is rendered as a `role="row"` with one `role="gridcell"` spanning every column, referenced by the expand cell's `aria-controls` while open.
 
 ## 📐 Row Pinning
 
@@ -30,18 +46,18 @@ The grid supports "Zebra" striping via CSS:
 
 When `getDetailPanelContent` is provided, the `<Row />` renders an expandable container below itself to show supplemental data.
 
-## ⚠️ v2.0 — Runtime `_*` hierarchy fields removed
+## ⚠️ v3.0 — Runtime `_*` hierarchy fields removed
 
-The internal hierarchy fields (`_hasChildren`, `_treeDepth`, `_isExpanded`, `_groupingField`, `_groupingValue`, `_descendantCount`, `_isGroupRow`) are no longer injected onto the runtime row object as of v2.0. Use `params.rowMeta` instead:
+Up to v2.x the grid copied tree-data and row-grouping rows and added hierarchy fields to the copies (`_hasChildren`, `_treeDepth`, `_isExpanded`, `_groupingField`, `_groupingValue`, `_descendantCount`, `_isGroupRow`). Since v3.0 nothing is added: `params.row` is your own row object, unchanged. Read the hierarchy from `params.rowMeta` instead:
 
 ```tsx
-// ❌ v1 shim — no longer works in v2:
+// ❌ v2.x — the field is undefined in v3.0:
 renderCell: (params) => {
   const hasChildren = (params.row as Record<string, unknown>)._hasChildren;
   return hasChildren ? <GroupIcon /> : params.value;
 }
 
-// ✅ v2:
+// ✅ v1.1+ (the only way since v3.0):
 renderCell: (params) => {
   const hasChildren = params.rowMeta?.hasChildren;
   return hasChildren ? <GroupIcon /> : params.value;
@@ -49,4 +65,4 @@ renderCell: (params) => {
 ```
 
 `params.rowMeta` is `undefined` for flat rows with no active tree-data or row-grouping.
-See [`GridRowMeta` architecture doc](../architecture/grid-row-meta.md) for the full data flow.
+See [`GridRowMeta` architecture doc](../architecture/grid-row-meta.md) for the full data flow and the [v2 → v3 migration guide](../migration/v2-to-v3.md).

package/docs/components/toolbar.md

@@ -20,7 +20,11 @@ import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
 />
 ```
 
-`GridToolbar` automatically hides buttons for features whose callbacks are not wired. For example, if you don't pass `onFilterModelChange` the search bar and filter button are not rendered.
+`GridToolbar` hides the buttons whose callbacks it does not receive: no `onFilterModelChange`, no search bar and Filters button; no `onColumnVisibilityModelChange`, no Columns button; no `onAggregationModelChange`, no Summaries button; no `onPivotModelChange`, no Pivot button. Mounted through `slots.toolbar`, the grid always passes the filter, column-visibility and aggregation callbacks, and the pivot ones when `pivotMode`, `pivotModel` or `onPivotModelChange` is set, so those buttons show without further props. A standalone `<GridToolbar />` shows only what you wire.
+
+One panel is open at a time. Every panel closes on Escape; the Columns, Summaries and Pivot panels also close on a click outside them. Each trigger button has `aria-haspopup="dialog"` and an `aria-expanded` state.
+
+The Summaries panel lists each aggregable column with the functions it allows: its `availableAggregationFunctions` when set, otherwise every built-in function (`sum`, `avg`, `count`, `min`, `max`, `unique`). Names that are not built-in functions are not offered.
 
 ---
 
@@ -29,19 +33,20 @@ import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `columns` | `GridColDef[]` | `[]` | Column definitions (injected automatically when used via `slots`). |
-| `baseColumns` | `GridColDef[]` | — | Pre-pivot column definitions, used by the Pivot panel to avoid showing synthetic columns. |
+| `baseColumns` | `GridColDef[]` | — | Pre-pivot column definitions. The Pivot panel lists these instead of the generated pivot columns, and the Summaries panel only offers columns that are among them (a summary on a generated pivot column would do nothing). |
 | `aggregationModel` | `GridAggregationModel` | `{}` | Current aggregation configuration. |
-| `onAggregationModelChange` | `(model) => void` | — | Called when the user changes aggregation settings. |
+| `onAggregationModelChange` | `(model) => void` | — | Called when the user changes aggregation settings. Presence of this prop shows the Summaries button. |
 | `pivotModel` | `GridPivotModel` | — | Current pivot configuration. |
 | `onPivotModelChange` | `(model) => void` | — | Called when the user changes pivot settings. Presence of this prop shows the Pivot button. |
-| `filterModel` | `GridFilterModel` | — | Current filter model. Presence of this prop shows the search bar and Filter button. |
-| `onFilterModelChange` | `(model) => void` | — | Called when the user changes filters or the search query. |
+| `filterModel` | `GridFilterModel` | — | Current filter model. |
+| `onFilterModelChange` | `(model) => void` | — | Called when the user changes filters or the search query. Presence of this prop shows the search bar and Filters button. |
 | `columnVisibilityModel` | `Record<string, boolean>` | `{}` | Current column visibility state. |
 | `onColumnVisibilityModelChange` | `(model) => void` | — | Called when the user shows/hides columns. Presence shows the Columns button. |
 | `onColumnReorder` | `(from, to) => 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` | — | When `true`, opens the Columns panel immediately (used internally by the column header menu). |
-| `onColumnsPanelClose` | `() => void` | — | Called when the Columns panel closes after a `forceColumnsOpen`. |
+| `forceColumnsOpen` | `boolean` | — | When it becomes `true`, opens the Columns panel. `DataGrid` sets it for the column menu's **Manage columns**. A `GridToolbar` that receives it from the grid (spread the slot props into it) shows the panel; when no such toolbar is rendered, the grid opens its standalone Columns panel instead. |
+| `onColumnsPanelClose` | `() => void` | — | Called whenever the Columns panel closes: its button, a custom `renderColumnsButton`, another panel opening, click-outside or Escape. |
+| `showNonHideableColumns` | `boolean` | `false` | Show `hideable: false` columns in the Columns panel as disabled rows. |
 | `children` | `ReactNode` | — | Content rendered in the **left** side of the toolbar (before the spacer). |
 | `rightContent` | `ReactNode` | — | Content rendered in the **right** side of the toolbar (after all built-in buttons). |
 | `className` | `string` | — | Additional CSS class applied to the toolbar root `<div>`. Use for visual overrides without replacing the component. |
@@ -74,11 +79,13 @@ Passed to `renderQuickFilter`.
 
 ```ts
 interface ToolbarQuickFilterRenderProps {
-  value: string;                  // Current search string
+  value: string;                  // Current search string (quickFilterValues joined with spaces)
   onChange: (value: string) => void; // Call with new string on input change
 }
 ```
 
+The toolbar splits the string passed to `onChange` on whitespace, so each word becomes one `quickFilterValues` term and a row matches when every term is found in some visible column (`john london` matches first name John, city London). See [Quick Filter](../features/filtering.md#quick-filter).
+
 ---
 
 ## Customization patterns
@@ -218,4 +225,15 @@ function MyToolbar() {
 <DataGrid slots={{ toolbar: MyToolbar }} />
 ```
 
-The custom component receives all `GridToolbarProps` via `slotProps.toolbar`.
+The custom component receives the toolbar props the grid owns (`columns`, `baseColumns`, the filter / visibility / aggregation / pivot models and their change handlers, `onColumnReorder`, `onColumnOrderReset`, `forceColumnsOpen`, `onColumnsPanelClose`) plus `apiRef`, with `slotProps.toolbar` spread over them. Spread them into a `GridToolbar` to keep the built-in buttons:
+
+```tsx
+import { GridToolbar } from '@opencorestack/opengridx';
+import type { GridToolbarProps } from '@opencorestack/opengridx';
+
+function MyToolbar(props: GridToolbarProps) {
+  return <GridToolbar {...props} rightContent={<span>Custom</span>} />;
+}
+```
+
+`slotProps.toolbar` is typed as `GridToolbarProps` plus any extra keys (v3.0+), so the render props above get their parameter types inferred and a misspelt built-in key with a wrong value type is a type error.