@opencorestack/opengridx 2.0.3 → 2.1.0

package/docs/API_REFERENCE.md

@@ -18,9 +18,10 @@ The main component for displaying and interacting with data.
 | `rowHeight` | `number` | `52` | Height of each row in pixels. |
 | `headerHeight` | `number` | `56` | Height of the header row. |
 | `autoHeight` | `boolean` | `false` | Adjust grid height to match row total. |
+| `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
 | `loading` | `boolean` | `false` | Shows a loading skeleton overlay. |
 | `checkboxSelection` | `boolean` | `false` | Enable row selection via checkboxes. |
-| `pagination` | `boolean` | `false` | Enable the bottom pagination bar. |
+| `pagination` | `boolean` | `false` | Enable the bottom pagination bar. Ignored while `rowGroupingModel` is active (dev-mode warning). |
 | `paginationMode` | `'client' \| 'server' \| 'infinite'` | `'client'` | How to handle paging. |
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). |
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
@@ -29,11 +30,12 @@ The main component for displaying and interacting with data.
 | `height` | `number \| string` | `undefined` | Total height of the grid container. |
 | `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density. |
 | `initialState` | `GridInitialState` | `undefined` | Starting state for sorting, filters, etc. |
-| `slots` | `GridSlots` | `{}` | Custom component overrides. |
+| `slots` | `GridSlots` | `{}` | Custom component overrides: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`. See [Slots API](customization/slots-api.md). |
 | `slotProps` | `Record<string, unknown>` | `{}` | Props passed to custom slots. |
 | `filterModel` | `GridFilterModel` | `undefined` | Active filters. |
 | `sortModel` | `GridSortItem[]` | `undefined` | Active sorting. |
 | `onRowClick` | `(params: GridRowParams) => void` | — | Fired when a row is clicked. |
+| `onRowDoubleClick` | `(params: GridRowParams) => void` | — | Fired when a row is double-clicked (v2.1+). Also fires for group rows; not fired on the checkbox, expand icon, drag handle or an open editor. |
 | `onCellClick` | `(params: GridCellParams) => void` | — | Fired when a cell is clicked. |
 | `onStateChange` | `(state: GridState) => void` | — | Fired on any internal state update. |
 | `processRowUpdate` | `(new, old) => R \| Promise<R>` | — | Fired after a cell edit is committed. |
@@ -301,7 +303,7 @@ Defines the behavior and appearance of a single column.
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | Fully custom cell renderer. Receives `value`, `row`, `field`, `rowIndex`, `colIndex`. |
+| `renderCell` | `(params: GridRenderCellParams) => ReactNode` | Fully custom cell renderer. Receives `value`, `formattedValue` (v2.1+, the `valueFormatter` output), `row`, `field`, `colDef`, `rowIndex`, `colIndex`, `rowMeta`. |
 | `renderHeader` | `(params: GridRenderHeaderParams) => ReactNode` | Custom header cell renderer. Use for icons, sort indicators, or rich headers. |
 | `renderEditCell` | `(params: GridRenderCellParams) => ReactNode` | Custom editor rendered when the cell enters edit mode. Requires `editable: true`. |
 
@@ -350,11 +352,19 @@ Defines the behavior and appearance of a single column.
 | `exportToCsv(rows, cols, options?)` | `void` | Triggers download of CSV file. |
 | `exportToJson(rows, cols, options?)` | `void` | Triggers download of JSON file. |
 | `exportToExcel(rows, cols, options?)` | `void` | Basic `.xls` export (zero-dep). |
-| `exportToExcelAdvanced(rows, cols, options?)` | `Promise<void>` | Real `.xlsx` export (styled, multi-sheet, lazy-loaded). |
+| `exportToExcelAdvanced(rows, cols, options?)` | `Promise<void>` | Real `.xlsx` export (styled, multi-sheet, lazy-loaded). Accepts `groupedRows` for outlined grouped reports (v2.1+). |
 | `printGrid(rows, cols, title \| options)` | `void` | Opens browser print dialog. |
 
 ---
 
+## 🧩 Standalone Components
+
+| Component | Description |
+| :--- | :--- |
+| `ColumnVisibilityPanel` | Controlled column show/hide (and optional reorder) list, for use outside the grid (v2.1+). Props: `ColumnVisibilityPanelProps`. See [Column Visibility](components/column-visibility.md). |
+
+---
+
 ## 🎨 Theming & Styling
 
 ### `DataGridThemeProvider`

package/docs/components/column-visibility.md

@@ -12,26 +12,50 @@ The `ColumnVisibilityPanel` provides an interactive list for users to toggle the
 
 ## 🛠️ Usage
 
-### Toolbar Integration
-The most common way to use the visibility panel is within a dropdown menu in the grid's toolbar.
+The grid's toolbar and header menu already include this panel. Import it yourself (exported since v2.1) only when you want the list somewhere else, such as a sidebar or modal. It is a controlled component: you own the visibility model and pass it in.
 
 ```tsx
