@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/features/sorting-pagination.md

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

package/docs/features/state-persistence.md

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

package/docs/features/toolbar-customization.md

@@ -19,10 +19,6 @@ import {
 <DataGrid
   rows={rows}
   columns={columns}
-  filterModel={filterModel}
-  onFilterModelChange={setFilterModel}
-  columnVisibilityModel={columnVisibilityModel}
-  onColumnVisibilityModelChange={setColumnVisibilityModel}
   slots={{ toolbar: GridToolbar }}
   slotProps={{
     toolbar: {
@@ -39,6 +35,19 @@ import {
 />
 ```
 
+When the toolbar is mounted through `slots.toolbar`, the grid passes it the filter, column-visibility, aggregation and column-order state and handlers itself, so search, Filters, Columns and Summaries work without any controlled props (v3.0+: the search box and Filters button no longer need `filterModel` / `onFilterModelChange`). Pass `filterModel` + `onFilterModelChange` (and the other controlled pairs) only when you want to own that state.
+
+### Which buttons appear
+
+`GridToolbar` renders a control only when it has the handler it needs. Under `slots.toolbar` the grid supplies these, except for pivot:
+
+| Control | Shown when |
+| :--- | :--- |
+| Search + Filters | `onFilterModelChange` is present (always under `slots.toolbar`) |
+| Columns | `onColumnVisibilityModelChange` is present (always under `slots.toolbar`) |
+| Pivot | `onPivotModelChange` is present (under `slots.toolbar`: when `pivotMode`, `pivotModel` or `onPivotModelChange` is set on the grid) |
+| Summaries | `onAggregationModelChange` is present (always under `slots.toolbar`; a standalone `<GridToolbar>` without it shows no Summaries button, v3.0+) |
+
 ---
 
 ## New props on `GridToolbarProps`
@@ -70,12 +79,12 @@ interface ToolbarButtonRenderProps {
 
 ```ts
 interface ToolbarQuickFilterRenderProps {
-  value: string;
-  onChange: (value: string) => void;
+  value: string;                     // quickFilterValues joined with spaces
+  onChange: (value: string) => void; // split on whitespace into quickFilterValues terms
 }
 ```
 
-Both types are exported from the package:
+Both types are exported from the package. `slotProps.toolbar` is typed as `Record<string, unknown>`, so annotate render-prop parameters with these types (an unannotated `(props) => …` is an implicit `any` under `strict`):
 
 ```ts
 import type { ToolbarButtonRenderProps, ToolbarQuickFilterRenderProps } from '@opencorestack/opengridx';
@@ -104,7 +113,7 @@ function MySearchBar({ value, onChange }: ToolbarQuickFilterRenderProps) {
 
 slotProps={{
   toolbar: {
-    renderQuickFilter: (props) => <MySearchBar {...props} />,
+    renderQuickFilter: (props: ToolbarQuickFilterRenderProps) => <MySearchBar {...props} />,
   },
 }}
 ```
@@ -126,7 +135,7 @@ function MyFilterBtn({ onClick, isOpen, activeCount }: ToolbarButtonRenderProps)
 
 slotProps={{
   toolbar: {
-    renderFilterButton: (props) => <MyFilterBtn {...props} />,
+    renderFilterButton: (props: ToolbarButtonRenderProps) => <MyFilterBtn {...props} />,
   },
 }}
 ```
@@ -144,7 +153,7 @@ const apiRef = useGridApiRef();
   slotProps={{
     toolbar: {
       renderExportButton: () => (
-        <button onClick={() => exportToCsv(apiRef.current.getAllRows(), columns, { filename: 'export' })}>
+        <button onClick={() => exportToCsv(apiRef.current.getAllFilteredRows(), apiRef.current.getVisibleColumns(), { fileName: 'export.csv' })}>
           Export CSV
         </button>
       ),
@@ -158,11 +167,11 @@ const apiRef = useGridApiRef();
 ```tsx
 slotProps={{
   toolbar: {
-    renderQuickFilter:       (props) => <MySearch {...props} />,
-    renderColumnsButton:     (props) => <MyColumnsBtn {...props} />,
-    renderFilterButton:      (props) => <MyFilterBtn {...props} />,
-    renderAggregationButton: (props) => <MyAggBtn {...props} />,
-    renderExportButton:      ()      => <MyExportBtn />,
+    renderQuickFilter:       (props: ToolbarQuickFilterRenderProps) => <MySearch {...props} />,
+    renderColumnsButton:     (props: ToolbarButtonRenderProps)      => <MyColumnsBtn {...props} />,
+    renderFilterButton:      (props: ToolbarButtonRenderProps)      => <MyFilterBtn {...props} />,
+    renderAggregationButton: (props: ToolbarButtonRenderProps)      => <MyAggBtn {...props} />,
+    renderExportButton:      ()                                     => <MyExportBtn />,
   },
 }}
 ```
@@ -190,7 +199,7 @@ slotProps={{
 
 When you provide a custom button, the toolbar renders your element as the trigger but keeps its own open/close state. The panel (Columns, Filters, or Aggregation) is positioned relative to the wrapper `<div>` surrounding your custom button, so placement is automatic — you don't need to pass any refs.
 
-Panel close behaviour is unchanged: Escape key closes, click-outside closes (except the Filter panel, which requires an explicit Close button to let users type without it dismissing).
+Panel close behaviour is unchanged: Escape closes every panel, and click-outside closes every panel except the Filter panel, which has an explicit Close button so users can type without it dismissing. However the Columns panel closes, `onColumnsPanelClose` is called.
 
 ---
 
@@ -201,5 +210,5 @@ These built-in features are unaffected regardless of which render props you prov
 - Column panel content (drag-to-reorder, show/hide toggles)
 - Filter panel content (operators, values, logic operator)
 - Aggregation panel content (per-column function pills)
-- Pivot panel (if `onPivotModelChange` is wired)
+- Pivot panel (when the Pivot button is shown, see above)
 - `children` / `rightContent` slot behaviour

package/docs/features/tree-data-grouping.md

@@ -12,14 +12,32 @@ Row grouping allows you to categorize rows based on common column values.
 ```tsx
 <DataGrid
   rows={rows}
+  columns={columns}
   rowGroupingModel={['department', 'role']}
 />
 ```
 
 ### Features
-- **Multi-Level Groups**: Nest data as deeply as needed.
+- **Multi-Level Groups**: Nest data as deeply as needed — one level per field in `rowGroupingModel`, in order.
 - **Aggregation Integration**: Summarize values automatically for each group level.
-- **Expansion Control**: Control which groups are expanded by default.
+- **Expansion Control**: `defaultGroupingExpansionDepth` sets how many levels start expanded (default `0`: all collapsed; `-1`: everything expanded).
+- **Aggregate placement**: `getAggregationPosition(node)` returns `'inline'` (on the group row, the default), `'footer'` (a subtotal row after the group's children while it is expanded) or `null` (hidden). It is also called once with `null` for the grand-total footer row; returning `null` there hides the footer.
+
+### Behaviour to know about
+
+- **Pagination is ignored** while `rowGroupingModel` is active. All groups render in one scrollable, virtualized view, so the grid needs a bounded height ([Virtualization](./virtualization.md#the-grid-needs-a-bounded-height)). A development-mode warning is logged if you pass `pagination` too.
+- **Expansion state survives data updates** (row grouping and tree data). Groups and nodes the user expanded or collapsed stay that way when `rows` changes: inline edits, live refreshes, new array identities, and lazily loaded server-side children. The state resets to `defaultGroupingExpansionDepth` only when `rowGroupingModel` or `defaultGroupingExpansionDepth` changes value.
+- **Group aggregation uses the same functions as the footer.** `sum`, `avg`, `count`, `min`, `max` and `unique` ignore `null`/`undefined`, so a group of `[10, null, 20]` gives `min` 10, `avg` 15 and `count` 2. `availableAggregationFunctions` on a column is honoured for group rows too.
+- **The expand toggle, indentation and group label sit in the leftmost column on screen**, after column order, visibility and pinning are applied — not in whichever column is first in `columns`. Hiding or moving that column no longer leaves group rows without a label or toggle (fixed in v3.0).
+- **Keyboard and screen readers** (v3.0): **Enter** on a non-editable cell of a group row or a tree-data parent expands or collapses it, and **Alt+ArrowRight** / **Alt+ArrowLeft** expand / collapse it. Rows expose `aria-level` (depth + 1), and rows with children expose `aria-expanded`. The expand buttons inside cells are not separate Tab stops. See [Keyboard & Accessibility](keyboard-navigation.md).
+- **`valueFormatter` applies to grouped rows** the same as flat rows (fixed in v2.1; earlier versions rendered raw values for every column once grouping was on).
+- **Group subtotals and the `(n)` count follow the filter.** They cover only the leaf rows that pass the current filter, and groups with no matching row are left out (v3.0; before, they counted hidden rows too). Groups keep their order of first appearance while filtering.
+- **Grouping values are compared by value, not by text**: `null` and `'null'`, `1` and `'1'`, `true` and `'true'` are separate groups; equal dates share one. A column with a `valueGetter` is grouped by the value it computes.
+- **`groupable: false`** fields are dropped from the model before grouping, so the other levels keep their depth, indentation, `defaultGroupingExpansionDepth` and export depth.
+- **Sorting the column that shows the group labels orders the groups by their grouping value**; sorting an aggregated column orders them by the aggregate.
+- **Group rows are synthetic.** They have no selection checkbox and no detail panel, their ids never appear in the selection model, clicking them toggles them (without `onRowClick`), and a column's `valueGetter` is not called for them. `renderCell` *is* called for them: see [GridRowMeta](../architecture/grid-row-meta.md#accessing-metadata-in-rendercell).
+- **Server modes**: with `filterMode="server"` / `sortingMode="server"` the grid does not filter or sort the rows again on the client, in row grouping and tree data as in a flat grid.
+- **Pass stable callbacks.** `rowGroupingModel` and `aggregationModel` are compared by value, so inline arrays and objects are fine, but a new `getTreeDataPath` or `columns` identity on every render rebuilds the whole hierarchy. Define them at module scope or memoize them.
 
 ---
 
@@ -29,15 +47,29 @@ Tree data is used for data that has a natural parent-child relationship (e.g., a
 
 ### Implementation
 1. Enable `treeData={true}`.
-2. Provide a `getTreeDataPath` function to define the hierarchy.
+2. Provide a `getTreeDataPath` function to define the hierarchy. It is required: without it the rows are shown flat. Define it at module scope or with `useCallback`.
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   treeData
-  getTreeDataPath={(row) => row.hierarchyPath} // e.g. ['CEO', 'VP Engineering', 'Manager']
+  getTreeDataPath={getPath} // e.g. (row) => row.hierarchyPath: ['CEO', 'VP Engineering', 'Manager']
 />
 ```
 
+### Behaviour to know about
+
+- **Path segments can contain any character**, including `/`: `['a/b']` and `['a', 'b']` are different paths.
+- **Missing parents are created for you.** A path segment with no row of its own gets a synthetic parent row (`rowMeta.isGroupRow`, label in `rowMeta.groupLabel`, row object `{ id }`) shown in the toggle column as `label (n)`, whatever that column is called. It is shown only when a row under it passes the filter, and sorting the toggle column orders it by its label.
+- **Parents that are your own rows behave like any row**: clicking one fires `onRowClick` and selects it; its chevron expands it. (Before v3.0 a click toggled it and never fired `onRowClick`.) From the keyboard it expands with Enter or Alt+ArrowRight (see below) and **Shift+Space** selects it.
+- **`descendantCount`** (the `(n)`) counts the rows below a node at any depth that pass the filter. A parent whose children are all filtered out is shown without a toggle.
+- **Invalid paths are reported in development**: a row whose path is empty is shown as a top-level row, rows sharing a path attach their children to the first of them, and `treeData` without `getTreeDataPath` shows the rows flat. Each logs a `console.warn`.
+- **Pagination** pages the flattened visible tree; keyboard navigation stays on the current page.
+- **Lazy (server) trees**: the children of an expanded node with `serverChildrenCount` are fetched when it is expanded, and fetched again after a server re-fetch (a sort or filter change) replaces the rows. `defaultGroupingExpansionDepth` counts such a node as expandable (v3.0+), so `-1` expands every lazy node and loads its children.
+- **`apiRef.getAllFilteredRows()` with a filter** returns the rows that match the filter, the same set select-all and the aggregation footer use. Ancestors shown only to give a match its context are not in it (v3.0+; before, they were).
+- **Row grouping with `paginationMode="server"`**: grouping turns pagination off, so a `dataSource` is asked for every row (see [Data Source](data-source.md#2-server-side-pagination)).
+
 ---
 
 ## ⚙️ API Reference
@@ -47,15 +79,18 @@ Tree data is used for data that has a natural parent-child relationship (e.g., a
 | :--- | :--- | :--- | :--- |
 | `rowGroupingModel` | `string[]` | `[]` | Fields to group by (in order). |
 | `treeData` | `boolean` | `false` | Enable tree data mode. |
-| `getTreeDataPath` | `(row) => string[]` | `undefined` | Function to get the path for a row. |
-| `defaultGroupingExpansionDepth` | `number` | `0` | How many levels to expand on load. |
-| `groupingColDef` | `GridColDef` | `undefined` | Custom configuration for the generated group column. |
+| `getTreeDataPath` | `(row) => string[]` | `undefined` | Path of a row. Required with `treeData`. |
+| `defaultGroupingExpansionDepth` | `number` | `0` | How many levels start expanded (`0` = collapsed, `-1` = all). |
+| `groupingColDef` | `Partial<GridColDef<R>>` | `undefined` | Adds a dedicated group column (row grouping or tree data). |
+| `getAggregationPosition` | `(node: GridTreeNode \| null) => 'inline' \| 'footer' \| null` | `undefined` | Where group aggregates appear; called with `null` for the grand total. |
+
+Hierarchy information is never written onto your row objects: read it from `params.rowMeta` (`isGroupRow`, `hasChildren`, `treeDepth`, `groupLabel`, …) in `renderCell`. See [GridRowMeta](../architecture/grid-row-meta.md).
 
 ---
 
 ## 🎨 Customizing the Group Column
 
-When `rowGroupingModel` is active, pass `groupingColDef` to configure a dedicated `__group__` column that is prepended at position 0 and auto-pinned left, separate from your data columns. It accepts any `GridColDef` fields except `field` (always `'__group__'`).
+When `rowGroupingModel` or `treeData` is active, pass `groupingColDef` to configure a dedicated `__group__` column that is prepended at position 0 and auto-pinned left, separate from your data columns. Its type is `Partial<GridColDef<R>>`: every key is optional, and a `field` you pass is ignored (it is always `'__group__'`). It also forces `hideable`, `sortable`, `filterable`, `pinnable` and `exportable` to `false`. Defaults: `headerName: 'Group'`, `width: 220`. With tree data (v3.0) the column shows the last segment of each row's path, and a `valueGetter` in `groupingColDef` can show something else (for example the whole path).
 
 ```tsx
 <DataGrid
@@ -69,7 +104,7 @@ When `rowGroupingModel` is active, pass `groupingColDef` to configure a dedicate
 />
 ```
 
-Without `groupingColDef`, the group toggle is overlaid on the first data column. With it, the group indicator always appears in its own fixed column regardless of your `columns` order.
+Without `groupingColDef`, the group toggle is overlaid on the leftmost column on screen. With it, the group indicator always appears in its own fixed column regardless of your `columns` order. A `renderCell` in `groupingColDef` renders the group rows' label cell (return `undefined` to keep the default label).
 
 ---
 

package/docs/features/virtualization.md

@@ -17,8 +17,8 @@ Virtualization is a technique that dramatically improves performance when workin
 The grid calculates which rows are visible based on:
 - Current scroll position
 - Viewport height
-- Row height (fixed or variable)
-- Overscan buffer (default: 5 rows)
+- Row height (the fixed `rowHeight`, plus the height of any expanded detail panels)
+- Overscan buffer (adaptive, minimum `overscanRowCount`, default 3 rows)
 
 ```tsx
 // Example: 1000 rows, but only ~15 rendered at a time
@@ -29,21 +29,69 @@ The grid calculates which rows are visible based on:
 />
 ```
 
-**Performance characteristics:**
+**Performance characteristics** (when the grid has a bounded height — see below):
 - ✅ Renders ~15-25 rows regardless of total dataset size
 - ✅ Constant memory usage
 - ✅ Smooth 60fps scrolling
-- ✅ Supports millions of rows
+- ⚠️ Not millions of rows. Browsers cap an element's height (33,554,432px in Chromium, about 17.9M px in Firefox) and the grid does no scroll scaling: it lays every row out at its real height, so rows past the cap cannot be scrolled to. The limit is roughly `33,554,432 / rowHeight` rows in Chromium (about 645,000 at the default 52px), and about half that in Firefox (about 340,000). Beyond that, use pagination, or server-side paging / infinite scroll. In development the grid warns when the content passes 17.8M px.
 
 ### Column Virtualization
 
-Currently, the DataGrid renders all columns. Column virtualization (rendering only visible columns) is planned for future releases.
+Unpinned columns are virtualized horizontally: only the columns in view plus 6 on each side are rendered, with spacer cells standing in for the rest. Pinned columns are always rendered.
+
+### Import the stylesheet
+
+Virtualization depends on the grid's CSS. Import it once in your app:
+
+```tsx
+import '@opencorestack/opengridx/styles';
+```
+
+Without the stylesheet the viewport does not scroll, so the grid renders every row. In development the grid logs a one-time `[OpenGridX] The grid stylesheet is not loaded` warning.
+
+### The grid needs a bounded height
+
+Virtualization renders as many rows as fit in the grid's viewport. If the grid's container has no bounded height, the viewport grows to fit **every** row, so every row is rendered. Nothing errors; the grid just stops virtualizing.
+
+The most common cause is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
+
+```tsx
+// ❌ Grows to fit all rows — virtualization is effectively off
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <div style={{ flex: 1 }}>
+    <DataGrid rows={rows} columns={columns} height="100%" />
+  </div>
+</div>
+
+// ✅ Bounded — only visible rows render
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <div style={{ flex: 1, minHeight: 0 }}>
+    <DataGrid rows={rows} columns={columns} height="100%" />
+  </div>
+</div>
+```
+
+`height="100%"` only helps if every ancestor up to a fixed-height element also has a definite height.
+
+**`DataGridThemeProvider` counts as an ancestor.** It renders a plain `<div class="ogx-theme-provider">` around the grid, and that wrapper is auto-height like any other `div`. When you use `height="100%"` inside it, give the wrapper a height as well:
+
+```tsx
+<div style={{ flex: 1, minHeight: 0 }}>
+  <DataGridThemeProvider theme={theme} style={{ height: '100%' }}>
+    <DataGrid rows={rows} columns={columns} height="100%" />
+  </DataGridThemeProvider>
+</div>
+```
+
+In development builds the grid logs a `console.warn` when it detects that it is rendering every row of a dataset larger than 200 rows because its viewport is unbounded.
+
+Pagination can hide this problem, because a paginated grid only has one page of rows to render. Row grouping switches pagination off (see below), so an unbounded container that looked fine with pagination can freeze the tab once grouping is enabled.
 
 ## Configuration
 
 ### Row Height
 
-The grid supports both fixed and variable row heights:
+Every data row has the same height. There is no per-row height callback; the only rows of a different height are expanded detail panels (see below).
 
 ```tsx
 // Fixed row height (default: 52px)
@@ -157,7 +205,7 @@ When using detail panels, row heights become variable. The grid automatically:
 
 ## Virtualization with Grouping/Tree Data
 
-Row grouping and tree data work seamlessly with virtualization:
+Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium by `DataGrid.virtualization.browser.test.tsx`).
 
 ```tsx
 // Tree data with virtualization
@@ -170,7 +218,7 @@ Row grouping and tree data work seamlessly with virtualization:
 />
 ```
 
-**Note:** When groups are collapsed, only visible rows are rendered. Expanding a group dynamically adds rows to the render list.
+**Note:** `pagination` is ignored while `rowGroupingModel` is active, so a grouped grid relies entirely on virtualization to bound what it renders. Make sure its container has a bounded height. A development-mode warning is logged if `pagination` is passed together with `rowGroupingModel`.
 
 ## Debugging Virtualization
 
@@ -192,13 +240,14 @@ You should see console logs only for visible rows + overscan buffer.
 
 ## Known Limitations
 
-1. **Column virtualization** - Not yet implemented (all columns are rendered)
-2. **Dynamic row heights** - Requires full dataset scan for accurate scroll calculations
-3. **Horizontal scrolling** - May show brief flicker with very wide grids
+1. **Unbounded containers** - Virtualization needs a bounded viewport height (see above)
+2. **Browser height cap** - Rows past roughly `33,554,432 / rowHeight` (Chromium; less in Firefox) cannot be scrolled to (see above)
+3. **Uniform row heights** - Only detail panels vary the height; cumulative heights are recomputed over all rows when panels change
+4. **Horizontal scrolling** - May show brief flicker with very wide grids
 
 ## Future Improvements
 
-- [ ] Column virtualization for grids with 50+ columns
+- [x] Column virtualization (unpinned columns, 6-column overscan)
 - [x] Adaptive overscan based on scroll velocity (`overscanRowCount` prop, v2.0.4)
 - [ ] Virtual scrollbar for extremely large datasets (millions of rows)
 - [ ] Intersection Observer API for better scroll detection
@@ -208,10 +257,10 @@ You should see console logs only for visible rows + overscan buffer.
 | Feature | OpenGridX | MUI X DataGrid |
 |---------|--------------|----------------|
 | Row virtualization | ✅ Yes | ✅ Yes |
-| Column virtualization | ❌ Planned | ✅ Yes (Pro) |
-| Variable row heights | ✅ Yes | ✅ Yes |
+| Column virtualization | ✅ Yes (unpinned columns) | ✅ Yes (Pro) |
+| Variable row heights | Detail panels only | ✅ Yes |
 | Overscan buffer | 3–30 rows (adaptive, velocity-based) | 3-8 rows (adaptive) |
-| Max recommended rows | 100,000+ | 100,000+ |
+| Max scrollable rows | ~645,000 at 52px in Chromium (browser height cap) | — |
 
 ## Related Documentation