@opencorestack/opengridx 2.1.0 → 3.0.1

package/docs/features/filtering.md

@@ -3,7 +3,7 @@
 OpenGridX provides a robust filtering system with support for both client-side and server-side operations.
 
 ## 📑 Overview
-- **Quick Filter**: Search across all columns simultaneously.
+- **Quick Filter**: Search across all visible, filterable columns at once.
 - **Column Filters**: Specific operators for different data types (string, number, date, etc.).
 - **Multi-Filter Groups**: Support for `AND`/`OR` logic operators.
 - **Server-Side Filtering**: Offload complex queries to your backend.
@@ -25,11 +25,24 @@ Simply define your columns with `filterable: true` (which is the default).
 />
 ```
 
+The filter model can be controlled (`filterModel` + `onFilterModelChange`) or left to the grid. Uncontrolled, the grid keeps its own filter model: the toolbar search and filter panel (`slots={{ toolbar: GridToolbar }}`) and `apiRef.current.setFilterModel()` change it, `onFilterModelChange` reports each change, and `initialState.filter.filterModel` sets the starting filter (which is how [state persistence](./state-persistence.md) restores it).
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  slots={{ toolbar: GridToolbar }}          // search + filters work without any filter props
+  initialState={{ filter: { filterModel: { items: [{ field: 'age', operator: '>', value: 30 }] } } }}
+/>
+```
+
 ### Server-Side Filtering
-Set `filterMode="server"` and handle the request in your `dataSource`.
+Set `filterMode="server"` and handle the request in your `dataSource`. The grid does not re-filter the rows it receives. Without a `dataSource`, fetch the filtered rows yourself from `onFilterModelChange` and pass them as `rows`.
 
 ```tsx
 <DataGrid
+  rows={[]}
+  columns={columns}
   filterMode="server"
   onFilterModelChange={(model) => console.log('Current Filters:', model)}
   dataSource={{
@@ -62,12 +75,35 @@ interface GridFilterItem {
 ```
 
 ### Supported Operators
+
+The filter panel offers these operators per column `type` (the first one is the default):
+
 | Type | Operators |
 | :--- | :--- |
-| **String** | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty`, `isAnyOf` |
-| **Number** | `equals`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
-| **Date** | `is`, `not`, `isEmpty`, `isNotEmpty` |
+| **String** (default) | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty` |
+| **Number** | `=`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
+| **Date** | `is`, `not`, `after`, `onOrAfter`, `before`, `onOrBefore`, `isEmpty`, `isNotEmpty` |
 | **Boolean** | `is` |
+| **singleSelect** | `isAnyOf`, `is`, `not` |
+
+Every operator in `GridFilterOperator` also works in a programmatic `filterModel` on any column; the panel shows such an operator as it is.
+
+### How values are matched
+
+- **Empty values do not filter.** An item whose `value` is `undefined`, `null`, a blank string or an empty array is ignored, so picking an operator before typing (or clearing the input) leaves the grid unfiltered. `isEmpty` / `isNotEmpty` need no value.
+- **Computed columns.** Cells are read through the column's `valueGetter`, so a computed column filters by the value it displays.
+- **Text operators** (`contains`, `equals`, `startsWith`, `endsWith`, `is`, `not`) compare case-insensitively.
+- **Number operators** compare numerically and accept numeric strings. A blank cell is empty, not `0`: it never matches `=`, `>`, `<` … and always matches `!=`.
+- **Date operators** compare local calendar days. Cells and values can be `Date` objects, epoch milliseconds or date strings; a `'YYYY-MM-DD'` string is read as a local date (not UTC midnight). `not` matches empty cells; the other date operators never do.
+- **`isAnyOf`** takes an array of allowed values. A single value is treated as a one-element list; an empty array does not filter.
+
+### Quick Filter
+
+`quickFilterValues` is a list of terms. A row matches when **every** term is found (case-insensitive substring) in at least one searched column.
+
+- Only **visible** columns with `filterable !== false` are searched. The row `id` and fields that are not columns are not searched.
+- Each column is searched by its value after `valueGetter` and, when the column has a `valueFormatter`, by the formatted text as well. `Date` values are searched as `YYYY-MM-DD`; objects are skipped.
+- The toolbar search box splits what the user types on whitespace, so `john london` becomes `['john', 'london']` and matches a row with first name John and city London.
 
 ---
 
