@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/architecture/use-grid-scroll-sync.md

@@ -0,0 +1,111 @@
+# `useGridScrollSync`
+
+Internal hook. Manages all scroll-related state and the `handleScroll` callback for the grid viewport — including RAF-batched tick updates that trigger virtualization recomputes and the `onRowsScrollEnd` threshold check for infinite scroll.
+
+**File:** `lib/hooks/core/useGridScrollSync.ts`
+
+---
+
+## Purpose
+
+Before extraction, three pieces of scroll logic lived inline in `DataGrid.tsx`:
+1. `scrollPosRef` / `scrollRafRef` / `scrollTick` state setup (~5 lines)
+2. A cleanup effect canceling the pending RAF on unmount (~4 lines)
+3. `handleScroll` callback with RAF scheduling and scroll-end threshold (~22 lines)
+
+Extracting them gives the scroll logic its own test surface and removes 31 lines from `DataGrid.tsx`.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridScrollSyncParams {
+    onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
+    /** Minimum overscan rows — the adaptive algorithm never goes below this. Defaults to 3. */
+    overscanRowCount?: number;
+}
+```
+
+---
+
+## Returns
+
+```ts
+interface UseGridScrollSyncResult {
+    scrollTop: number;
+    scrollLeft: number;
+    /** Dynamically computed overscan row count based on current scroll velocity. */
+    overscanRows: number;
+    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+}
+```
+
+| Return | Used by |
+|--------|---------|
+| `scrollTop` | `useGridVirtualization` — vertical scroll offset for computing the visible row window |
+| `scrollLeft` | `useGridVirtualization` — horizontal scroll offset for computing the visible column window |
+| `overscanRows` | `useGridVirtualization` — adaptive overscan count, set from current scroll velocity |
+| `handleScroll` | Passed to the viewport `<div onScroll={handleScroll}>` |
+
+---
+
+## RAF batching pattern
+
+`handleScroll` fires on every scroll event (can be 60+ per second). Rather than recomputing the virtual window on every event, the hook schedules a single RAF per frame:
+
+```
+scroll event → measure velocity → cancel pending RAF → schedule new RAF
+  → RAF fires → setScrollState({ scrollTop, scrollLeft, overscanRows })
+```
+
+All three values are bundled into a single `setScrollState` call so `useGridVirtualization` recomputes exactly once per frame. Scroll velocity (px/ms) is computed as `deltaPos / deltaTime` from the previous scroll event, then mapped to an overscan tier via `velocityToOverscan()`:
+
+| Velocity (px/ms) | `overscanRows` |
+|---|---|
+| < 0.5 | 3 |
+| 0.5 – 3 | 5 |
+| 3 – 15 | 12 |
+| 15 – 40 | 20 |
+| > 40 | 30 |
+
+The state holds only the velocity-derived count (0 at rest); the returned value is `Math.max(velocityCount, overscanRowCount)`, computed during render, so a new `overscanRowCount` applies immediately.
+
+---
+
+## Decay timer
+
+200 ms after the last scroll event, a `setTimeout` callback resets `overscanRows` back to `overscanRowCount`. This prevents the grid from holding a large overscan buffer while the user is idle.
+
+---
+
+## `onRowsScrollEnd` threshold
+
+When a **vertical** scroll brings the viewport within 100px of the bottom (`scrollHeight - scrollTop - clientHeight < 100`), the hook calls `onRowsScrollEnd` synchronously (not RAF-batched) so the consumer can load the next page immediately. A latch makes it fire once per arrival: it re-arms when the viewport leaves the threshold or `rowCount` changes. After every `rowCount` change an effect re-checks the viewport, so a page that does not fill it still fires (skipped with `autoHeight` or a 0px viewport). Horizontal-only scroll events are ignored.
+
+## Viewport remounts
+
+`attachViewport` is the viewport's callback ref (combined by `useGridViewport` with `useGridViewportSize`, which attaches a `ResizeObserver` to every viewport element that mounts). When the viewport remounts (list view switched off again) it restores the last scroll position onto the new element; if the browser clamps it, the state is synced to the element.
+
+---
+
+## Cleanup
+
+The hook registers a single `useEffect` with an empty dependency array to cancel any pending RAF and decay timer on unmount:
+
+```ts
+useEffect(() => {
+    return () => {
+        if (rafRef.current !== null) cancelAnimationFrame(rafRef.current);
+        if (decayRef.current !== null) clearTimeout(decayRef.current);
+    };
+}, []);
+```
+
+This prevents a `setState` call on an unmounted component if the grid is removed mid-scroll.
+
+---
+
+## 🔗 Related
+- [useGridVirtualization](use-grid-virtualization.md)
+- [useGridStateSnapshot](use-grid-state-snapshot.md)

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

@@ -0,0 +1,90 @@
+# `useGridStateSnapshot`
+
+Internal hook. Fires the `onStateChange` callback whenever the *value* of any tracked grid state changes — sorting, filtering, pagination, column configuration or density. Packages the current state into a `GridState` snapshot and delivers it to the caller.
+
+**File:** `lib/hooks/core/useGridStateSnapshot.ts`
+
+---
+
+## Purpose
+
+Before extraction, ~28 lines of state-snapshot logic lived inline in `DataGrid.tsx` — a `useRef` to hold the latest `onStateChange` callback plus a `useEffect` that fired on state changes. Extracting them makes the snapshot contract explicit and independently testable.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridStateSnapshotParams {
+    onStateChange?: (state: GridState) => void;
+    sortModel: GridSortItem[];
+    filterModel: GridFilterModel;
+    effectivePaginationModel: GridPaginationModel;
+    columnWidths: Record<string, number>;
+    effectiveColumnOrder: string[];
+    columnVisibilityModel: Record<string, boolean>;
+    pinnedColumns: GridColumnPinning;   // the user's pins, not the grid's effective pins
+    density: 'compact' | 'standard' | 'comfortable';
+}
+```
+
+---
+
+## Returns
+
+`void` — this is a side-effect-only hook.
+
+---
+
+## Snapshot shape
+
+The hook assembles a `GridState` object on every tracked change:
+
+```ts
+{
+    sorting: { sortModel },
+    filter: { filterModel },
+    pagination: { paginationModel: effectivePaginationModel },
+    columns: {
+        columnWidths,
+        columnOrder: effectiveColumnOrder,
+        columnVisibilityModel,
+        pinnedColumns,
+    },
+    density: { density },
+}
+```
+
+Grid-owned columns never appear in it: the synthetic `__group__` column (added when `groupingColDef` is set under row grouping) is removed from `columnOrder`, `pinnedColumns`, `columnWidths` and `columnVisibilityModel`, so the persisted state only names the consumer's own columns.
+
+This matches the `GridState` interface from `lib/state/types.ts` and is the same structure accepted by `initialState` / `GridInitialState` — so a caller can persist the snapshot and restore it directly.
+
+---
+
+## Fires on value changes, not identity changes
+
+Inline model props (`filterModel={{ items: [] }}`, `paginationModel={{ page, pageSize }}`) get a new identity on every parent render. The hook keeps the JSON of the last emitted snapshot in a ref and skips `onStateChange` when the new snapshot serialises the same (the snapshot holds only plain data). Without this, an `onStateChange` that stores the state in the parent re-renders the parent, which creates new inline props, which fires `onStateChange` again — an endless loop.
+
+---
+
+## Ref-stabilized callback
+
+`onStateChange` is stored in a ref (updated via `useLayoutEffect`) rather than being included directly in the snapshot effect's dependency array:
+
+```ts
+const onStateChangeRef = useRef(onStateChange);
+useLayoutEffect(() => {
+    onStateChangeRef.current = onStateChange;
+});
+```
+
+**Why:** Without a ref, if the consumer passes an inline arrow function (`onStateChange={() => {...}}`), the snapshot effect would fire on every render (the function identity changes each time) rather than only when state actually changes. The ref decouples the callback identity from the effect deps.
+
+`useLayoutEffect` (not `useEffect`) is used for the ref update so the ref is always current before the snapshot effect reads it, avoiding a one-render lag on the first fire.
+
+---
+
+## 🔗 Related
+- [useGridScrollSync](use-grid-scroll-sync.md)
+- [useGridControlledState](use-grid-controlled-state.md)
+- [useGridColumns](use-grid-columns.md)

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

