@opencorestack/opengridx 2.1.0 → 3.0.0

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

@@ -12,6 +12,7 @@ Row grouping allows you to categorize rows based on common column values.
 ```tsx
 <DataGrid
   rows={rows}
+  columns={columns}
   rowGroupingModel={['department', 'role']}
 />
 ```
@@ -19,14 +20,24 @@ Row grouping allows you to categorize rows based on common column values.
 ### Features
 - **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.
 
 ---
 
@@ -36,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
@@ -54,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
@@ -76,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,7 +17,7 @@ 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)
+- Row height (the fixed `rowHeight`, plus the height of any expanded detail panels)
 - Overscan buffer (adaptive, minimum `overscanRowCount`, default 3 rows)
 
 ```tsx
@@ -33,12 +33,22 @@ The grid calculates which rows are visible based on:
 - ✅ 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
 
 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.
@@ -63,6 +73,16 @@ The most common cause is a flex child that is missing `min-height: 0`. A flex it
 
 `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.
@@ -71,7 +91,7 @@ Pagination can hide this problem, because a paginated grid only has one page of
 
 ### 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)
@@ -221,8 +241,9 @@ You should see console logs only for visible rows + overscan buffer.
 ## Known Limitations
 
 1. **Unbounded containers** - Virtualization needs a bounded viewport height (see above)
-2. **Dynamic row heights** - Requires full dataset scan for accurate scroll calculations
-3. **Horizontal scrolling** - May show brief flicker with very wide grids
+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
 
@@ -237,9 +258,9 @@ You should see console logs only for visible rows + overscan buffer.
 |---------|--------------|----------------|
 | Row virtualization | ✅ Yes | ✅ Yes |
 | Column virtualization | ✅ Yes (unpinned columns) | ✅ Yes (Pro) |
-| Variable row heights | ✅ Yes | ✅ Yes |
+| 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
 

package/docs/migration/v1-to-v2.md