@@ -76,10 +112,12 @@ The filter panel is accessible through the built-in `GridToolbar`. To use your o
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   slots={{
     toolbar: MyCustomToolbar
   }}
 />
 ```
 
-The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout.
+The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout. See [`<FilterPanel />`](../components/filter-panel.md) for how it edits the model.

package/docs/features/infinite-scroll.md

@@ -5,83 +5,91 @@ The OpenGridX DataGrid supports infinite scrolling (lazy loading), allowing you
 ## Concept
 
 When infinite scroll is enabled, the grid:
-1.  Disables client-side slicing (pagination in the UI).
-2.  Uses `paginationModel` internally to track the current page and page size.
+1.  Shows no pager and never slices the loaded rows (`pagination` is ignored).
+2.  Uses `paginationModel.page` and `pageSize` to decide how many rows should be loaded: `(page + 1) * pageSize`.
 3.  Triggers `onRowsScrollEnd` when the user scrolls near the bottom of the grid, signaling that more data should be fetched.
-4.  Data is typically **appended** to the existing rows, rather than replacing them.
+4.  **Appends** each response to the rows already loaded. Your `getRows` only returns the requested range.
 
 ## Usage
 
 To enable infinite scrolling:
 
-1.  Set `pagination={false}` to disable UI pagination controls.
+1.  Pass a `dataSource` whose `getRows` returns the rows in `[startRow, endRow)`.
 2.  Set `paginationMode="infinite"`.
-3.  Implement `onRowsScrollEnd` to update your data fetching logic/state (e.g., increment page number).
-4.  Ensure your `dataSource` manages the loaded rows correctly (usually appending).
+3.  Control `paginationModel` and advance `page` in `onRowsScrollEnd`. The grid does not advance the page on its own.
+4.  Set `sortingMode="server"` / `filterMode="server"` if `getRows` applies `sortModel` / `filterModel`.
 
 ```tsx
-import { DataGrid, GridDataSource } from '@opencorestack/opengridx';
+import { useCallback, useMemo, useState } from 'react';
+import {
+    DataGrid,
+    type GridColDef,
+    type GridDataSource,
+    type GridPaginationModel,
+} from '@opencorestack/opengridx';
+import '@opencorestack/opengridx/styles';
 