@@ -0,0 +1,115 @@
+# `useGridVirtualization`
+
+Internal hook. Converts scroll position, viewport dimensions, and the current row/column layout into a render context — the minimal window of rows and columns that need to be in the DOM at any given moment.
+
+**File:** `lib/hooks/core/useGridVirtualization.ts`
+
+---
+
+## Purpose
+
+Row virtualization is the core performance mechanism: instead of rendering all rows, only the visible slice is rendered. Columns are virtualized too: of the unpinned (centre) columns, only those in the horizontal viewport plus an overscan of **6 columns on each side** are rendered, with spacer columns standing in for the rest. Pinned columns (left and right) are always rendered. This hook encapsulates the binary search and offset math that determines both slices.
+
+Row indices in `renderContext` and `cumulativeHeights` cover the **centre (unpinned) rows only**; top- and bottom-pinned rows are laid out separately (`pinnedTopHeight` / `pinnedBottomHeight`).
+
+Before extraction, ~120 lines of `useMemo` logic lived inside `DataGrid.tsx`. The hook makes the math independently readable and testable.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridVirtualizationParams<R extends GridRowModel> {
+    layout: LayoutResult<R>;   // from useLayout: row heights, column widths
+    scrollTop: number;         // current vertical scroll position in pixels
+    scrollLeft: number;        // current horizontal scroll position in pixels
+    viewportWidth: number;
+    viewportHeight: number;
+    autoHeight: boolean;
+    rowReordering: boolean;
+    hasDetailPanel: boolean;
+    checkboxSelection: boolean;
+    pinCheckboxColumn: boolean;
+    pinExpandColumn: boolean;
+    /** Adaptive overscan row count from useGridScrollSync. Defaults to 5 when omitted. */
+    overscanRows?: number;
+}
+```
+
+> `scrollTop`, `scrollLeft`, and `overscanRows` all come from `useGridScrollSync`, which batches scroll events via RAF and bundles all three into a single state update that fires at most once per animation frame. `overscanRows` there is velocity-based and never below the grid's `overscanRowCount` prop (default 3). Column overscan is fixed at 6 and not configurable.
+
+---
+
+## Returns
+
+```ts
+interface GridVirtualizationResult {
+    renderContext: {
+        firstRowIndex: number;
+        lastRowIndex: number;
+        firstColumnIndex: number;
+        lastColumnIndex: number;
+    };
+    offsetTop: number;           // translateY for the virtual row block
+    offsetLeft: number;          // always 0: horizontal offset is carried by spacer columns
+    totalHeight: number;         // full scrollable height
+    pinnedTopHeight: number;
+    pinnedBottomHeight: number;
+    totalWidth: number;
+    rowHeights: number[];
+    cumulativeHeights: number[]; // inclusive prefix sums of centre-row heights (from useLayout)
+    virtualColumns: (GridColDef<R> & { width: number })[]; // left-pinned, [__spacer_left__], window, [__spacer_right__], right-pinned
+    columnMetrics: {
+        leftPinnedWidth: number;
+        rightPinnedWidth: number;
+        unpinnedAccWidths: number[];  // inclusive prefix sums of unpinned column widths
+        unpinnedCols: { field: string; width: number }[];
+        totalSpecialsWidth: number;   // combined width of checkbox / expand / reorder columns
+        pinnedSpecialsWidth: number;
+    };
+}
+```
+
+---
+
+## Binary search algorithm
+
+The hook uses binary search on the `cumulativeHeights` prefix-sum array to find the first visible row in O(log n) instead of scanning all rows:
+
+```
+cumulativeHeights[i] = sum of heights of centre rows 0..i   (inclusive: the bottom edge of row i)
+
+firstVisible  = first index where cumulativeHeights[i] >= scrollTop
+firstRowIndex = max(0, firstVisible - overscanRows)
+offsetTop     = firstRowIndex > 0 ? cumulativeHeights[firstRowIndex - 1] : 0
+lastRowIndex  = (first index where cumulativeHeights[i] >= scrollTop + viewportHeight) + overscanRows,
+                clamped to the last centre row
+```
+
+Row heights include an expanded detail panel's height, so the prefix sums account for open panels.
+
+Columns use the same search on `unpinnedAccWidths` (also inclusive), relative to the left edge of the unpinned area (`scrollLeft - leftPinnedWidth`), widened by 6 columns on each side. The skipped widths become `__spacer_left__` / `__spacer_right__` entries (`isSpacer: true`) in `virtualColumns`.
+
+When a column declares `colSpan` / `rowSpan`, `DataGrid` widens this window afterwards (`useGridSpanRowWindow` / `useGridSpanColumnWindow`) so a span whose origin is outside the window is not cut.
+
+---
+
+## `autoHeight` mode
+
+When `autoHeight={true}`, the viewport height used for the row window is the sum of all row heights (pinned and centre, plus 50px) rather than the measured container height. Row virtualization is effectively disabled — all rows are in the render window — so the height adjusts to content. Column virtualization still applies. Without `autoHeight`, a viewport that has not been measured yet falls back to 600px high and 1000px wide.
+
+---
+
+## Relationship to DataGrid
+
+`DataGrid.tsx` calls this hook and uses:
+- `renderContext` (after the span widening above) to slice the centre rows to the visible subset; `useGridVisibleRows` then merges them with the pinned rows
+- `offsetTop` as the `translateY` value on the virtual row container
+- `totalHeight` and `totalWidth` to set the scroll container's inner dimensions
+- `columnMetrics` to lay out pinned and unpinned column groups
+
+---
+
+## 🔗 Related
+- [useGridRowPipeline](use-grid-row-pipeline.md)
+- [Virtualization](../features/virtualization.md)

package/docs/architecture/use-grid-visible-rows.md

@@ -0,0 +1,85 @@
+# `useGridVisibleRows`
+
+Internal hook. Merges the pinned top rows, the virtual center window, and the pinned bottom rows into a single `{ row, rowIndex }[]` array — exactly what the viewport JSX iterates to render `<Row>` components.
+
+**File:** `lib/hooks/core/useGridVisibleRows.ts`
+
+---
+
+## Purpose
+
+The render window is the intersection of what the row pipeline produced and what the virtualization engine says is visible. Before this hook, ~40 lines of `useMemo` logic lived inline in `DataGrid.tsx`. Extracting it makes the merge strategy explicit and independently testable.
+
+---
+
+## Parameters
+
+```ts
+interface UseGridVisibleRowsParams<R extends GridRowModel> {
+    renderContext: {
+        firstRowIndex: number;  // from useGridVirtualization
+        lastRowIndex: number;
+    };
+    pinnedTopRows: R[];             // from useGridRowPipeline
+    pinnedBottomRows: R[];          // from useGridRowPipeline
+    paginatedUnpinnedRows: R[];     // from useGridRowPipeline
+    sortedUnpinnedRows: R[];        // from useGridRowPipeline
+    pagination: boolean;
+}
+```
+
+---
+
+## Returns
+
+```ts
+GridVisibleRow<R>[]
+// where GridVisibleRow<R> = { row: R; rowIndex: number }
+```
+
+`rowIndex` is the position in the renderable rows (top-pinned + the current page's centre rows + bottom-pinned) — it becomes the row's `data-rowindex`, the `rowIndex` in `onRowClick` / `getDetailPanelContent` params and the zebra-stripe class. `aria-rowindex` is computed separately (`lib/utils/aria`, `getAriaRowLayout`): it adds the header rows and, for centre rows, the rows on earlier pages, and puts bottom-pinned rows after every page. `GridPinnedRows` receives the bottom rows' offset (`topPinned + centerCount`) so they no longer restart at 0.
+
+---
+
+## Merge strategy
+
+```
+topPinned:  rows 0 .. pinnedTopRows.length - 1              (always fully rendered)
+center:     rows [firstRowIndex - topPinnedCount, lastRowIndex - topPinnedCount]
+            (clipped to the virtual window)
+bottomPinned: rows (topPinned + centerCount) .. end          (always fully rendered)
+```
+
+Pinned rows are NOT subject to virtualization — they are always in the DOM regardless of scroll position.
+
+---
+
+## Deduplication guard
+
+After merging, the hook filters out any row whose `id` has already been seen:
+
+```ts
+const seenIds = new Set<GridRowId>();
+return combined.filter(item => {
+    if (seenIds.has(item.row.id)) return false;
+    seenIds.add(item.row.id);
+    return true;
+});
+```
+
+**Why:** If a user passes the same row in both `rows` and `pinnedRows`, it would appear in both `pinnedTopRows` and `paginatedUnpinnedRows`. Two `<Row key={id}>` elements with the same key cause React reconciliation bugs. The guard ensures each ID appears at most once — the pinned version takes precedence since it comes first in the merged array.
+
+Entries from the pinned sections carry `pinned: 'top' | 'bottom'`. `GridVirtualRows` renders only the untagged (center) entries, in one linear pass; it does not de-duplicate again and does not consult the raw `pinnedRows` prop, so under tree data / row grouping (where nothing is pinned) every row still renders in its place.
+
+---
+
+## Relationship to DataGrid
+
+`DataGrid.tsx` calls this hook after `useGridVirtualization` produces the render context and after `useGridRowPipeline` produces the pinned/paginated row groups. The returned `visibleRows` array is iterated directly in the viewport JSX.
+
+---
+
+## 🔗 Related
+- [useGridRowPipeline](use-grid-row-pipeline.md)
+- [useGridVirtualization](use-grid-virtualization.md)
+- [useGridColumns](use-grid-columns.md)

package/docs/components/aggregation-footer.md

@@ -6,24 +6,29 @@ Internal component that renders the sticky aggregation totals row pinned to the
 
 | Prop | Type | Description |
 | :--- | :--- | :--- |
-| `columns` | `GridColDef[]` | Ordered list of visible column definitions used to lay out cells. |
+| `columns` | `GridColDef[]` | The columns exactly as the rows lay them out (`virtualization.virtualColumns`): visible columns only, left-pinned first and right-pinned last, with the horizontal-virtualization spacer entries. |
 | `aggregationModel` | `GridAggregationModel` | Maps field names to function names (`'sum' \| 'avg' \| 'count' \| 'min' \| 'max' \| 'unique'`). |
 | `aggregationResult` | `GridAggregationResult` | Computed values keyed by field name, produced by `useAggregation`. |
-| `columnWidths` | `Record<string, number>` | Runtime pixel widths for each field, kept in sync with user resize actions. |
+| `columnWidths` | `Record<string, number>` | User resize overrides, as passed to the rows; otherwise each column's layout width is used. |
 | `rowHeight` | `number` | Sets `min-height` on the footer row, matching the grid's configured row height. |
-| `checkboxSelection` | `boolean` | When `true`, inserts a 48px spacer at the start to align with the checkbox column. |
-| `hasDetailPanel` | `boolean` | When `true`, inserts a 48px spacer to align with the expand/collapse column. |
-| `rowReordering` | `boolean` | When `true`, inserts a 48px spacer to align with the drag handle column. |
+| `checkboxSelection` | `boolean` | When `true`, inserts a 48px spacer aligned with the checkbox column. |
+| `hasDetailPanel` | `boolean` | When `true`, inserts a 48px spacer aligned with the expand/collapse column. |
+| `rowReordering` | `boolean` | When `true`, inserts a 48px spacer aligned with the drag handle column (always sticky, like the row's handle). |
+| `pinCheckboxColumn` | `boolean` | Default `true`. Whether the checkbox spacer sticks to the left, matching the row's checkbox column; also used for the pinned-column offsets. |
+| `pinExpandColumn` | `boolean` | Default `true`. The same for the expand/collapse spacer. |
+| `pinnedColumns` | `GridColumnPinning` | Pinned columns get sticky totals at the same offsets as the pinned body cells. |
+| `loading` | `boolean` | A server aggregation request is pending: sets `aria-busy="true"` and the class `ogx__aggregation-footer--loading`. |
 
 ## 🔄 When it renders
 
-`GridAggregationFooter` renders when `aggregationModel` has at least one entry and `aggregationResult` contains the corresponding computed values. The footer is sticky — it remains visible when the user scrolls vertically.
+`GridAggregationFooter` renders when `aggregationModel` has at least one entry, except in pivot mode (the pivot's Grand Total row is the aggregate there). The footer is sticky — it remains visible when the user scrolls vertically. A column without an entry in `aggregationModel` gets an empty cell, so every total sits under its header.
 
 ## 🔢 Value formatting
 
-Values are formatted by `formatAggregationValue` from `useAggregation`:
-- `count` → integer (e.g. `42`)
-- `sum` / `avg` / `min` / `max` → `toLocaleString()` with up to 2 decimal places
+Values are formatted by `formatAggregateForColumn` (`lib/utils/aggregation`), the same formatting used by group rows, pivot cells and exports:
+- `sum` / `avg` / `min` / `max` go through the column's `valueFormatter`, with the footer totals (`aggregationResult`) as its `row`. If the formatter throws, the default format is used.
+- `count` / `unique` are plain counts (the column's `valueFormatter` is not applied).
+- Without a formatter: `toLocaleString()` (`avg` to at most 2 decimal places); dates as locale dates; a missing value shows `—`.
 
 ## 🎨 Usage via DataGrid prop
 
@@ -41,7 +46,7 @@ The footer renders automatically. No additional configuration required.
 
 ## ♿ Accessibility
 
-The footer row uses `role="row"` and `aria-label="Aggregation totals"`. Each cell uses `role="gridcell"`. The container uses `aria-live="polite"` so screen readers announce value updates when the data changes.
+The footer row uses `role="row"` and `aria-label="Aggregation totals"`. Each cell uses `role="gridcell"`. The container uses `aria-live="polite"` so screen readers announce value updates when the data changes, and `aria-busy="true"` while server totals are loading. The system-column spacers are `aria-hidden`.
 
 ## 🔗 Related
 - [DataGrid](datagrid.md)

package/docs/components/cell.md

@@ -4,18 +4,25 @@ The atomic unit of the grid. Handles rendering, formatting, editing, and selecti
 
 ## ⚙️ Props
 
+`Cell` and its props type `CellProps` are exported. The main props:
+
 | Prop | Type | Description |
 | :--- | :--- | :--- |
-| `value` | `any` | The raw value to display. |
+| `value` | `unknown` | The cell value (after `valueGetter`). |
 | `row` | `GridRowModel` | The full row data object. |
 | `colDef` | `GridColDef` | Configuration for the column. |
 | `rowIndex` | `number` | 0-indexed position in the current view. |
+| `colIndex` | `number` | 0-indexed position of the column among the visible data columns in render order (system columns excluded). Passed to `renderCell`, `cellClassName`, `onCellClick` and `isCellEditable`. |
+| `ariaColIndex` | `number` | 1-based `aria-colindex`, system columns included. Defaults to `colIndex + 1`. |
 | `isSelected` | `boolean` | Whether the parent row is selected. |
-| `isFocused` | `boolean` | Whether the cell has keyboard focus. |
-| `isEditable` | `boolean` | Enables inline editing for this cell. |
-| `isEditing` | `boolean` | Whether the cell is currently in edit mode. |
+| `isFocused` | `boolean` | Whether the cell is the grid's focus position (drives `.ogx__cell--focused`). Since v3.0 the cell does not move DOM focus onto itself; the grid does, and only while it owns focus. |
+| `isEditable` | `boolean` | Whether this cell may enter edit mode. `<Row />` resolves it per cell from `colDef.editable`, the row (synthetic group rows are never editable) and `isCellEditable`; it also drives `aria-readonly`. |
+| `isEditing` | `boolean` | Whether the cell is currently in edit mode. While editing, clicks and double-clicks inside the cell belong to the editor and are not handled as cell clicks. |
+| `onEditStop` | `(cancel?: boolean, field?: string) => void` | Ends this cell's edit (commit, or discard when `cancel` is true). The cell passes its own `field` so a late call cannot end another cell's edit. Also called (commit) when the cell unmounts while editing. |
 | `width` | `number` | Calculated width including resizing and flex. |
 | `pinnedPosition` | `'left' \| 'right' \| null` | Sticky positioning state. |
+| `rowMeta` | `GridRowMeta` | Hierarchy metadata, passed to `renderCell` as `params.rowMeta`. |
+| `onCellClick` | `(params: GridCellParams) => void` | Click handler (not called for clicks inside an open editor). |
 
 ## 🧩 Modifiers & Classes
 
@@ -25,6 +32,7 @@ The `<Cell />` component applies various BEM classes for styling:
 - `.ogx__cell--editing`: During active cell editing.
 - `.ogx__cell--pinned-left`: Sticky to the left.
 - `.ogx__cell--pinned-right`: Sticky to the right.
+- `.ogx__cell-image`: The default `<img>` of a `type: 'image'` column without `renderCell`.
 
 ## 🛠️ Custom Rendering
 
@@ -45,9 +53,11 @@ const columns: GridColDef[] = [
 
 ## 🛡️ Error containment
 
-Custom `renderCell` callbacks are wrapped in a `CellErrorBoundary`. If a renderCell throws during render, that single cell shows a `⚠` indicator (CSS class `ogx__cell-error`) with the error message as a tooltip. The rest of the grid continues rendering normally.
+Custom `renderCell` and `renderEditCell` callbacks are wrapped in a `CellErrorBoundary`. If a renderCell throws during render, that single cell shows a `⚠` indicator (CSS class `ogx__cell-error`, `role="img"` with an `aria-label`) with the error message as a tooltip. The rest of the grid continues rendering normally.
+
+The cell renders again (and the indicator clears if the renderer now succeeds) when the row object, the column's `renderCell` function or the cell value changes, so passing fixed columns recovers without replacing every row (v3.0).
 
-Default cell display (no `renderCell`) does not go through the boundary — it cannot throw.
+A column's `valueGetter` or `valueFormatter` that throws for a row is contained the same way: that cell shows the `⚠` indicator and the rest of the grid renders. On synthetic rows (row-grouping group and subtotal rows, auto-created tree parents) `valueGetter` is not called (the row already holds its grouping value and aggregates under the column's field), and `valueFormatter` is only called for the values the row holds, not for its empty cells.
 
 To style the error indicator:
 

package/docs/components/column-group-header.md

@@ -1,50 +1,77 @@
-# `<ColumnGroupHeader />`
+# Column Group Headers
 
-The `ColumnGroupHeader` component handles the rendering of nested header groups in multi-level column layouts. It allows for advanced data organization where multiple columns are grouped under a single, semantic parent.
-
-## 📑 Overview
-- **Hierarchical Layout**: Supports an unlimited depth of nested groupings (Year → Quarter → Metric).
-- **Sticky Behavior**: Automatically stays within the grid's header section during horizontal scroll.
-- **Dynamic Calculation**: Positions itself based on the combined width of its child columns.
-- **Reflective Styles**: Inherits header-level styling while providing specialized group-level CSS hooks.
-
----
+Column group headers are spanning header cells above the regular column headers, so related columns can sit under a shared label (Year → Quarter → Metric). They are rendered by `<Header />` from the `columnGroupingModel` prop on `<DataGrid />`; there is no separate component to import or replace (the old internal `ColumnGroupHeader` component was removed in v3.0).
 
 ## 🛠️ Usage
 
-### Define Multi-Level Grouping
-In your columns definition, include nested `columnGroups`.
+Pass a `columnGroupingModel`. Each group lists column `field`s, or nested groups, in `children`:
 
 ```tsx