-import { ColumnVisibilityPanel } from '@opencorestack/opengridx';
-
-// In your Toolbar component
-<Dropdown content={<ColumnVisibilityPanel />}>
-  <button>Columns</button>
-</Dropdown>
+import { useMemo, useState } from 'react';
+import { DataGrid, ColumnVisibilityPanel } from '@opencorestack/opengridx';
+import type { GridColDef } from '@opencorestack/opengridx';
+
+function Report({ rows, columns }: { rows: Row[]; columns: GridColDef<Row>[] }) {
+  const [visibility, setVisibility] = useState<Record<string, boolean>>({});
+  const visibleColumns = useMemo(
+    () => new Set(columns.filter(c => visibility[c.field] !== false).map(c => c.field)),
+    [columns, visibility],
+  );
+  const setAll = (visible: boolean) =>
+    setVisibility(Object.fromEntries(columns.filter(c => c.hideable !== false).map(c => [c.field, visible])));
+
+  return (
+    <div style={{ display: 'flex' }}>
+      <aside className="my-column-sidebar">
+        <ColumnVisibilityPanel
+          columns={columns}
+          visibleColumns={visibleColumns}
+          onVisibilityChange={(field, isVisible) => setVisibility(v => ({ ...v, [field]: isVisible }))}
+          onShowAll={() => setAll(true)}
+          onHideAll={() => setAll(false)}
+        />
+      </aside>
+      <DataGrid rows={rows} columns={columns} columnVisibilityModel={visibility} onColumnVisibilityModelChange={setVisibility} />
+    </div>
+  );
+}
 ```
 
-### Direct Integration
-You can also render it persistently beside the grid or within a custom modal.
+### Props (`ColumnVisibilityPanelProps`)
 
-```tsx
-<div className="my-column-sidebar">
-  <ColumnVisibilityPanel />
-</div>
-```
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `columns` | `GridColDef[]` | Columns to list |
+| `visibleColumns` | `Set<string>` | Fields currently visible |
+| `onVisibilityChange` | `(field, isVisible) => void` | Toggle one column |
+| `onShowAll` / `onHideAll` | `() => void` | Bulk actions (only `hideable` columns are affected) |
+| `onColumnReorder` | `(fromField, toField) => void` | Optional — enables drag-to-reorder in the list |
+| `onColumnOrderReset` | `() => void` | Optional — shows a reset-order action |
+| `showNonHideableColumns` | `boolean` | Show `hideable: false` columns as disabled rows. Default `false` |
 
 ---
 
@@ -47,7 +71,7 @@ You can also render it persistently beside the grid or within a custom modal.
 
 ## 🎨 Controlling Visibility Programmatically
 
-The column visibility panel is an internal component; it cannot be replaced via the slots API. Use the controlled props to drive visibility from outside:
+The built-in panel cannot be replaced through the slots API. To drive visibility from outside, use the controlled props, optionally together with a standalone `ColumnVisibilityPanel` as shown above:
 
 ```tsx
 <DataGrid

package/docs/components/datagrid.md

