@opencorestack/opengridx 2.1.0 → 3.0.1

package/docs/features/toolbar-customization.md

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

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

@@ -12,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,37 +33,59 @@ 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.
 
-The most common cause is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
+**Without a `height` prop the grid fills its container** (since 3.0.1): its root gets `height: 100%` and, as a flex item, `flex: 1 1 auto; min-height: 0`. So it fills a sized block parent, or the free space of a flex column, and virtualizes. In a container with no definite height, `100%` resolves to `auto` and the grid grows to fit its rows, exactly as before. Passing `height` (a number or any CSS length) sets the height instead; `autoHeight` always grows to fit every row.
+
+The most common cause of an unbounded container is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
 
 ```tsx
-// ❌ Grows to fit all rows — virtualization is effectively off
+// ❌ The wrapper grows to fit all rows — virtualization is effectively off
 <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
   <div style={{ flex: 1 }}>
-    <DataGrid rows={rows} columns={columns} height="100%" />
+    <DataGrid rows={rows} columns={columns} />
   </div>
 </div>
 
 // ✅ Bounded — only visible rows render
 <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
   <div style={{ flex: 1, minHeight: 0 }}>
-    <DataGrid rows={rows} columns={columns} height="100%" />
+    <DataGrid rows={rows} columns={columns} />
   </div>
 </div>
 ```
 
-`height="100%"` only helps if every ancestor up to a fixed-height element also has a definite height.
+Every flex (or grid) item between the grid and the element with a fixed height (`100vh`, `600px`, …) needs `min-height: 0`. The grid itself can also be the flex item: `<div style={{ display: 'flex', flexDirection: 'column', height: 600 }}><Toolbar /><DataGrid … /></div>` gives the grid the space left after the toolbar.
+
+**`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`. Inside a bounded container, 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} />
+  </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.
+In development builds the grid logs a `console.warn` when it is rendering every row of a dataset larger than 200 rows and its viewport is at least as tall as those rows, that is, when its container really is unbounded. The warning names the fixes above.
 
 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 +93,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)
@@ -185,7 +207,7 @@ When using detail panels, row heights become variable. The grid automatically:
 
 ## Virtualization with Grouping/Tree Data
 
-Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium by `DataGrid.virtualization.browser.test.tsx`).
+Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium, Firefox and WebKit by `DataGrid.virtualization.browser.test.tsx`).
 
 ```tsx
 // Tree data with virtualization
@@ -221,8 +243,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 +260,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