-const columns = [
-  { field: 'id', headerName: 'ID', width: 100 },
-  { field: 'q1', headerName: 'Q1 Sales', width: 120 },
-  { field: 'q2', headerName: 'Q2 Sales', width: 120 },
+import { DataGrid } from '@opencorestack/opengridx';
+import type { GridColDef, GridColumnGroupingModel } from '@opencorestack/opengridx';
+
+const columns: GridColDef[] = [
+  { field: 'name', headerName: 'Name', width: 160 },
+  { field: 'q1Sales', headerName: 'Sales', type: 'number' },
+  { field: 'q1Target', headerName: 'Target', type: 'number' },
+  { field: 'q2Sales', headerName: 'Sales', type: 'number' },
+  { field: 'q2Target', headerName: 'Target', type: 'number' },
+];
+
+const columnGroupingModel: GridColumnGroupingModel = [
+  {
+    groupId: '2024',
+    headerName: '2024 Performance',
+    children: [
+      { groupId: 'q1', headerName: 'Q1', children: ['q1Sales', 'q1Target'] },
+      { groupId: 'q2', headerName: 'Q2', children: ['q2Sales', 'q2Target'], headerClassName: 'my-q2-header' },
+    ],
+  },
 ];
 
-// Define your mapping logic in your component or use the columns API:
-// ColumnGroupHeader is typically used by the DataGrid automatically when 
-// nested structures are detected.
+<DataGrid rows={rows} columns={columns} columnGroupingModel={columnGroupingModel} height={500} />
 ```
 
-### Direct Customization
-While the grid uses this component internally, you can customize its appearance via specific CSS classes or by replacing it in the `slots` API.
+This renders two group rows (`2024 Performance`, then `Q1` / `Q2`) above the column header row: one group row per nesting level. `name` is not in any group, so it gets an empty filler cell in both group rows.
+
+See [`GridColumnGroup`](../API_REFERENCE.md#️-column-group-headers) for the type.
 
 ---
 
-## ⚙️ How it Works
+## ⚙️ How it works
 
-1. **Hierarchy Resolution**: The component takes a structure and determines which headers need to be "merged" into groups.
-2. **Width Aggregation**: Each group header calculates its own total width by summing the widths of all its children (including other nested groups).
-3. **Alignment**: Ensuring that the group labels are centered over their respective child columns for a clean visual hierarchy.
+- **Order, visibility and pinning**: a group cell covers its visible member columns in their rendered order. When the members are not adjacent (because of reordering, hiding or a pinned-section boundary), the group renders one labelled cell per run of adjacent members. Group cells over pinned columns are sticky, so they stay above their columns on horizontal scroll.
+- **Widths**: a group cell is exactly as wide as its member columns, including flex, `auto` and percentage widths and manual resizes.
+- **Reordering**: header drag and the toolbar / Columns-panel reorder keep groups intact: a column can only be moved onto a column of the same innermost group, and an ungrouped column only onto another ungrouped column.
+- **Accessibility**: group rows are `role="row"` with `aria-rowindex`; group cells are `role="columnheader"` with `aria-colspan` (visible member columns) and `aria-colindex`; filler cells are `aria-hidden`. The grid's `aria-rowcount` includes the group rows.
 
 ---
 
-## 🎨 Customization
+## 🎨 Styling
+
+Group headers cannot be replaced through the `slots` API. Style them with CSS:
+
+| Class | Element |
+| :--- | :--- |
+| `.ogx-col-group-row` | One group header row (one per nesting level). |
+| `.ogx-col-group-cell` | Every cell in a group row. |
+| `.ogx-col-group-cell--group` | A cell that shows a group label. |
+| `.ogx-col-group-cell--filler` | An empty cell over columns that are not in a group at that level. |
+| `.ogx-col-group-cell--pinned` | A cell over pinned columns (sticky), with `--pinned-left` or `--pinned-right`. |
+| `.ogx-col-group-cell__label` | The label text inside a group cell. |
 
-Column group headers are rendered internally; they cannot be replaced via the slots API. Style them through CSS targeting `.ogx__column-group-header`, or use the `columnGroupingModel` to control grouping structure.
+A group's `headerClassName` is added to its group cells, next to `ogx-col-group-cell` and `ogx-col-group-cell--group`:
+
+```css
+.ogx-col-group-cell--group {
+  font-weight: 600;
+}
+.my-q2-header {
+  background: #eef2ff;
+}
+```
 
 ## 📝 Best Practices
 - **Logical Labels**: Use clear, concise labels for groups like `2024 Performance` or `Contact Info`.
 - **Type-Based Grouping**: Align related data types (e.g., all currency fields under a `Finance` group) for better user comprehension.
-- **Limit Depth**: While technically unlimited, more than 3-4 levels of nesting can become difficult for users to follow on small screens.
+- **Limit Depth**: More than 3-4 levels of nesting becomes hard to follow, especially on small screens.