@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/README.md

@@ -43,6 +43,7 @@ In-depth guides on the grid's functional capabilities.
 - **[Tree Data & Grouping](features/tree-data-grouping.md)** - Hierarchical layout and Column grouping
 - **[Cell Spanning](features/cell-spanning.md)** - Row and Col span spanning
 - **[Master-Detail](features/master-detail.md)** - Expandable Detail Panels
+- **[Keyboard & Accessibility](features/keyboard-navigation.md)** - Keys, focus behaviour and ARIA structure
 - **[List View](features/list-view.md)** - Card-based responsive layout
 - **[Infinite Scroll](features/infinite-scroll.md)** - Advanced performance loading
 - **[Data Source](features/data-source.md)** - Server-side fetching and SSR
@@ -61,6 +62,7 @@ Make the grid your own.
 ## 🏛️ Architecture — Internal Hooks
 Reference for core hooks extracted from `DataGrid.tsx`. Intended for contributors.
 
+- **[DataGrid orchestration](architecture/datagrid-orchestration.md)** - Every hook `DataGrid.tsx` calls, in call order, and why the order matters
 - **[useGridControlledState](architecture/use-grid-controlled-state.md)** - Controlled/uncontrolled state for all 7 state pairs
 - **[useGridRowPipeline](architecture/use-grid-row-pipeline.md)** - Filter → pin → sort → paginate row pipeline
 - **[useGridVirtualization](architecture/use-grid-virtualization.md)** - Render context and scroll-position math
@@ -69,6 +71,9 @@ Reference for core hooks extracted from `DataGrid.tsx`. Intended for contributor
 - **[useGridScrollSync](architecture/use-grid-scroll-sync.md)** - RAF-batched scroll tick, scrollPosRef, onRowsScrollEnd threshold
 - **[useGridStateSnapshot](architecture/use-grid-state-snapshot.md)** - onStateChange callback delivery on sort/filter/pagination/column changes
 
+## 🔀 Migration Guides
+- **[v2 → v3](migration/v2-to-v3.md)** - Underscore row fields removed, `params.row` identity, grouped export labels
+- **[v1 → v2](migration/v1-to-v2.md)** - Removed dead props, `groupable` / `availableAggregationFunctions` enforcement
+
 ## 🛠️ Project Meta
 - **[Development Roadmap](roadmap.md)** - What's built and what's next
-- **[Research Notes](research/FEATURE_CATALOG.md)** - Comparative analysis and design decisions

package/docs/architecture/datagrid-orchestration.md