-// ... setup columns and mockApi ...
+type Person = {
+    id: number;
+    name: string;
+};
+
+const columns: GridColDef<Person>[] = [
+    { field: 'id', headerName: 'ID', width: 90 },
+    { field: 'name', headerName: 'Name', width: 200, sortable: true },
+];
+
+// With a dataSource the grid owns the loaded rows; `rows` only seeds the store.
+const NO_ROWS: Person[] = [];
+
+declare function fetchPeople(params: {
+    startRow: number;
+    endRow: number;
+    sort?: { field: string; sort: 'asc' | 'desc' };
+}): Promise<{ rows: Person[]; total: number }>;
 
 export default function InfiniteScrollDemo() {
-    const [paginationModel, setPaginationModel] = useState({
+    const [paginationModel, setPaginationModel] = useState<GridPaginationModel>({
         page: 0,
-        pageSize: 50
+        pageSize: 50,
     });
-    const [loading, setLoading] = useState(false);
-    const [allRows, setAllRows] = useState([]);
-
-    const dataSource: GridDataSource = useMemo(() => ({
-        getRows: async (params) => {
-            setLoading(true);
-            try {
-                // Fetch NEXT batch of rows from server
-                const response = await mockApi.getRows(params);
-                
-                // CRITICAL: Append new rows to existing rows
-                // (Or ensure response.rows contains ONLY new rows and parent handles appending)
-                return response;
-            } finally {
-                setLoading(false);
-            }
-        }
+
+    const dataSource = useMemo<GridDataSource<Person>>(() => ({
+        getRows: async ({ startRow, endRow, sortModel }) => {
+            // Return ONLY the requested range; the grid appends it to what is loaded.
+            const { rows, total } = await fetchPeople({ startRow, endRow, sort: sortModel[0] });
+            return { rows, rowCount: total };
+        },
     }), []);
 
     const handleScrollEnd = useCallback(() => {
-        if (!loading) {
-            // Increment page to fetch next batch
-            setPaginationModel(prev => ({
-                ...prev,
-                page: prev.page + 1
-            }));
-        }
-    }, [loading]);
+        setPaginationModel(prev => ({ ...prev, page: prev.page + 1 }));
+    }, []);
 
     return (
         <DataGrid
-            rows={[]} // Rows managed by dataSource
+            rows={NO_ROWS}
             columns={columns}
             dataSource={dataSource}
-            
-            // KEY PROPS FOR INFINITE SCROLL
-            pagination={false} 
             paginationMode="infinite"
             sortingMode="server"
-            
             paginationModel={paginationModel}
             onPaginationModelChange={setPaginationModel}
-            
             onRowsScrollEnd={handleScrollEnd}
+            height={400}
         />
     );
 }
 ```
 
+The grid needs a bounded height (here `height={400}`) and the stylesheet import; without either the viewport never scrolls, every loaded row renders, and `onRowsScrollEnd` keeps firing until the whole dataset is loaded.
+
 ## Implementation Details
 
-*   **`onRowsScrollEnd`**: Triggered when `scrollHeight - scrollTop - clientHeight < threshold` (default 100px).
-*   **Request Handling**: `useGridDataSource` includes logic to cancel stale requests if scrolling happens too quickly.
-*   **Appending vs Replacing**: 
-    *   In `infinite` mode, rows fetched for **new pages** are appended.
-    *   Rows fetched due to **sorting/filtering changes** replace the entire dataset (resetting to page 0).
+*   **`onRowsScrollEnd`**: Fired once when the end of the rows comes within 100px of the viewport bottom (`scrollHeight - scrollTop - clientHeight < 100`). It is re-armed when the user scrolls out of that zone or the row count changes, so one scroll gesture loads one page. It also fires after the rows change when the end is already in view, so a first page that does not fill the viewport keeps loading until it does. Horizontal scrolling never fires it.
+*   **Loading placeholders**: the skeleton rows shown while the next page loads are drawn after the last loaded row, only when the user has scrolled to the end of the data.
+*   **Ranges, not pages**: each request asks for `[rows loaded so far, (page + 1) * pageSize)`. Advancing the page twice within the 300 ms debounce, or while a request is in flight, still loads every row in between: one request runs at a time and, when it lands, the grid requests whatever the current page still needs. A response shorter than requested is treated as the end of the data until the page advances again.
+*   **Appending**: rows are appended; a row whose id (`getRowId`) is already loaded is skipped, so overlapping pages never show a row twice.
+*   **Restarting**: a sort, filter, page-size or `dataSource` (`getRows`) change replaces the rows with a new request from row 0 and reports page 0 through `onPaginationModelChange`. Setting a smaller page yourself reloads the list up to that page.
+*   **No pager**: `paginationMode="infinite"` ignores `pagination`; no pagination bar is shown and loaded rows are never sliced.
+*   **Stale responses**: a response for a list that has since restarted is discarded.

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: rendering tens of thousands of cards freezes the page, and in development the grid warns when the list view renders more than 2,000 items (v3.0.1+). `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.