@@ -0,0 +1,115 @@
+# Migrating from v1 to v2
+
+This guide covers every change that requires action when upgrading `@opencorestack/opengridx` from any v1.x release to v2.0.0.
+
+---
+
+## 1. Remove two dead callback props
+
+These props existed in v1 but their callbacks were **never called** — no UI existed to trigger them. They have been removed from `DataGridProps` in v2.
+
+| Removed prop | Why | Fix |
+| :--- | :--- | :--- |
+| `onPinnedRowsChange` | No pin/unpin-row UI exists | Delete the prop from your JSX |
+| `onRowGroupingModelChange` | No drag-to-group UI exists | Delete the prop from your JSX |
+
+**TypeScript will give a compile error at every call site.** Runtime behavior is unchanged — these callbacks were never invoked, so removing them has no effect.
+
+```tsx
+// v1 — remove these props:
+<DataGrid
+  onPinnedRowsChange={handlePinnedRowsChange}      // ❌ delete
+  onRowGroupingModelChange={handleGroupingChange}  // ❌ delete
+/>
+
+// v2:
+<DataGrid />
+```
+
+---
+
+## 2. Audit columns with `groupable: false`
+
+In v1 the `groupable: false` flag on a `GridColDef` was **silently ignored** — the column was still grouped if it appeared in `rowGroupingModel`. In v2 the flag is enforced: that field is skipped entirely when building the group tree.
+
+**Action required only if** you have a column with `groupable: false` that also appears in `rowGroupingModel`.
+
+```tsx
+// If you have this in v1 and the column was grouping:
+{ field: 'id', groupable: false }
+// ...and rowGroupingModel includes 'id'
+
+// v2: 'id' is now silently skipped from grouping.
+// Either remove 'id' from rowGroupingModel, or remove groupable:false.
+```
+
+---
+
+## 3. Audit columns with `availableAggregationFunctions`
+
+In v1 `availableAggregationFunctions` on a `GridColDef` was **silently ignored** — all configured aggregation functions ran regardless. In v2 this list is enforced: any function in `aggregationModel` that is not in `availableAggregationFunctions` for that field is skipped.
+
+**Action required only if** you have `availableAggregationFunctions` set AND the active `aggregationModel` for that field uses a function not in that list.
+
+```tsx
+// v1: both 'sum' and 'avg' aggregations ran, regardless of this list
+{ field: 'salary', availableAggregationFunctions: ['sum'] }
+// ...with aggregationModel: { salary: 'avg' }
+
+// v2: 'avg' is skipped for 'salary' because it is not in the allowed list.
+// Fix: either add 'avg' to availableAggregationFunctions, or change aggregationModel.
+```
+
+---
+
+## 4. `groupingColDef` now creates a real column
+
+In v1 passing `groupingColDef` had no runtime effect. In v2, when `rowGroupingModel` is active, `groupingColDef` creates a dedicated `__group__` column at position 0, auto-pinned left.
+
+**Action required only if** you were passing `groupingColDef` expecting it to be a no-op.
+
+```tsx
+// v1: this prop was accepted but did nothing
+<DataGrid groupingColDef={{ headerName: 'Group', width: 200 }} rowGroupingModel={['dept']} />
+
+// v2: this creates a pinned __group__ column at position 0.
+// If you don't want the dedicated column, remove groupingColDef.
+```
+
+---
+
+## 5. No action needed: legacy underscore row fields are still present
+
+> **v3.0 update:** the underscore fields are removed at runtime in 3.0.0. See [Migrating from v2 to v3](./v2-to-v3.md).
+
+Earlier drafts of `docs/architecture/grid-row-meta.md` and `docs/roadmap.md` stated that the `_hasChildren` / `_treeDepth` / `_isExpanded` / `_groupingField` / `_groupingValue` / `_descendantCount` / `_isGroupRow` runtime shim was removed in v2.0. That was incorrect — it was never scheduled for v2.0 and nothing in this release touches it. `useTreeData` and `useRowGrouping` still inject these fields onto every row exactly as they did in v1.x.
+
+**No migration action is required.** If you were already using `params.rowMeta` (recommended since v1.1), nothing changes. If you were still reading the underscore fields directly, they continue to work in v2.0 — but treat them as deprecated and migrate to `params.rowMeta` before they're removed in a future major version. See `docs/architecture/grid-row-meta.md` for the full field mapping.
+
+---
+
+## New features (no migration needed)
+
+These are purely additive — existing v1 code continues to work unchanged.
+
+| Feature | Prop | Notes |
+| :--- | :--- | :--- |
+| Multi-sort single-click | `multiSort` | `false` by default; Shift+click always worked |
+| Multi-sort shift-click | (built-in) | Shift+click now appends; previously behaved like a plain click |
+| Row density wired | `density` | Was accepted but ignored in v1 |
+| Click-to-select control | `disableRowSelectionOnClick` | Was accepted but ignored in v1; `onRowSelectionModelChange` now fires correctly |
+| Single-row selection cap | `disableMultipleRowSelection` | Was accepted but ignored in v1 |
+| Group label formatter | `groupingValueFormatter` on `GridColDef` | New field, no v1 code has it |
+| Header tooltip | `description` on `GridColDef` | Was in types but not rendered in v1; now renders as `title` attribute |
+| Pagination fixed | (bug fix) | Uncontrolled pagination navigation now works; controlled usage unchanged |
+
+---
+
+## Quick checklist
+
+- [ ] Search codebase for `onPinnedRowsChange` — delete every occurrence
+- [ ] Search codebase for `onRowGroupingModelChange` — delete every occurrence
+- [ ] Search codebase for `groupable: false` — verify those fields are not in `rowGroupingModel`
+- [ ] Search codebase for `availableAggregationFunctions` — verify the list covers what `aggregationModel` actually uses
+- [ ] Search codebase for `groupingColDef` — verify you want the `__group__` column it now creates
+- [ ] Run TypeScript (`tsc --noEmit`) — compiler will flag any remaining type errors