@@ -0,0 +1,81 @@
+# DataGrid orchestration
+
+`lib/components/DataGrid/DataGrid.tsx` is the orchestration layer: it destructures the props, calls
+hooks and pure utils in a fixed order, and renders JSX. Feature logic lives in the hooks and utils
+listed here; add new logic there, not in the component.
+
+## Why the order matters
+
+Effects run in the order their hooks are called (within the same phase: layout effects first, then
+passive effects). Several hooks install methods on `apiRef` or read state that an earlier hook wrote
+in an effect, so **keep the call order when you move or add a hook**. In particular:
+
+- `useGridApiRefBinding` points the consumer's `apiRef` at the live API in a layout effect, before any
+  parent layout effect runs.
+- `useGridApiMethods` (layout effects) installs the state methods before `useGridAggregationApi`,
+  `useGridClipboardApi` and `useGridScrollToIndexesApi` install theirs. `useGridApiMethods`,
+  `useGridAggregationApi` and `useGridScrollToIndexesApi` install once per `apiRef` in a layout
+  effect and read the latest values from a ref refreshed in a layout effect, so the methods are
+  live in a parent's layout effect and never answer from a previous render.
+- `useGridLiveRowSelection` prunes the selection, and `useGridPageCorrection` corrects a page past the
+  end, in effects that run before the later hooks' effects.
+
+## Call order
+
+| # | Hook / util | File | Produces |
+| :- | :--- | :--- | :--- |
+| 0 | `useStableColumns` | `hooks/core/useStableColumns.ts` | The `columns` prop with a stable identity while every column is shallowly equal (inline columns do not re-run the row passes) |
+| 1 | `useGridControlledState` | `hooks/core/useGridControlledState.ts` | Controlled/uncontrolled sort, filter, aggregation, visibility, pinning, pivot, pagination, selection, density |
+| 2 | `useGridPivot` | `hooks/features/useGridPivot.ts` | Pivot rows/columns (or the source ones) and the pipeline filter/sort models |
+| 3 | `resolveGridModes` (pure) | `utils/gridModes.ts` | Which features are in effect: tree data, row grouping, pagination, row reordering, list view, grouping column |
+| 4 | `useGridThemeDimensions` | `hooks/core/useGridThemeDimensions.ts` | Row and header heights (props → theme provider → defaults) |
+| 5 | `useGridGroupingColumn` | `hooks/core/useGridGroupingColumn.ts` | `activeColumns` with the `__group__` column, and its auto-pin |
+| 6 | `useGridColumnLookup` | `hooks/core/useGridColumnLookup.ts` | Column lookup for filtering/sorting |
+| 7 | `useServerAggregationResults` | `hooks/features/useAggregation.ts` | Server-provided totals |
+| 8 | `useGridKeyboardMode` | `hooks/core/useGridFocusHandlers.ts` | `setKeyboardMode` (toggles `ogx--kb` on the root) |
+| 9 | `useDataGrid` | `hooks/core/useDataGrid.ts` | Row store, dimensions, data-source state, the live `apiRef` |
+| 10 | `useGridRowIdOf` | `hooks/core/useGridRowIdOf.ts` | `getRowIdOf` and its stable event-handler twin |
+| 11 | `useGridApiRefBinding` | `hooks/core/useGridApiRefBinding.ts` | Binds the `apiRef` prop (layout effect) |
+| 12 | `useGridHierarchy` | `hooks/core/useGridHierarchy.ts` | `useTreeData` + `useRowGrouping`, the active handlers and `rowMetaMap` |
+| 13 | `useGridEditing` | `hooks/features/useGridEditing.ts` | Cell editing state and handlers |
+| 14 | `useGridLiveRowSelection` | `hooks/core/useGridLiveRowSelection.ts` | Selection without removed rows |
+| 15 | `useGridDataSource` | `hooks/features/useGridDataSource.ts` | Server fetching |
+| 16 | `useServerTreeChildren` | `hooks/features/useServerTreeChildren.ts` | Lazy server tree children |
+| 17 | `useGridDetailPanel` | `hooks/core/useGridDetailPanel.ts` | Detail-panel expansion, toggle, measured heights |
+| 18 | `useGridColumns` | `hooks/core/useGridColumns.tsx` | Effective/ordered/visible columns, widths, reorder |
+| 19 | `useGridStateSnapshot` | `hooks/core/useGridStateSnapshot.ts` | `onStateChange` delivery |
+| 20 | `useGridRowPipeline` | `hooks/core/useGridRowPipeline.ts` | Filter → pin → sort → paginate |
+| 21 | `useGridPageCorrection` | `hooks/core/useGridPageCorrection.ts` | Moves a page left past the end back to the last page |
+| 22 | `getPaginationRowCount` (pure) | `utils/pagination/index.ts` | What the pager pages through |
+| 23 | `useGridRowInteractions` | `hooks/core/useGridRowInteractions.ts` | Row selection, `handleRowClick`, `handleSelectionChange` |
+| 24 | `useGridApiMethods` | `hooks/core/useGridApiMethods.ts` | State API methods (`getAllFilteredRows` via `utils/gridApiRows.ts`) |
+| 25 | `useRowReorder` | `hooks/useRowReorder.ts` | Row drag-reorder |
+| 26 | `useAggregation` | `hooks/features/useAggregation.ts` | Footer aggregation result |
+| 27 | `useGridAggregationApi` | `hooks/core/useGridAggregationApi.ts` | `getAggregationResult`, `getAggregationModel`, `getGroupedExportRows` |
+| 28 | `useLayout` | `hooks/core/useLayout.ts` | Row heights, pinned column split, widths |
+| 29 | `useGridSpanning` | `hooks/features/useGridSpanning.ts` | Row/column spans |
+| 30 | `useGridClipboardApi` | `hooks/core/useGridClipboardApi.ts` | Ctrl/Cmd+C and `copySelectedRows` |
+| 31 | `useGridScrollToIndexesApi` | `hooks/core/useGridScrollToIndexesApi.ts` | `scrollToIndexes` |
+| 32 | `useGridViewport` | `hooks/core/useGridViewport.ts` | Scroll sync, viewport measurement, viewport callback ref |
+| 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window |
+| 34 | `useGridSortHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Header sort / shift-sort |
+| 35 | `useGridKeyboardNavigation` | `hooks/core/useGridKeyboardNavigation.ts` | Focus and keyboard handling |
+| 36 | `useGridPointerFocusHandlers` | `hooks/core/useGridFocusHandlers.ts` | Cell and header click focus |
+| 37 | `useGridColumnMenuHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Column menu Hide / Pin (`pinColumnTo` in `utils/pinning`) |
+| 38 | `useGridAriaRows` | `hooks/core/useGridAriaRows.ts` | `aria-rowcount` and `aria-rowindex` bases |
+| 39 | `useGridSpanRowWindow` | `hooks/features/useGridSpanRenderWindow.ts` | Render window widened to whole row spans |
+| 40 | `useGridVisibleRows` | `hooks/core/useGridVisibleRows.ts` | Pinned + virtual centre rows to render |
+| 41 | `useGridSpanColumnWindow` | `hooks/features/useGridSpanRenderWindow.ts` | Columns to render, widened to whole column spans |
+| 42 | `useGridDevWarnings` | `hooks/core/useGridDevWarnings.ts` | Dev-only warnings |
+| 43 | `useColumnGroupReorderGuard` | `hooks/features/useColumnGroupReorderGuard.ts` | Header drag-reorder kept inside column groups |
+| 44 | `useGridColumnsPanel` | `hooks/core/useGridColumnsPanel.ts` | Columns panel (toolbar or standalone) |
+| 45 | `useGridStylesheetWarning` | `hooks/core/useGridDevWarnings.ts` | Warns when the stylesheet is missing |
+| 46 | `useGridToolbarProps` | `hooks/core/useGridToolbarProps.ts` | Props for `slots.toolbar` |
+
+## Rendered components
+
+`GridToolbarSlot`, `GridStandaloneColumnPanel`, `GridListView` (list view) or the viewport
+(`Header`, `GridPinnedRows` top, `GridEmptyState`, `GridVirtualRows`, `GridPinnedRows` bottom,
+`GridAggregationFooter`), then `slots.footer` or `GridPaginationArea`, `GridLiveRegion`,
+`GridLoadingOverlay` and `GridErrorOverlay`. The props all three row renderers take alike are built
+once in `DataGrid.tsx` (`rowRenderProps`) and spread into each.