@@ -35,6 +35,7 @@ function MyGrid() {
 | `paginationModel` | `GridPaginationModel` | — | Controlled pagination state (`{ page, pageSize }`). Omit for uncontrolled; use `initialState` to set the initial page/pageSize. |
 | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. |
 | `initialState` | `GridInitialState` | `undefined` | Initial configuration (sorting, columns, pagination, etc). |
+| `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
 
 ## 🔃 Sorting
 

package/docs/customization/slots-api.md

@@ -113,30 +113,42 @@ function CustomLoader() {
 ```
 
 ### 5. `footer`
-Replace the entire footer section (including pagination).
+Replace the entire footer section below the grid, including the default pagination. Rendered whenever the slot is set, including while row grouping is active.
 
 **Props received:**
 ```typescript
 {
-  // Any props from slotProps.footer
+  apiRef: React.MutableRefObject<GridApi>;
+  aggregationModel: GridAggregationModel;
+  aggregationResult: GridAggregationResult | null;  // null when no aggregationModel
+  rowCount: number;              // filtered rows (leaf rows when grouping)
+  pagination: boolean;           // effective: false while row grouping is active
+  paginationModel: GridPaginationModel;
+  pageSizeOptions: number[];
+  onPaginationModelChange: (model: GridPaginationModel) => void;
+  // ...plus any props from slotProps.footer
 }
 ```
 
-**Example:**
+**Example — a persistent grand-total bar that stays in sync with filtering:**
 ```tsx
-function CustomFooter() {
+function TotalsFooter({ aggregationResult, rowCount }: Record<string, unknown>) {
+  const totals = aggregationResult as Record<string, number> | null;
   return (
     <div style={{ padding: '12px', borderTop: '1px solid #e0e0e0' }}>
-      <span>Custom footer content</span>
+      {String(rowCount)} rows · Total: {totals?.amount ?? '—'}
     </div>
   );
 }
 
 <DataGrid
-  slots={{ footer: CustomFooter }}
+  aggregationModel={{ amount: 'sum' }}
+  slots={{ footer: TotalsFooter }}
 />
 ```
 
+> `noRowsOverlay`, `loadingOverlay` and `footer` were declared in the types before v2.1 but never rendered. They are wired from v2.1.
+
 ## Complete Example
 
 ```tsx

package/docs/features/export-guide.md

@@ -47,7 +47,7 @@ exportToCsv(rows, columns, {
   includeHeaders: true,
   delimiter: ',',
   selectedRows: [1, 2, 3],           // export only these IDs
-  aggregationResult: aggResult,       // adds SUM/AVG totals row
+  aggregationResult: aggResult,       // adds two rows: function labels (SUM/AVG), then values
   aggregationModel: { salary: 'sum' },
 });
 ```
@@ -60,7 +60,7 @@ exportToCsv(rows, columns, {
 | `includeHeaders` | `boolean` | `true` | Include column header row |
 | `delimiter` | `string` | `','` | Field delimiter |
 | `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
-| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `aggregationResult` | `object \| null` | — | Appends two rows after the data: a function-label row (`SUM`, `AVG`…) then a values row |
 | `aggregationModel` | `object \| null` | — | Labels for aggregation row |
 
 ---
@@ -89,7 +89,7 @@ exportToExcel(rows, columns, {
 | `sheetName` | `string` | `'Sheet1'` | Sheet tab name |
 | `includeHeaders` | `boolean` | `true` | Include column header row |
 | `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
-| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `aggregationResult` | `object \| null` | — | Appends two rows after the data: a function-label row (`SUM`, `AVG`…) then a values row |
 | `aggregationModel` | `object \| null` | — | Labels for aggregation row |
 
 ---
@@ -163,6 +163,9 @@ await exportToExcelAdvanced(rows, columns, {
 | `aggregationResult` | `object \| null` | — | Aggregation totals |
 | `aggregationModel` | `object \| null` | — | Aggregation function labels |
 | `selectedRows` | `(string\|number)[]` | — | IDs for `rows: 'selected'` sheets |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Grouped structure from `apiRef.current.getGroupedExportRows()` (v2.1+). See [Grouped export](#grouped-export-to-advanced-excel) |
+| `groupHeaderFillColor` | `string` | `'#e8eaf6'` | Group-header row fill (grouped export) |
+| `groupSubtotalFillColor` | `string` | `'#f0f4ff'` | Group-subtotal row fill (grouped export) |
 
 ### `ExcelSheetDefinition`
 
@@ -187,6 +190,22 @@ await exportToExcelAdvanced(rows, columns, {
 | `imageWidth` | `number` | Width of embedded image (px, default: 40) |
 | `imageHeight`| `number` | Height of embedded image (px, default: 40) |
 
+### Grouped export to advanced Excel
+
+Since v2.1, pass the grid's grouped structure to keep number formats, styling and summary sheets on grouped reports:
+
+```tsx
+await exportToExcelAdvanced(rows, columns, {
+  fileName: 'sales-by-region.xlsx',
+  groupedRows: apiRef.current.getGroupedExportRows() ?? undefined,
+  aggregationModel,
+  aggregationResult: apiRef.current.getAggregationResult(),
+  columnStyles: { amount: { numFmt: '$#,##0.00' } },
+});
+```
+
+Sheets with `rows: 'all'` are written in grouped order: a bold group-header row (label from the column's `groupingValueFormatter`, else `"Header: value"`), the leaf rows, a `Subtotal` row per group, and a final `Grand Total`. Rows use Excel's native outlining, so users can collapse groups in Excel. Subtotal and total values are written as numbers so `columnStyles[field].numFmt` applies. A `grand-total` entry replaces the sheet's `includeSummary` rows, so totals are not duplicated. `rows: 'selected'` sheets ignore `groupedRows` and export flat.
+
 ### Summary Sheet
 
 Pass `{ type: 'summary', name: 'My Sheet' }` in `sheets` to add a standalone aggregation sheet:

package/docs/features/sorting-pagination.md

@@ -62,6 +62,8 @@ Disable sorting for specific columns in `GridColDef`:
 
 OpenGridX supports standard page-based pagination and infinite scrolling.
 
+> **Pagination is ignored while row grouping is active.** When `rowGroupingModel` is non-empty the grid renders all groups in one scrollable, virtualized view and does not show the pager, even if `pagination` is set. A development-mode `console.warn` flags this combination. Give a grouped grid a bounded height so virtualization limits what renders; see [Virtualization](./virtualization.md#the-grid-needs-a-bounded-height).
+
 ### Usage
 ```tsx
 <DataGrid

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

@@ -17,10 +17,17 @@ Row grouping allows you to categorize rows based on common column values.
 ```
 
 ### Features
-- **Multi-Level Groups**: Nest data as deeply as needed.
+- **Multi-Level Groups**: Nest data as deeply as needed — one level per field in `rowGroupingModel`, in order.
 - **Aggregation Integration**: Summarize values automatically for each group level.
 - **Expansion Control**: Control which groups are expanded by default.
 
+### 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.
+- **`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).
+
 ---
 
 ## 🌿 Tree Data

package/docs/features/virtualization.md

@@ -18,7 +18,7 @@ The grid calculates which rows are visible based on:
 - Current scroll position
 - Viewport height
 - Row height (fixed or variable)
-- Overscan buffer (default: 5 rows)
+- Overscan buffer (adaptive, minimum `overscanRowCount`, default 3 rows)
 
 ```tsx
 // Example: 1000 rows, but only ~15 rendered at a time
@@ -29,7 +29,7 @@ The grid calculates which rows are visible based on:
 />
 ```
 
-**Performance characteristics:**
+**Performance characteristics** (when the grid has a bounded height — see below):
 - ✅ Renders ~15-25 rows regardless of total dataset size
 - ✅ Constant memory usage
 - ✅ Smooth 60fps scrolling
@@ -37,7 +37,35 @@ The grid calculates which rows are visible based on:
 
 ### Column Virtualization
 
-Currently, the DataGrid renders all columns. Column virtualization (rendering only visible columns) is planned for future releases.
+Unpinned columns are virtualized horizontally: only the columns in view plus 6 on each side are rendered, with spacer cells standing in for the rest. Pinned columns are always rendered.
+
+### The grid needs a bounded height
+
+Virtualization renders as many rows as fit in the grid's viewport. If the grid's container has no bounded height, the viewport grows to fit **every** row, so every row is rendered. Nothing errors; the grid just stops virtualizing.
+
+The most common cause is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
+
+```tsx
+// ❌ Grows to fit all rows — virtualization is effectively off
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <div style={{ flex: 1 }}>
+    <DataGrid rows={rows} columns={columns} height="100%" />
+  </div>
+</div>
+
+// ✅ Bounded — only visible rows render
+<div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+  <div style={{ flex: 1, minHeight: 0 }}>
+    <DataGrid rows={rows} columns={columns} height="100%" />
+  </div>
+</div>
+```
+
+`height="100%"` only helps if every ancestor up to a fixed-height element also has a definite height.
+
+In development builds the grid logs a `console.warn` when it detects that it is rendering every row of a dataset larger than 200 rows because its viewport is unbounded.
+
+Pagination can hide this problem, because a paginated grid only has one page of rows to render. Row grouping switches pagination off (see below), so an unbounded container that looked fine with pagination can freeze the tab once grouping is enabled.
 
 ## Configuration
 
@@ -84,16 +112,37 @@ Disable virtualization for small datasets:
 
 ### Overscan Buffer
 
-The overscan buffer determines how many extra rows are rendered outside the viewport. A larger buffer provides smoother scrolling but uses more memory.
+The overscan buffer determines how many extra rows are rendered outside the viewport. The grid adapts this buffer automatically based on scroll velocity so fast scrolls never produce blank flashes.
+
+**Adaptive algorithm (`useGridScrollSync`):**
+- Scroll velocity (px/ms) is measured on every scroll event
+- The overscan tier is chosen from the table below and applied immediately
+- 200 ms after scrolling stops the buffer decays back to `overscanRowCount`
+
+| Velocity (px/ms) | Overscan rows |
+|---|---|
+| < 0.5 | 3 |
+| 0.5 – 3 | 5 |
+| 3 – 15 | 12 |
+| 15 – 40 | 20 |
+| > 40 | 30 |
+
+**Configuring the floor:**
+
+```tsx
+// Never render fewer than 5 rows outside the viewport
+<DataGrid
+  rows={rows}
+  columns={columns}
+  overscanRowCount={5}
+/>
+```
 
-**Current implementation:**
-- Default overscan: **5 rows** (above and below viewport)
-- Total rendered rows: ~(viewport rows + 10)
+`overscanRowCount` (default `3`) sets the minimum — the adaptive algorithm always produces a value ≥ this floor.
 
 **Trade-offs:**
-- **Smaller overscan (1-3)**: Less memory, potential flickering during fast scrolling
-- **Larger overscan (5-8)**: More memory, smoother fast scrolling
-- **Very large overscan (10+)**: Diminishing returns, wasted rendering
+- **Smaller floor (1-3)**: Less idle memory, relies on adaptive headroom for fast scrolls
+- **Larger floor (5-8)**: Pre-renders more rows at rest, trades memory for smoother slow scrolls
 
 ### Scroll Performance
 
@@ -136,7 +185,7 @@ When using detail panels, row heights become variable. The grid automatically:
 
 ## Virtualization with Grouping/Tree Data
 
-Row grouping and tree data work seamlessly with virtualization:
+Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium by `DataGrid.virtualization.browser.test.tsx`).
 
 ```tsx
 // Tree data with virtualization
@@ -149,7 +198,7 @@ Row grouping and tree data work seamlessly with virtualization:
 />
 ```
 
-**Note:** When groups are collapsed, only visible rows are rendered. Expanding a group dynamically adds rows to the render list.
+**Note:** `pagination` is ignored while `rowGroupingModel` is active, so a grouped grid relies entirely on virtualization to bound what it renders. Make sure its container has a bounded height. A development-mode warning is logged if `pagination` is passed together with `rowGroupingModel`.
 
 ## Debugging Virtualization
 
@@ -171,14 +220,14 @@ You should see console logs only for visible rows + overscan buffer.
 
 ## Known Limitations
 
-1. **Column virtualization** - Not yet implemented (all columns are rendered)
+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
 
 ## Future Improvements
 
-- [ ] Column virtualization for grids with 50+ columns
-- [ ] Adaptive overscan based on scroll velocity
+- [x] Column virtualization (unpinned columns, 6-column overscan)
+- [x] Adaptive overscan based on scroll velocity (`overscanRowCount` prop, v2.0.4)
 - [ ] Virtual scrollbar for extremely large datasets (millions of rows)
 - [ ] Intersection Observer API for better scroll detection
 
@@ -187,9 +236,9 @@ You should see console logs only for visible rows + overscan buffer.
 | Feature | OpenGridX | MUI X DataGrid |
 |---------|--------------|----------------|
 | Row virtualization | ✅ Yes | ✅ Yes |
-| Column virtualization | ❌ Planned | ✅ Yes (Pro) |
+| Column virtualization | ✅ Yes (unpinned columns) | ✅ Yes (Pro) |
 | Variable row heights | ✅ Yes | ✅ Yes |
-| Overscan buffer | 5 rows | 3-8 rows (adaptive) |
+| Overscan buffer | 3–30 rows (adaptive, velocity-based) | 3-8 rows (adaptive) |
 | Max recommended rows | 100,000+ | 100,000+ |
 
 ## Related Documentation

package/docs/roadmap.md

@@ -5,7 +5,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 ## ✅ Implemented Features
 
 ### Core
-*   **Virtualization**: High-performance row virtualization for handling large datasets. Column virtualization is planned (currently all columns are rendered).
+*   **Virtualization**: Row virtualization plus horizontal virtualization of unpinned columns. Requires a bounded grid height (see `docs/features/virtualization.md`).
 *   **Sorting**: Client-side and server-side multi-column sorting.
 *   **Filtering**: Client-side filtering with support for various operators.
 *   **Pagination**: Client-side and server-side pagination with customizable page sizes.
@@ -74,21 +74,27 @@ This document tracks the current status of features in `OpenGridX` and outlines
 
 ### Advanced Data Features
 *   **Interactive Pivot Builder**: Drag-and-drop UI for users to dynamically create pivot tables.
-*   **Native PDF Reporting**: Automated PDF generation with customizable layouts.
 *   **Advanced Charts Integration**: Inline sparklines and trend visualization.
 
-### DX & Publishing
-*   **npm publish**: Finalize `package.json` metadata, `README.md`, and publish to npm registry.
-
 ### Demo Site
 *   **Full source viewer coverage**: Migrate all 32 examples to `DocsLayout` using Vite `?raw` auto-loading (eliminates string-literal source maintenance). See `docs/superpowers/plans/2026-07-29-demo-app-refactor.md`.
 *   **Syntax highlighting**: Prism.js token-based highlighting in the source viewer.
-*   **GitHub Pages deployment**: CI/CD via GitHub Actions (`base: '/OpenGridX/'` already configured in `vite.config.js`).
 
 ## ✅ Implemented Features (Recent)
 
+### Consumer defect fixes *(v2.1.0, 2026-09-23)*
+- Row-grouping subtotals now use the shared aggregation functions (nulls ignored, `unique` supported, `availableAggregationFunctions` honoured); `min`/`max` no longer overflow the call stack on very large datasets.
+- Group and tree-data expansion state survives row updates, including server-side lazily loaded children.
+- Rows are positioned correctly when rows are pinned to the top; keyboard navigation and `scrollToIndexes` keep the target row fully visible below the sticky header.
+- `valueFormatter` applies under row grouping; `formattedValue` is passed to `renderCell`.
+- `slots.footer`, `slots.noRowsOverlay` and `slots.loadingOverlay` are rendered (they were typed but ignored).
+- New `onRowDoubleClick`; `ColumnVisibilityPanel` exported; `exportToExcelAdvanced` accepts `groupedRows`.
+- Dev-mode warnings for an unbounded grid container and for `pagination` with row grouping.
+- Real-browser test project (Vitest browser mode + Playwright/Chromium), `npm run test:browser`; the npm publish workflow now runs unit and browser tests before publishing.
+- Already shipped, previously listed as upcoming: npm publishing (since 0.1.0), native PDF export (v1.2.1), GitHub Pages deployment.
+
 ### Library Hardening *(completed 2026-09-02)*
-- **`GridRowMeta`**: Hierarchy metadata (`hasChildren`, `treeDepth`, `groupingField`, `groupingValue`, `descendantCount`, `isExpanded`, `isGroupRow`) moved from `GridRowModel` into a separate `Map<GridRowId, GridRowMeta>`. Exposed as `params.rowMeta` in `renderCell`. Runtime shim maintains backward compatibility; removed in v2.0.
+- **`GridRowMeta`**: Hierarchy metadata (`hasChildren`, `treeDepth`, `groupingField`, `groupingValue`, `descendantCount`, `isExpanded`, `isGroupRow`) moved from `GridRowModel` into a separate `Map<GridRowId, GridRowMeta>`. Exposed as `params.rowMeta` in `renderCell`. Runtime shim (underscore-prefixed fields on the row object) maintains backward compatibility; still present as of v2.1.0, deprecated for removal in a future major version — see `docs/architecture/grid-row-meta.md`.
 - **`CellErrorBoundary`**: Custom `renderCell` errors are now caught per-cell. Failing cells show a `⚠` indicator with the error as a tooltip; the rest of the grid renders normally.
 - **`GridLocaleText` / `localeText` prop**: All user-visible pagination strings (`paginationRowsPerPage`, `paginationOf`, `paginationPage`, `noRowsLabel`) are now overrideable for internationalisation.
 - **Core hook tests**: `useGridRowPipeline`, `useGridControlledState`, `useGridKeyboardNavigation` now have full test coverage (25 new tests).

package/lib/components/Cell/Cell.tsx

@@ -244,6 +244,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
                         resetKey={row}
                         renderFn={() => colDef.renderCell!({
                             value,
+                            formattedValue,
                             row,
                             field: colDef.field,
                             colDef,

package/lib/components/DataGrid/DataGrid.css

@@ -122,6 +122,13 @@
   color: var(--ogx-color-gray-300);
 }
 
+.ogx__loading-overlay {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 200px;
+}
+
 .ogx-error-overlay {
   position: absolute;
   top: 0;

package/lib/components/DataGrid/DataGrid.defects.test.tsx

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { DataGrid } from './DataGrid';
+import type { GridColDef } from '../../types';
+
+// Regression tests for the OpenGridX 2.0.4 consumer defect report.
+
+type Row = { id: number; region: string; amount: number };
+
+const ROWS: Row[] = [
+    { id: 1, region: 'North', amount: 1200 },
+    { id: 2, region: 'North', amount: 800 },
+    { id: 3, region: 'South', amount: 450 },
+];
+
+const COLUMNS: GridColDef<Row>[] = [
+    { field: 'region', headerName: 'Region', width: 150 },
+    { field: 'amount', headerName: 'Amount', width: 150, valueFormatter: ({ value }) => `$${String(value)}` },
+];
+
+describe('D3 — valueFormatter survives row grouping', () => {
+    it('renders formatted values without grouping', () => {
+        render(<DataGrid rows={ROWS} columns={COLUMNS} />);
+        expect(screen.getByText('$1200')).toBeInTheDocument();
+    });
+
+    it('renders formatted values for leaf rows when rowGroupingModel is active', () => {
+        render(<DataGrid rows={ROWS} columns={COLUMNS} rowGroupingModel={['region']} defaultGroupingExpansionDepth={-1} />);
+        expect(screen.getByText('$1200')).toBeInTheDocument();
+        expect(screen.queryByText('1200')).not.toBeInTheDocument();
+    });
+
+    it('passes formattedValue to a consumer renderCell', () => {
+        const renderCell = vi.fn(() => null);
+        const cols: GridColDef<Row>[] = [COLUMNS[0], { ...COLUMNS[1], renderCell }];
+        render(<DataGrid rows={ROWS} columns={cols} />);
+        expect(renderCell).toHaveBeenCalledWith(expect.objectContaining({ value: 1200, formattedValue: '$1200' }));
+    });
+});
+
+describe('D2 — slots that were typed but never rendered', () => {
+    it('renders slots.footer with grid state, replacing the default pagination', () => {
+        const Footer = vi.fn((props: Record<string, unknown>) => <div data-testid="footer">rows:{String(props.rowCount)} note:{String(props.note)}</div>);
+        render(
+            <DataGrid
+                rows={ROWS}
+                columns={COLUMNS}
+                pagination
+                aggregationModel={{ amount: 'sum' }}
+                slots={{ footer: Footer }}
+                slotProps={{ footer: { note: 'hi' } }}
+            />
+        );
+        expect(screen.getByTestId('footer')).toHaveTextContent('rows:3 note:hi');
+        expect(Footer).toHaveBeenCalledWith(expect.objectContaining({ aggregationResult: { amount: 2450 } }), undefined);
+        expect(document.querySelector('.ogx-pagination, .ogx__pagination')).toBeNull();
+    });
+
+    it('renders slots.noRowsOverlay when there are no rows', () => {
+        render(<DataGrid rows={[]} columns={COLUMNS} slots={{ noRowsOverlay: () => <div>Nothing here</div> }} />);
+        expect(screen.getByText('Nothing here')).toBeInTheDocument();
+    });
+
+    it('renders slots.loadingOverlay while loading with no rows', () => {
+        render(<DataGrid rows={[]} columns={COLUMNS} loading slots={{ loadingOverlay: () => <div>Fetching…</div> }} />);
+        expect(screen.getByText('Fetching…')).toBeInTheDocument();
+    });
+});
+
+describe('D6 — onRowDoubleClick', () => {
+    it('fires with the row params on double-click', () => {
+        const onRowDoubleClick = vi.fn();
+        render(<DataGrid rows={ROWS} columns={COLUMNS} onRowDoubleClick={onRowDoubleClick} />);
+        fireEvent.doubleClick(screen.getByText('$800'));
+        expect(onRowDoubleClick).toHaveBeenCalledWith(expect.objectContaining({ id: 2, row: ROWS[1] }));
+    });
+
+    it('fires in list view as well', () => {
+        const onRowDoubleClick = vi.fn();
+        render(
+            <DataGrid rows={ROWS} columns={COLUMNS} listView
+                listViewColumn={{ field: 'card', renderCell: ({ row }) => <span>card-{row.id}</span> }}
+                onRowDoubleClick={onRowDoubleClick} />
+        );
+        fireEvent.doubleClick(screen.getByText('card-3'));
+        expect(onRowDoubleClick).toHaveBeenCalledWith(expect.objectContaining({ id: 3, row: ROWS[2] }));
+    });
+});
+
+describe('Row grouping — expansion survives row edits', () => {
+    it('keeps a user-expanded group open when the rows prop changes', () => {
+        const { rerender, container } = render(<DataGrid rows={ROWS} columns={COLUMNS} rowGroupingModel={['region']} />);
+        const rowCount = () => container.querySelectorAll('.ogx__rows [role="row"]').length;
+        expect(rowCount()).toBe(2);
+
+        fireEvent.click(container.querySelector('.ogx__rows [role="row"]')!);
+        expect(rowCount()).toBe(4);
+
+        rerender(<DataGrid rows={ROWS.map(r => (r.id === 1 ? { ...r, amount: 1300 } : r))} columns={COLUMNS} rowGroupingModel={['region']} />);
+        expect(rowCount()).toBe(4);
+        expect(screen.getByText('$1300')).toBeInTheDocument();
+    });
+});