package/docs/architecture/grid-row-meta.md

@@ -0,0 +1,102 @@
+# `GridRowMeta`
+
+Hierarchy metadata for a grid row, available via `params.rowMeta` in `renderCell` since v1.1.
+
+**File:** `lib/types/index.ts`
+
+---
+
+## Why it exists
+
+Before v1.1, `useTreeData` and `useRowGrouping` injected internal fields (`_hasChildren`, `_treeDepth`, etc.) directly onto each row object and declared them on `GridRowModel`. This caused two problems:
+
+1. **Collision risk** — a user dataset with a field called `_hasChildren` would be silently corrupted.
+2. **API leakage** — implementation details appeared as typed public API, inviting users to depend on them.
+
+`GridRowMeta` moves these fields to a separate `Map<GridRowId, GridRowMeta>` that never touches the user's data.
+
+---
+
+## Interface
+
+```ts
+export interface GridRowMeta {
+  hasChildren?: boolean;
+  treeDepth?: number;
+  groupingField?: string;
+  groupingValue?: unknown;
+  groupLabel?: string;
+  descendantCount?: number;
+  isExpanded?: boolean;
+  isGroupRow?: boolean;
+  isGroupFooter?: boolean; // v3.0
+}
+```
+
+| Field | Meaning |
+| :--- | :--- |
+| `hasChildren` | The row has children to show under the active filter, so the expand toggle is rendered. A lazy tree node whose children are not loaded yet (`serverChildrenCount > 0`) counts as having children. |
+| `descendantCount` | Data rows below the row, at any depth, that pass the filter: row-grouping leaves, or tree-data rows (auto-created tree parents are not counted). `undefined` for a lazy node whose children are not loaded. It is the `(n)` next to group labels. |
+| `groupLabel` | The label shown for a synthetic row: the group label (`groupingValueFormatter` or `"field: value"`), or the path segment of an auto-created tree parent. |
+| `isGroupRow` | The row is synthetic: a row-grouping group row, a group subtotal row, or a tree-data parent created for a path segment that has no row of its own (its row object is just `{ id }`). Synthetic rows are never selected, edited or given a detail panel, clicking one toggles it, and `valueGetter` is not called for them. Tree-data parents that are your own rows have `isGroupRow: false`. |
+| `isGroupFooter` | The row is the subtotal row of a group, shown after its children when `getAggregationPosition` returns `'footer'`. |
+
+---
+
+## Data flow
+
+```
+useTreeData / useRowGrouping
+  └─ returns rowMetaMap: Map<GridRowId, GridRowMeta>
+
+useGridHierarchy (called by DataGrid.tsx)
+  └─ selects the active map (tree data XOR row grouping XOR empty)
+  └─ uses rowMetaMap in:
+       ├─ handleRowClick / selection / editing (skip or toggle synthetic rows)
+       └─ GridVirtualRows / GridPinnedRows / GridListView
+            (resolve meta per row: rowMetaMap.get(id), id = getRowId(row))
+            └─ Row (rowMeta prop)
+                 └─ Cell (passes rowMeta into GridRenderCellParams)
+                      └─ renderCell, including the hierarchy renderers useGridColumns injects (read params.rowMeta)
+```
+
+---
+
+## Accessing metadata in `renderCell`
+
+```tsx
+renderCell: (params) => {
+  // params.rowMeta is undefined for flat rows
+  if (params.rowMeta?.hasChildren) {
+    return <strong>{params.formattedValue} ({params.rowMeta.descendantCount})</strong>;
+  }
+  return params.formattedValue;
+}
+```
+
+Since v3.0 `renderCell` is called for every row, including synthetic group, subtotal and auto-created tree-parent rows, in every column, and its output is shown. In the column that holds the expand toggle, the output replaces the default group label next to the toggle. **Returning `undefined` for a synthetic row keeps the grid's default content** (the group label and count in the toggle column, the aggregate or nothing elsewhere), so a renderCell written for data rows can opt out in one line:
+
+```tsx
+renderCell: (params) => (params.rowMeta?.isGroupRow ? undefined : <Avatar user={params.row.user} />)
+```
+
+A renderCell that throws on a synthetic row shows the `⚠` cell indicator; in the toggle column the toggle stays usable.
+
+---
+
+## Runtime shim (removed in v3.0)
+
+From v1.1 to v2.x, `useTreeData` and `useRowGrouping` still copied each row and injected the underscore fields (`_hasChildren`, `_treeDepth`, `_isExpanded`, `_groupingField`, `_groupingValue`, `_descendantCount`, `_isGroupRow`) onto the copy for backward compatibility. (An earlier revision of this doc wrongly said the injection was removed in v2.0.)
+
+**Since v3.0 nothing is injected.** Both hooks pass the consumer's row objects through unchanged and all hierarchy information lives in `rowMetaMap` / `params.rowMeta`. `params.row` under grouping is therefore the same object the consumer passed in `rows`, just as it is without grouping. See [Migrating from v2 to v3](../migration/v2-to-v3.md).
+
+---
+
+## Non-hierarchy rows
+
+`params.rowMeta` is `undefined` when no tree-data or row-grouping is active. While a hierarchy is active, **every** row rendered in it has an entry, data rows included:
+
+- Row grouping: a leaf (data) row has `{ hasChildren: false, treeDepth, isGroupRow: false }`; group rows add `groupingField`, `groupingValue`, `groupLabel`, `descendantCount` and `isExpanded`; subtotal rows are like their group row with `isGroupFooter: true`, `hasChildren: false` and `treeDepth + 1`.
+- Tree data: every node has `hasChildren`, `treeDepth`, `descendantCount`, `isGroupRow` and `isExpanded`; auto-created parents also have `groupLabel`.
+
+Still guard with optional chaining (`params.rowMeta?.hasChildren`) so the same `renderCell` works with and without a hierarchy.

package/docs/architecture/use-grid-columns.md

@@ -0,0 +1,128 @@
+# `useGridColumns`
+
+Internal hook. Manages the full column lifecycle: injects hierarchy cell renderers, maintains column widths and order state, derives ordered/visible column lists, and computes the navigation column array used by keyboard navigation and spanning.
+
+**File:** `lib/hooks/core/useGridColumns.tsx` (`.tsx` — contains JSX for hierarchy cell renderers)
+
+---
+
+## Purpose
+
+Before extraction, ~195 lines of column management lived inline in `DataGrid.tsx`. Pulling them out gives this logic its own test surface and removes hierarchy rendering concerns from the main component.
+
+The injected hierarchy renderers read hierarchy metadata from `params.rowMeta` (the `GridRowMeta` entry from `rowMetaMap`), never from the row object: rows are the consumer's own objects and carry no `_treeDepth` / `_hasChildren` fields (removed in v3.0). See [GridRowMeta](grid-row-meta.md).
+
+---
+
+## Parameters
+
+```ts
+interface UseGridColumnsParams<R extends GridRowModel> {
+    activeColumns: GridColDef<R>[];           // pivot-resolved column list
+    isHierarchyEnabled: boolean;              // true when treeData OR rowGrouping active
+    isRowGrouping: boolean;
+    isTreeData: boolean;
+    activeHierarchyHandlers: { toggleExpansion: (id: GridRowId) => void } | null;
+    columnVisibilityModel: Record<string, boolean>;
+    columnOrder?: string[];                   // controlled; undefined = uncontrolled
+    onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void;
+    onColumnOrderModelChange?: (columnOrder: string[]) => void;  // whole new order; not in pivot mode
+    disableColumnReorder: boolean;
+    pivotMode: boolean;                       // pivot is active (DataGrid passes useGridPivot's isActive)
+    checkboxSelection: boolean;
+    hasDetailPanel: boolean;
+    rowReordering: boolean;
+    initialState?: GridInitialState;
+    setColumns: (cols: GridColDef[]) => void; // state store updater from useDataGrid
+    pinnedColumns?: GridColumnPinning;
+    getRowId?: (row: R) => GridRowId;         // id passed to toggleExpansion; defaults to row.id
+    aggregationModel?: GridAggregationModel;  // formats aggregates on row-grouping group rows
+    groupingRows?: ReadonlyMap<GridRowId, unknown>; // row grouping's synthetic group rows, by id
+}
+```
+
+> **`hasDetailPanel` is resolved before the hook call** — it depends only on `getDetailPanelContent` (a prop): `useGridDetailPanel`, called just before `useGridColumns` in `DataGrid.tsx`, returns it as `Boolean(getDetailPanelContent)`.
+
+---
+
+## Returns
+
+```ts
+interface UseGridColumnsResult<R extends GridRowModel> {
+    effectiveColumns: GridColDef<R>[];   // hierarchy renderers injected
+    hierarchyField: string | undefined;  // the column that gets the expand toggle / indent / group label
+    orderedColumns: GridColDef<R>[];     // sorted by effectiveColumnOrder
+    visibleOrderedColumns: GridColDef<R>[];  // filtered by columnVisibilityModel
+    navigationColumns: Array<GridColDef<R> | { field: string; sortable: false; editable: false }>;  // system + visible data cols
+    columnIndexMap: Map<string, number>; // visible data column field -> public colIndex
+    columnWidths: Record<string, number>;
+    effectiveColumnOrder: string[];
+    setInternalColumnOrder: React.Dispatch<...>;
+    columnReorderHandlers: ReturnType<typeof useColumnReorder>;  // header drag
+    moveColumn: (fromField: string, toField: string) => void;    // Columns panel drag
+    resetColumnOrder: () => void;                                // Columns panel Reset
+    handleColumnResize: (field: string, newWidth: number) => void;
+}
+```
+
+---
+
+## `effectiveColumns` — hierarchy renderer injection
+
+When `isHierarchyEnabled` is `false`, `effectiveColumns` is `activeColumns` unchanged.
+
+When `true`, the **hierarchy column** (`hierarchyField`) is the leftmost column actually on screen: the first visible column in render order (left-pinned in `pinnedColumns.left` order, then unpinned in column order, then right-pinned). Hiding, reordering or pinning columns therefore moves the toggle instead of dropping it. That column gets a `renderCell` override that:
+1. Reads `params.rowMeta` (`treeDepth`, `hasChildren`, `isExpanded`, `isGroupRow`, `groupLabel`, `descendantCount`, …)
+2. Renders indented padding (`treeDepth * 24px`)
+3. Shows an `<ExpandIcon>` if the row has children; clicking it calls `toggleExpansion(getRowId(row))`
+4. Renders the content next to it: the consumer's `renderCell` output if the column has one (isolated in its own `CellErrorBoundary`, so a throw keeps the toggle), otherwise the default — `params.formattedValue` for data rows, the group label plus `(count)` for row-grouping group rows and tree-data parents, nothing for subtotal (group footer) rows. For a synthetic row, a consumer `renderCell` returning `undefined` falls back to the default.
+
+All other columns get a `renderCell` wrapper. Data rows use the column's own `renderCell` or `params.formattedValue`. On synthetic group rows the consumer's `renderCell` decides (`undefined` keeps the default); by default the grouping-field column is empty (the label already shows the value) and other columns show their value (the aggregate) or nothing.
+
+Under row grouping, a column with an `aggregationModel` entry also gets `valueGetter` / `valueFormatter` wrappers for group rows (identified through `groupingRows`): the cell shows the aggregate stored on the group row (a `valueGetter` would recompute it from fields a group row does not have), formatted with `formatAggregateForColumn`, the formatter the footer, pivot cells and exports use (so `count` / `unique` are never put in the column's currency or unit format). Leaf rows keep the column's own getter and formatter.
+
+---
+
+## Column order
+
+- **Uncontrolled:** the order is the columns' own order until the user reorders (`setInternalColumnOrder`); it is derived, not snapshotted at mount, so it stays right when the columns change or the grid mounts in pivot mode.
+- **Controlled:** `columnOrder` wins, except in pivot mode.
+- **Every move works on the full current order**, `orderedColumns.map(c => c.field)`: all current columns, including those added after mount, those missing from a stored or controlled order, and the synthetic `__group__` column. The header drag (`columnReorderHandlers`), `moveColumn` and `resetColumnOrder` all go through one commit step: it stores the new order (uncontrolled or pivot), fires `onColumnOrderChange` with indices in that full order (not for Reset), and fires `onColumnOrderModelChange` with the whole order (not in pivot mode). Before v3.0 the indices came from `orderedColumns` but were applied to `effectiveColumnOrder`, so a column added after the order was stored, or a partial controlled order, made a drag move the wrong column or nothing.
+- **Pivot mode:** the generated pivot columns keep an order of their own, reset whenever the generated column set changes. Pivoting never rewrites the normal order, a controlled `columnOrder` (which names source columns) does not apply, and reordering updates the pivot order. `setInternalColumnOrder` writes to the order that is active.
+
+## Visibility
+
+`visibleOrderedColumns` drops columns hidden by `columnVisibilityModel`, except, in pivot mode, the pivot row-label columns (marked `hideable: false`): they share their field with the source column, which the visibility model may hide in normal mode, and the pivot rows are labelled by them.
+
+---
+
+## `navigationColumns` and `columnIndexMap`
+
+`navigationColumns` is what Row and Header render, in render order: system column stubs, then the visible data columns sorted left-pinned, unpinned, right-pinned (the same order `useLayout` renders them in):
+
+```
+[{ field: '__reorder_col__', sortable: false, editable: false }]   (if rowReordering)
+[{ field: '__expand_col__', sortable: false, editable: false }]    (if hasDetailPanel)
+[{ field: '__checkbox_col__', sortable: false, editable: false }]  (if checkboxSelection)
+...visibleOrderedColumns in pinned render order
+```
+
+Hidden columns are not in it, so arrow keys never land on a column that is not rendered (v3.0; it used to be built from `orderedColumns`, in unpinned order). Its length is the grid's `aria-colcount`.
+
+`columnIndexMap` maps each visible data column's field to its position in that render order, system columns excluded. Row, Cell and Header use it for the public `colIndex` (`GridCellParams`, `renderCell`, `renderHeader`) and for `aria-colindex` (`colIndex + 1 +` the number of system columns), so both are absolute and do not depend on the horizontal render window.
+
+`navigationColumns` is consumed by `useGridKeyboardNavigation` (to map arrow-key movements across all focusable columns). `useGridSpanning` does not use it: spans are computed over the rendered data columns only (the layout's left-pinned, unpinned and right-pinned columns), so system columns and hidden columns are never part of a span.
+
+---
+
+## Relationship to DataGrid
+
+DataGrid calls this hook after computing `isHierarchyEnabled`, `activeHierarchyHandlers`, and hoisting `hasDetailPanel`. The hook's return values are destructured directly into the variables the JSX return and downstream hooks expect.
+
+---
+
+## 🔗 Related
+- [useGridRowPipeline](use-grid-row-pipeline.md)
+- [useGridVirtualization](use-grid-virtualization.md)
+- [useGridVisibleRows](use-grid-visible-rows.md)
+- [DataGrid](../components/datagrid.md)

package/docs/architecture/use-grid-controlled-state.md

@@ -0,0 +1,157 @@
+# `useGridControlledState`
+
+Internal hook. Centralises the controlled/uncontrolled state pattern for every piece of DataGrid state that can be driven externally via props.
+
+**File:** `lib/hooks/core/useGridControlledState.ts`
+
+---
+
+## Purpose
+
+Eight DataGrid state pairs follow the same pattern:
+
+```
+[internal, setInternal] = useState(defaultValue)
+isControlled = prop !== undefined
+effective = isControlled ? prop : internal
+```
+
+Before this hook existed, those 85 lines lived inline in `DataGrid.tsx`. `useGridControlledState` extracts them into a single location so the controlled/uncontrolled contract is tested and reasoned about in one place.
+
+---
+
+## Managed state pairs
+
+| State | Prop (controlled) | Change callback |
+| :--- | :--- | :--- |
+| Sort | `sortModel` | `onSortModelChange` |
+| Filter | `filterModel` | `onFilterModelChange` |
+| Aggregation | `aggregationModel` | `onAggregationModelChange` |
+| Column visibility | `columnVisibilityModel` | `onColumnVisibilityModelChange` |
+| Pinned columns | `pinnedColumns` | `onPinnedColumnsChange` |
+| Pivot | `pivotModel` | `onPivotModelChange` |
+| Pagination | `paginationModel` | `onPaginationModelChange` |
+| Row selection | `rowSelectionModel` | `onRowSelectionModelChange` |
+
+It also resolves `density` (the `density` prop, else `initialState.density`, else `'standard'`).
+
+This hook is the single source of truth for these models. The `useDataGrid` reducer holds only
+the row store, dimensions and dataSource status (it used to keep its own sort, filter, pagination
+and selection copies, which drifted from what the grid rendered and made `apiRef` setters no-ops).
+Everything that reads or changes these models — the header, toolbar, pager, row checkboxes and
+the imperative API (`useGridApiMethods`) — goes through the values and `handle*Change` callbacks
+returned here.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridControlledStateParams {
+    initialState?: GridInitialState;
+
+    sortModel?: GridSortItem[];
+    onSortModelChange?: (model: GridSortItem[]) => void;
+
+    filterModel?: GridFilterModel;
+    onFilterModelChange?: (model: GridFilterModel) => void;
+
+    aggregationModel?: GridAggregationModel;
+    onAggregationModelChange?: (model: GridAggregationModel) => void;
+
+    columnVisibilityModel?: Record<string, boolean>;
+    onColumnVisibilityModelChange?: (model: Record<string, boolean>) => void;
+
+    pinnedColumns?: GridColumnPinning;
+    onPinnedColumnsChange?: (model: GridColumnPinning) => void;
+
+    pivotModel?: GridPivotModel;
+    onPivotModelChange?: (model: GridPivotModel) => void;
+
+    paginationModel?: GridPaginationModel;
+    onPaginationModelChange?: (model: GridPaginationModel) => void;
+    pageSizeOptions?: number[];   // picks the uncontrolled default page size
+
+    rowSelectionModel?: GridRowId[];
+    onRowSelectionModelChange?: (model: GridRowId[]) => void;
+
+    density?: 'compact' | 'standard' | 'comfortable';
+}
+```
+
+---
+
+## Returns
+
+```ts
+interface UseGridControlledStateReturn {
+    // Sort
+    sortModel: GridSortItem[];
+    isSortControlled: boolean;
+    setInternalSortModel: React.Dispatch<React.SetStateAction<GridSortItem[]>>;
+    handleSortModelChange: (model: GridSortItem[]) => void;
+
+    // Filter (seeded from initialState.filter.filterModel)
+    filterModel: GridFilterModel;
+    isFilterControlled: boolean;
+    handleFilterModelChange: (model: GridFilterModel) => void;
+
+    // Aggregation
+    aggregationModel: GridAggregationModel;
+    handleAggregationModelChange: (model: GridAggregationModel) => void;
+
+    // Column visibility
+    columnVisibilityModel: Record<string, boolean>;
+    handleColumnVisibilityModelChange: (model: Record<string, boolean>) => void;
+
+    // Pinned columns
+    pinnedColumns: GridColumnPinning;
+    handlePinnedColumnsChange: (model: GridColumnPinning) => void;
+
+    // Pivot
+    currentPivotModel: GridPivotModel;
+    handlePivotModelChange: (model: GridPivotModel) => void;
+
+    // Pagination
+    effectivePaginationModel: GridPaginationModel;
+    handlePaginationModelChange: (model: GridPaginationModel) => void;
+
+    // Row selection
+    rowSelectionModel: GridRowId[];
+    selectedRowIds: Set<GridRowId>;         // derived Set for O(1) lookup
+    isSelectionControlled: boolean;
+    setInternalRowSelectionModel: React.Dispatch<React.SetStateAction<GridRowId[]>>;
+    handleRowSelectionModelChange: (model: GridRowId[]) => void;
+
+    // Density
+    density: 'compact' | 'standard' | 'comfortable';
+}
+```
+
+---
+
+## Key behaviours
+
+**Controlled mode:** When a prop is provided (`prop !== undefined`), the effective value is always `prop`. The internal state is not updated — the caller is responsible for updating the prop via the change callback.
+
+**Uncontrolled mode:** When a prop is `undefined`, the effective value is the internal state. The `handle*Change` callback updates internal state and also fires the external callback (if provided) for observability.
+
+**Selection:** `handleRowSelectionModelChange` applies a new model like the other handlers. The row-click, checkbox, Space-key and select-all rules (including `disableMultipleRowSelection`) live in `useGridRowSelection`, which calls it. `getPendingRowSelectionModel()` (stable identity) returns the model most recently passed to `handleRowSelectionModelChange` that has not rendered yet, or `null`; it is cleared on every commit (a controlled parent may reject a change). `useGridApiMethods` prefers it over the rendered (pruned) selection, so `apiRef.getSelectedRows()` and `copySelectedRows()` are current inside `onRowSelectionModelChange` and right after `apiRef.selectRows`.
+
+**Default page size:** without `paginationModel` or `initialState.pagination`, the page size is 100 when `pageSizeOptions` offers it, otherwise the first option, so the page-size select always shows the size in use.
+
+**`aggregationModel` identity follows content:** an inline `aggregationModel={{ salary: 'sum' }}` is a new object on every parent render. The returned `aggregationModel` keeps its identity while its content is unchanged (it is keyed on its JSON), so the server fetches and memos that depend on it do not rerun for an unchanged model.
+
+**`selectedRowIds` (Set):** The array `rowSelectionModel` is converted to a `Set` via `useMemo` for O(1) membership checks during row rendering. Both are returned so callers can choose the right structure.
+
+---
+
+## Relationship to DataGrid
+
+`DataGrid.tsx` calls this hook at the top of its body and destructures the returned values directly into the variables used by the rest of the component. The hook replaces the controlled/uncontrolled block that previously occupied lines ~200–285 of `DataGrid.tsx`.
+
+---
+
+## 🔗 Related
+- [useGridRowPipeline](use-grid-row-pipeline.md)
+- [DataGrid](../components/datagrid.md)

package/docs/architecture/use-grid-row-pipeline.md

@@ -0,0 +1,120 @@
+# `useGridRowPipeline`
+
+Internal hook. Transforms the raw `rows` array through a deterministic five-stage pipeline — filter → pin → sort → paginate → assemble — producing the final ordered list of rows the viewport renders.
+
+**File:** `lib/hooks/core/useGridRowPipeline.ts`
+
+---
+
+## Purpose
+
+Before this hook existed, the five `useMemo` stages lived inline in `DataGrid.tsx` (~85 lines). Extracting them into one place makes the pipeline independently testable and removes noise from the main component.
+
+---
+
+## Pipeline stages
+
+```
+effectiveRows
+   │
+   ▼ filterRows (client) / getVisibleRows (hierarchy) / passthrough (filterMode='server')
+filteredRows
+   │
+   ▼ getPinnedRowGroups
+pinnedTopRows, unpinnedRows, pinnedBottomRows
+   │
+   ▼ sortRows (client) / passthrough (sortingMode='server' / hierarchy)
+sortedUnpinnedRows
+   │
+   ▼ slice [currentPage * pageSize, (currentPage+1) * pageSize]  — skipped when pagination=false or paginationMode='server'
+paginatedUnpinnedRows
+   │
+   ▼ [...pinnedTop, ...center, ...pinnedBottom]
+allRenderableRows   ← the rows the grid view and the list view render
+```
+
+**Server modes do not need a `dataSource`.** `filterMode`, `sortingMode` and `paginationMode` set to
+`'server'` mean the rows already arrived filtered, sorted or paged, whether a `dataSource` fetched
+them or the consumer did (for example from `onPaginationModelChange`). Before v3.0 the passthrough
+applied only when a `dataSource` was also set, so a consumer-fetched page was sliced again (page 2
+rendered empty) and server results were re-filtered and re-sorted with client rules.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridRowPipelineParams<R extends GridRowModel> {
+    effectiveRows: R[];                       // rows after dataSource / prop merge
+    activeHierarchyHandlers: { getVisibleRows: () => R[] } | null;
+    filterMode: 'client' | 'server';
+    filterModel: GridFilterModel;
+    sortModel: GridSortItem[];
+    sortingMode: 'client' | 'server';
+    pagination: boolean;                      // must be true to enable slicing
+    paginationMode: 'client' | 'server' | 'infinite';
+    effectivePaginationModel: GridPaginationModel;
+    pinnedRows?: GridRowPinning;              // { top: GridRowId[], bottom: GridRowId[] }
+    getRowId?: (row: R) => GridRowId;         // resolves ids for pinnedRows; rows are not required to carry `id`
+    columnLookup?: GridColumnLookup;          // from useGridColumnLookup(activeColumns, columnVisibilityModel)
+}
+```
+
+`columnLookup` (built by `useGridColumnLookup`, `lib/utils/columnLookup.ts`) gives `filterRows` / `sortRows` the column definitions: cells are read through `valueGetter` (`getCellValue` in `lib/utils/values.ts`), the column `type` selects numeric / date comparison, and the quick filter searches only the visible, filterable columns. `DataGrid` passes the same lookup to `useTreeData` and `useRowGrouping`, which compile the filter once per pass with `createRowFilter` and sort with `compareRowsBySortModel` / `compareValues`. The lookup's identity changes only when the columns or the set of hidden columns change, so an inline `columnVisibilityModel` object does not re-run filter and sort.
+
+> **`GridRowPinning` vs `GridPinnedRows<R>`** — `GridRowPinning` (used here) holds `top: GridRowId[]`; `GridPinnedRows<R>` holds `top: R[]`. These are distinct types. `getPinnedRowGroups` expects `GridRowPinning`.
+
+---
+
+## Returns
+
+```ts
+interface GridRowPipelineResult<R extends GridRowModel> {
+    filteredRows: R[];
+    dataRows: R[];               // filtered data rows, independent of hierarchy expansion
+    pinnedTopRows: R[];
+    unpinnedRows: R[];
+    pinnedBottomRows: R[];
+    sortedUnpinnedRows: R[];
+    paginatedUnpinnedRows: R[];
+    currentPage: number;         // the page actually sliced (clamped to the last page)
+    allRenderableRows: R[];      // the rows the grid view and the list view render
+}
+```
+
+All intermediate results are returned so features like the row count badge or aggregation can read them without re-deriving them. The client pager counts `sortedUnpinnedRows` (filtered, pinned rows excluded, since pinned rows show on every page); select-all acts on `dataRows`.
+
+---
+
+## Page clamping
+
+When the grid pages client-side, the slice uses `currentPage`: `effectivePaginationModel.page` clamped to `0 … pageCount - 1`, where `pageCount = ceil(sortedUnpinnedRows.length / pageSize)` (at least 1). A page size below 1 is treated as 1 (`lib/utils/pagination`). So when the rows shrink (new `rows`, a filter, collapsed tree nodes) and the requested page is past the end, the last page is shown instead of an empty body. Under server pagination (`paginationMode="server"`) `currentPage` is the requested page, because the server owns the page count.
+
+`DataGrid` passes `currentPage` to the pager and calls `useGridPageCorrection`, which reports the corrected model through `onPaginationModelChange` (and stores it when uncontrolled) once rows are present and nothing is loading. A restored page is therefore not thrown away before the rows arrive.
+
+---
+
+## Hierarchy mode shortcut
+
+When `activeHierarchyHandlers` is set (tree data or row grouping), the hook delegates row ordering entirely to the hierarchy controller. Pinning and client-side sort/filter are bypassed: `getVisibleRows()` becomes `filteredRows` and `sortedUnpinnedRows`. Pagination still applies, so `allRenderableRows` is the current page of the visible hierarchy, the same rows the grid view renders.
+
+---
+
+## Infinite scroll loading rows
+
+`allRenderableRows` holds only real rows. While an infinite-scroll page loads, `GridVirtualRows` draws the placeholder rows itself (from `dataSourceLoading`) and `useLayout` adds their height, so the placeholders never reach `renderCell`, the list view, keyboard navigation, selection or spanning. (Before v3.0 the hook appended `{ id: '__skeleton_N__', _isSkeleton: true }` objects to `allRenderableRows`.)
+
+---
+
+## Relationship to DataGrid
+
+`DataGrid.tsx` calls this hook and destructures `allRenderableRows` for the viewport, `filteredRows` for the row count display, and `pinnedTopRows` / `pinnedBottomRows` for the sticky row sections.
+
+---
+
+## 🔗 Related
+- [useGridControlledState](use-grid-controlled-state.md)
+- [useGridVirtualization](use-grid-virtualization.md)
+- [Filtering](../features/filtering.md)
+- [Sorting & Pagination](../features/sorting-pagination.md)
+- [Tree Data & Grouping](../features/tree-data-grouping.md)