@opencorestack/opengridx 2.0.4 → 3.0.0

package/docs/components/tooltip.md

@@ -1,10 +1,10 @@
 # `<GridTooltip />`
 
-The `GridTooltip` component provides a lightweight, accessible tooltip for any HTML or React element. It is commonly used within columns, actions, or toolbars to display extra information when a user hovers over a component.
+The `GridTooltip` component provides a lightweight, accessible tooltip for any HTML or React element. It is commonly used within columns, actions, or toolbars to display extra information when a user hovers over or focuses a component.
 
 ## 📑 Overview
-- **Portal Rendering**: Tooltips are rendered at the end of `document.body` for unobstructed positioning.
-- **Dynamic Calculation**: Tooltips calculate their placement relative to the target element on hover.
+- **Portal Rendering**: Tooltips are portalled into the closest `DataGridThemeProvider` (`.ogx-theme-provider`), so they use the theme's overlay colours like the grid's menus and panels, or into `document.body` outside a provider. They are `position: fixed` and follow the target when the page or a container scrolls.
+- **Dynamic Calculation**: Tooltips calculate their placement relative to the target element when they open.
 - **Support for React Elements**: It wraps its child element to attach event listeners and calculate position.
 - **Customizable Delays**: Support for `enterDelay` and `leaveDelay`.
 
@@ -36,6 +36,14 @@ You can choose from four different placements: `top`, `bottom`, `left`, or `righ
 <GridTooltip title="Bottom Placement" placement="bottom">
   <span>Hover me</span>
 </GridTooltip>
+
+<GridTooltip title="Left Placement" placement="left">
+  <span>Hover me</span>
+</GridTooltip>
+
+<GridTooltip title="Right Placement" placement="right">
+  <span>Hover me</span>
+</GridTooltip>
 ```
 
 ---
@@ -47,8 +55,8 @@ You can choose from four different placements: `top`, `bottom`, `left`, or `righ
 | **`title`** | `React.ReactNode` | — | Content (text, JSX, etc.) to show inside the tooltip. |
 | **`children`** | `React.ReactElement` | — | The target element the tooltip is attached to. |
 | **`placement`** | `'top'`, `'bottom'`, `'left'`, `'right'` | `'top'` | Direction where the tooltip appears. |
-| **`enterDelay`** | `number` | `200` | Delay (ms) before showing the tooltip. |
-| **`leaveDelay`** | `number` | `0` | Delay (ms) before hiding the tooltip. |
+| **`enterDelay`** | `number` | `200` | Delay (ms) before showing the tooltip on hover or focus. |
+| **`leaveDelay`** | `number` | `0` | Delay (ms) before hiding the tooltip on mouse leave or blur. |
 
 ---
 
@@ -61,5 +69,6 @@ The internal tooltip component is not replaceable via the slots API. For column-
 ```
 
 ## 📝 Accessibility
-- Tooltips are triggered by mouse hover events (`onMouseEnter`/`onMouseLeave`).
-- It is recommended to use descriptive `aria-label` tags on the child element for screen readers, as tooltips are visually focused.
+- The tooltip opens on hover and on keyboard focus of the child (focus events bubble to the wrapper), and closes on mouse leave, blur or Escape.
+- The open tooltip has `role="tooltip"` and an id, and the child's `aria-describedby` references it (added to any `aria-describedby` the child already has) while it is open.
+- The tooltip describes its child; it does not name it. Icon-only buttons still need an `aria-label`.

package/docs/customization/slots-api.md

@@ -4,57 +4,85 @@ The Slots API allows you to replace any built-in component in the DataGrid with
 
 ## Available Slots
 
+Every slot is typed `React.ComponentType<Record<string, unknown>>`, and every `slotProps` entry is `Record<string, unknown>`. A slot component therefore takes `props: Record<string, unknown>` and narrows the props it uses; the examples below cast to a type alias describing the props the grid passes. (A component declared with its own required props, such as `(props: { page: number }) => …`, is rejected by TypeScript.) The props from `slotProps.<slot>` are spread last, so they can override the grid's props.
+
 ### 1. `toolbar`
 Add a custom toolbar above the grid (commonly used for export buttons, filters, actions).
 
 **Props received:**
 ```typescript
 {
-  // Any props from slotProps.toolbar
+  apiRef: React.MutableRefObject<GridApi>;
+  columns: GridColDef[];                 // every column in display order, hidden ones included
+  baseColumns: GridColDef[];             // the `columns` prop as passed
+  aggregationModel: GridAggregationModel;
+  onAggregationModelChange: (model: GridAggregationModel) => void;
+  pivotModel?: GridPivotModel;           // only when pivotMode, pivotModel or onPivotModelChange is set
+  onPivotModelChange?: (model: GridPivotModel) => void;
+  filterModel: GridFilterModel;
+  onFilterModelChange: (model: GridFilterModel) => void;
+  columnVisibilityModel: GridColumnVisibilityModel;
+  onColumnVisibilityModelChange: (model: GridColumnVisibilityModel) => void;
+  onColumnReorder?: (fromField: string, toField: string) => void;  // undefined with disableColumnReorder
+  onColumnOrderReset?: () => void;                                 // undefined with disableColumnReorder
+  forceColumnsOpen: boolean;             // the column menu's "Manage columns" asked for the Columns panel
+  onColumnsPanelClose: () => void;
+  // ...plus any props from slotProps.toolbar
 }
 ```
 
+These match `GridToolbarProps`, so `slots={{ toolbar: GridToolbar }}` gives the built-in toolbar.
+
 **Example:**
 ```tsx
-import { exportToCsv, exportToExcel } from '@opencorestack/opengridx';
+import { DataGrid, exportToCsv, exportToExcel, type GridApi, type GridColDef } from '@opencorestack/opengridx';
+import type { MutableRefObject } from 'react';
+
+type ToolbarSlotProps = { apiRef: MutableRefObject<GridApi>; columns: GridColDef[] };
 
-function CustomToolbar({ rows, columns }) {
+function CustomToolbar(props: Record<string, unknown>) {
+  const { apiRef, columns } = props as ToolbarSlotProps;
+  const exportRows = () => apiRef.current.getAllFilteredRows();
   return (
     <div style={{ padding: '12px', display: 'flex', gap: '8px' }}>
-      <button onClick={() => exportToCsv(rows, columns)}>
+      <button type="button" onClick={() => exportToCsv(exportRows(), columns)}>
         Export CSV
       </button>
-      <button onClick={() => exportToExcel(rows, columns)}>
+      <button type="button" onClick={() => exportToExcel(exportRows(), columns)}>
         Export Excel
       </button>
     </div>
   );
 }
 
-<DataGrid
-  slots={{ toolbar: CustomToolbar }}
-  slotProps={{ toolbar: { rows, columns } }}
-/>
+<DataGrid rows={rows} columns={columns} slots={{ toolbar: CustomToolbar }} />
 ```
 
+`toolbar` accepts any React component type: function, class, `React.memo`, `forwardRef` or `lazy`. A plain function toolbar may be defined inline inside your own component: the grid keys it on its source code, so it keeps its state (open panels, typed search) when your component re-renders and remounts only when you pass a toolbar with different code. A class, memo or forwardRef toolbar is rendered as a normal element, so define it outside render to keep its identity stable.
+
 ### 2. `pagination`
-Replace the default pagination component.
+Replace the default pagination component. It is rendered only while pagination is in effect (`pagination` set, no row grouping, `paginationMode` not `"infinite"`), is not rendered when a `footer` slot is set, and is used by list view too.
 
 **Props received:**
 ```typescript
 {
-  page: number;                    // Current page (0-based)
+  page: number;                    // Current page (0-based), clamped to the last page client-side
   pageSize: number;                // Current page size
-  rowCount: number;                // Total number of rows
-  pageSizeOptions: number[];       // Available page sizes
+  rowCount: number;                // Rows being paged: filtered, unpinned rows; the server total in paginationMode="server"
+  pageSizeOptions: number[];       // Available page sizes (default [10, 25, 50, 100])
   onPageChange: (page: number) => void;
-  onPageSizeChange: (size: number) => void;
+  onPageSizeChange: (size: number) => void;   // also resets to page 0
+  localeText?: Pick<GridLocaleText, 'paginationRowsPerPage' | 'paginationOf' | 'paginationPage'>;  // only when the localeText prop is set
+  // ...plus any props from slotProps.pagination
 }
 ```
 
 **Example:**
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
+  pagination
   slots={{ pagination: CustomPagination }}
   slotProps={{ pagination: { customProp: 'value' } }}
 />
@@ -66,7 +94,7 @@ Replace the empty state shown when there are no rows.
 **Props received:**
 ```typescript
 {
-  // Any props from slotProps.noRowsOverlay
+  // Only the props from slotProps.noRowsOverlay
 }
 ```
 
@@ -82,6 +110,8 @@ function CustomNoRows() {
 }
 
 <DataGrid
+  rows={rows}
+  columns={columns}
   slots={{ noRowsOverlay: CustomNoRows }}
 />
 ```
@@ -92,7 +122,7 @@ Replace the loading state overlay.
 **Props received:**
 ```typescript
 {
-  // Any props from slotProps.loadingOverlay
+  // Only the props from slotProps.loadingOverlay
 }
 ```
 
@@ -108,44 +138,79 @@ function CustomLoader() {
 }
 
 <DataGrid
+  rows={rows}
+  columns={columns}
+  loading={isLoading}
   slots={{ loadingOverlay: 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, except in list view.
 
-**Props received:**
+**Props received** (`GridFooterSlotProps`, v3.0+):
 ```typescript
 {
-  // Any props from slotProps.footer
+  apiRef: React.MutableRefObject<GridApi>;
+  aggregationModel: GridAggregationModel;
+  aggregationResult: GridAggregationResult | null;  // null when aggregationModel is empty, and in pivot mode
+  rowCount: number;              // see below
+  pagination: boolean;           // effective: false while row grouping is active or with paginationMode="infinite"
+  paginationModel: GridPaginationModel;   // the model as held (not clamped to the last page)
+  pageSizeOptions: number[];
+  onPaginationModelChange: (model: GridPaginationModel) => void;
+  // ...plus any props from slotProps.footer
 }
 ```
 
-**Example:**
+`rowCount` is:
+- with `paginationMode="server"`: the server total (the `dataSource` response's `rowCount`, else the `rowCount` prop, else the number of loaded rows);
+- otherwise, in a flat grid: the pager's `rowCount`, the filtered rows **without** pinned rows (v3.0+; before, pinned rows were counted). With `filterMode="server"` it is every row the grid holds; with `paginationMode="infinite"` the rows loaded so far; in pivot mode the pivot rows including the Grand Total row;
+- under row grouping and tree data: the data rows that pass the client filter (never group rows), whatever is expanded.
+
+**Example — a persistent grand-total bar that stays in sync with filtering:**
 ```tsx
-function CustomFooter() {
+import type { GridFooterSlotProps } from '@opencorestack/opengridx';
+
+// Type the props you read; the grid checks them against GridFooterSlotProps.
+function TotalsFooter({ aggregationResult, rowCount }: Pick<GridFooterSlotProps, 'aggregationResult' | 'rowCount'>) {
+  const total = aggregationResult?.amount;
   return (
     <div style={{ padding: '12px', borderTop: '1px solid #e0e0e0' }}>
-      <span>Custom footer content</span>
+      {rowCount} rows · Total: {typeof total === 'number' ? total.toLocaleString() : '—'}
     </div>
   );
 }
 
 <DataGrid
-  slots={{ footer: CustomFooter }}
+  rows={rows}
+  columns={columns}
+  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
 import { Select, Pagination, Spin, Empty } from 'antd';
 import { DataGrid } from '@opencorestack/opengridx';
 
-function AntdPagination(props) {
-  const { page, pageSize, rowCount, pageSizeOptions, onPageChange, onPageSizeChange } = props;
-  
+type PaginationSlotProps = {
+  page: number;
+  pageSize: number;
+  rowCount: number;
+  pageSizeOptions: number[];
+  onPageChange: (page: number) => void;
+  onPageSizeChange: (pageSize: number) => void;
+};
+
+function AntdPagination(props: Record<string, unknown>) {
+  const { page, pageSize, rowCount, pageSizeOptions, onPageChange, onPageSizeChange } =
+    props as PaginationSlotProps;
+
   return (
     <div style={{ display: 'flex', gap: '16px', padding: '12px 16px', justifyContent: 'flex-end' }}>
       <Select
@@ -199,18 +264,17 @@ function MyApp() {
 
 ## TypeScript Support
 
-For full type safety, define your component props:
+The library exports no props type for the pagination, overlay or footer slots (the toolbar's props are `GridToolbarProps`). Declare a type alias for the props you read and narrow `Record<string, unknown>` to it, as above. Use a `type` alias rather than an `interface`: an interface has no index signature, so `props as MyInterface` needs `as unknown as`.
 
 ```typescript
-import type { PaginationProps } from '@opencorestack/opengridx';
-
-interface CustomPaginationProps extends PaginationProps {
-  customProp?: string;
-}
+type CustomPaginationProps = PaginationSlotProps & {
+  customProp?: string; // from slotProps.pagination
+};
 
-const CustomPagination: React.FC<CustomPaginationProps> = (props) => {
+function CustomPagination(props: Record<string, unknown>) {
+  const { page, customProp } = props as CustomPaginationProps;
   // Your implementation
-};
+}
 ```
 
 ## Best Practices
@@ -223,5 +287,5 @@ const CustomPagination: React.FC<CustomPaginationProps> = (props) => {
 
 ## See Also
 
-- [Custom Pagination Guide](./CUSTOM_PAGINATION.md) - Detailed examples with Ant Design and MUI
-- [DataGrid Props](../src/OpenGridX/types/index.ts) - Full TypeScript definitions
+- [Custom Pagination Guide](../features/custom-pagination.md) - Detailed examples with Ant Design and MUI
+- [DataGrid Props](../../lib/types/index.ts) - Full TypeScript definitions

package/docs/customization/theming.md

@@ -11,6 +11,7 @@ OpenGridX ships with a complete design-token system built on CSS custom properti
 
 ```tsx
 import { DataGrid, DataGridThemeProvider } from '@opencorestack/opengridx';
+import '@opencorestack/opengridx/styles'; // required: the tokens only take effect through the grid's stylesheet
 
 const myTheme = {
   colors: {
@@ -38,11 +39,27 @@ export default function App() {
 
 The `DataGridThemeProvider` resolves each key in the `GridTheme` object to its corresponding `--ogx-*` CSS variable and applies it as an inline style on a wrapper `div`. **No CSS-in-JS, no runtime overhead.**
 
+How the provider builds the variables (v3.0+):
+
+- **It pins a complete palette.** It starts from a full light palette (or a full dark one with `mode: 'dark'`) that sets every colour token, neutral scale included, and then applies your keys on top. A light theme therefore stays light, and readable, when the operating system is in dark mode, and a dark theme needs no other CSS.
+- **Accents follow `colors.primary`.** The toolbar's primary button, active chips, search focus ring, selected menu items, selected rows and the keyboard focus ring are all derived from the `colors.primary*` tokens (with `var()` / `color-mix()`), so a theme that only sets `colors.primary` recolours all of them. Set the specific `toolbar.*`, `overlays.*` or `grid.*` key to override one.
+- **Toolbar tokens follow the grid surface.** Unless you set `toolbar.*`, the toolbar uses the header background, header text and grid border colours.
+- **Row and header heights reach the layout.** `grid.rowHeightStandard` / `grid.headerHeight` (and `rowHeightCompact` / `rowHeightComfortable` with `density`) are read by the grid itself, which virtualizes from them. They must be pixel values (`'36px'` or `'36'`); other units are ignored. The `rowHeight` / `headerHeight` props win over the theme.
+
+> **Sizing:** the wrapper `div` (`.ogx-theme-provider`) is a normal auto-height block. If the grid uses `height="100%"`, pass `style={{ height: '100%' }}` (or a `className` that sets a height) to the provider too. Otherwise the wrapper grows to fit every row and row virtualization is effectively off. See [Virtualization → The grid needs a bounded height](../features/virtualization.md#the-grid-needs-a-bounded-height).
+
 ---
 
 ## Dark Mode
 
-The grid automatically switches to its dark palette via `@media (prefers-color-scheme: dark)`. If your app manages dark mode manually (e.g. via a `data-theme` attribute), override the dark tokens with:
+Without a provider, the grid automatically switches to its dark palette via `@media (prefers-color-scheme: dark)`. Inside a `DataGridThemeProvider` the theme decides instead: `darkTheme` (or any theme with `mode: 'dark'`) is dark and every other theme is light, whatever the operating-system setting. To follow the OS with the provider, pick the theme in your app:
+
+```tsx
+const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+<DataGridThemeProvider theme={prefersDark ? darkTheme : roseTheme}>…</DataGridThemeProvider>
+```
+
+If your app manages dark mode manually without the provider (e.g. via a `data-theme` attribute), override the dark tokens with:
 
 ```css
 [data-theme="dark"] {
@@ -60,20 +77,23 @@ The grid automatically switches to its dark palette via `@media (prefers-color-s
 
 ```ts
 interface GridTheme {
-  colors?:      GridThemeColors;
+  mode?:        'light' | 'dark';     // base palette, default 'light'
+  colors?:      GridThemeColors;      // primary*, secondary*, success/warning/error/info, white, black, gray: { 50…900 }
   typography?:  GridThemeTypography;
   spacing?:     GridThemeSpacing;
   borders?:     GridThemeBorders;
   shadows?:     GridThemeShadows;
-  grid?:        GridThemeGrid;
+  grid?:        GridThemeGrid;        // surfaces, heights (px), cellPaddingX/Y, cellFontSize, headerFontSize, …
   toolbar?:     GridThemeToolbar;
   overlays?:    GridThemeOverlays;
   scrollbar?:   GridThemeScrollbar;
-  skeleton?:    GridThemeSkeleton;
+  skeleton?:    GridThemeSkeleton;    // baseColor, highlightColor
   transitions?: GridThemeTransitions;
 }
 ```
 
+All sub-theme types (`GridThemeColors`, `GridThemeGrayScale`, `GridThemeTypography`, `GridThemeSpacing`, `GridThemeBorders`, `GridThemeShadows`, `GridThemeGrid`, `GridThemeToolbar`, `GridThemeOverlays`, `GridThemeScrollbar`, `GridThemeSkeleton`, `GridThemeTransitions`) are exported from the package.
+
 ---
 
 ## All CSS Tokens
@@ -110,8 +130,8 @@ interface GridTheme {
 
 | Token | Default | Description |
 |---|---|---|
-| `--ogx-font-family` | `'Inter', system-ui, sans-serif` | Primary UI font |
-| `--ogx-font-family-mono` | `'JetBrains Mono', 'Fira Code', monospace` | Monospace (code cells, IDs) |
+| `--ogx-font-family` | `'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', …, sans-serif` | Primary UI font |
+| `--ogx-font-family-mono` | `'JetBrains Mono', 'Fira Code', 'Courier New', Courier, monospace` | Monospace (code cells, IDs) |
 | `--ogx-font-size-xs` | `0.75rem` (12px) | Extra-small |
 | `--ogx-font-size-sm` | `0.875rem` (14px) | Small |
 | `--ogx-font-size-md` | `1rem` (16px) | Medium |
@@ -165,16 +185,16 @@ interface GridTheme {
 
 | Token | Default | Description |
 |---|---|---|
-| `--ogx-row-height` | `52px` | Default row height |
-| `--ogx-header-height` | `56px` | Column header row height |
-| `--ogx-grid-row-height-compact` | `32px` | Compact density preset |
-| `--ogx-grid-row-height-standard` | `52px` | Standard density preset |
-| `--ogx-grid-row-height-comfortable` | `72px` | Comfortable density preset |
-| `--ogx-grid-header-height` | `56px` | Header height (grid-specific) |
+| `--ogx-row-height` | `52px` | Row height. The grid sets it inline on `.ogx` from the `rowHeight` / `density` props (or the provider's `grid.rowHeight*`); read it in custom CSS, don't set it. |
+| `--ogx-header-height` | `56px` | Column header row height; set inline by the grid like `--ogx-row-height`. |
+| `--ogx-grid-row-height-compact` | `32px` | Informational copy of the theme's `grid.rowHeightCompact`; the grid reads the theme value, not this variable |
+| `--ogx-grid-row-height-standard` | `52px` | Informational copy of `grid.rowHeightStandard` |
+| `--ogx-grid-row-height-comfortable` | `72px` | Informational copy of `grid.rowHeightComfortable` |
+| `--ogx-grid-header-height` | `56px` | Informational copy of `grid.headerHeight` |
 | `--ogx-grid-cell-padding-x` | `10px` | Horizontal cell padding |
 | `--ogx-grid-cell-padding-y` | `8px` | Vertical cell padding |
-| `--ogx-grid-cell-font-size` | `13px` | Body cell font size |
-| `--ogx-grid-header-font-size` | `13px` | Header cell font size |
+| `--ogx-grid-cell-font-size` | `13px` | Body cell font size (`grid.cellFontSize`) |
+| `--ogx-grid-header-font-size` | `13px` | Header cell font size (`grid.headerFontSize`) |
 | `--ogx-grid-line-height` | `var(--ogx-line-height-normal)` | Row line height |
 
 ### Grid Colors
@@ -198,6 +218,26 @@ interface GridTheme {
 | `--ogx-checkbox-bg` | — | `#1e293b` | Checkbox background (dark only) |
 | `--ogx-checkbox-border` | — | `#64748b` | Checkbox border (dark only) |
 
+### Toolbar, Overlay and Scrollbar Colors
+
+Read with a fallback, so a grid without a provider looks the same as before. Inside a provider they come from `toolbar.*`, `overlays.*` and `scrollbar.*`, or from the derivations described above.
+
+| Token | Theme key | Default | Used by |
+|---|---|---|---|
+| `--ogx-toolbar-background` / `-text` / `-border` | `toolbar.background` / `text` / `border` | header background / header text / grid border | Toolbar bar |
+| `--ogx-toolbar-btn-bg` / `-btn-hover` / `-btn-text` | `toolbar.buttonBackground` / `buttonHoverBackground` / `buttonText` | transparent / header hover / header text | Toolbar icon buttons |
+| `--ogx-toolbar-btn-primary-bg` / `-hover` / `-text` | `toolbar.buttonPrimary*` | primary / primary-dark / white | Active summary pills |
+| `--ogx-toolbar-btn-danger-bg` / `-hover` / `-text` | `toolbar.buttonDanger*` | red tints | Clear buttons |
+| `--ogx-toolbar-input-bg` / `-text` / `-border` | `toolbar.inputBackground` / `inputText` / `inputBorder` | grid background / row text / gray-300 | Quick search |
+| `--ogx-toolbar-input-focus-border` / `-focus-shadow` | `toolbar.inputFocus*` | primary / 12% primary | Focused quick search |
+| `--ogx-toolbar-chip-bg` / `-text` | `toolbar.chipBackground` / `chipText` | transparent / row text | Summary pills |
+| `--ogx-toolbar-chip-active-bg` / `-text` | `toolbar.chipActive*` | 12% primary / primary-dark | Active pills, filter chips, pivot chips |
+| `--ogx-overlay-*` | `overlays.*` | white surface, gray border | Menus, panels, tooltips |
+| `--ogx-overlay-item-selected-bg` / `-text` | `overlays.itemSelected*` | 8% primary / primary-dark | Selected menu item |
+| `--ogx-overlay-item-danger-bg` / `-text` | `overlays.itemDanger*` | red tints | Remove-condition button in the filter panel |
+| `--ogx-scrollbar-thumb` / `-track` / `-size` | `scrollbar.thumbColor` / `trackColor` / `size` | gray-300 / transparent / 8px | Grid viewport scrollbars |
+| `--ogx-skeleton-base` / `-highlight` | `skeleton.baseColor` / `highlightColor` | light grays | Loading skeleton rows |
+
 ### Transitions
 
 | Token | Default | Description |
@@ -247,17 +287,25 @@ You can theme the grid without the `DataGridThemeProvider` by overriding variabl
 
 ## Built-in Presets
 
-OpenGridX ships with two presets accessible from `'opengridx'`:
+OpenGridX exports five presets as named exports:
 
 ```tsx
-import { DataGridThemeProvider, themes } from '@opencorestack/opengridx';
+import { DataGridThemeProvider, darkTheme } from '@opencorestack/opengridx';
+// Also: roseTheme, emeraldTheme, amberTheme, compactTheme
 
-// Available: themes.light, themes.dark, themes.compact, themes.comfortable
-<DataGridThemeProvider theme={themes.dark}>
+<DataGridThemeProvider theme={darkTheme}>
   <DataGrid ... />
 </DataGridThemeProvider>
 ```
 
+| Preset | What it sets |
+|---|---|
+| `darkTheme` | `mode: 'dark'` plus a dark grid, toolbar and overlay palette |
+| `roseTheme`, `emeraldTheme`, `amberTheme` | A brand primary colour and tinted header / selection backgrounds on the light palette |
+| `compactTheme` | 36px rows, 40px header (28px rows with `density="compact"`), tighter cell padding and 12px cell / header text |
+
+Presets are plain objects, so you can combine them: `theme={{ ...compactTheme, ...roseTheme, grid: { ...compactTheme.grid, ...roseTheme.grid } }}`.
+
 ---
 
 ## Example: Custom Purple Theme

package/docs/features/aggregation-pivot.md

@@ -21,19 +21,45 @@ Aggregation allows you to calculate summary values (Sum, Avg, etc.) for groups o
 />
 ```
 
+### What the footer totals
+
+The footer (and `apiRef.current.getAggregationResult()`, and the `aggregationResult` passed to `slots.footer`) always aggregates **every data row that passes the current filter**. That holds with or without row grouping or tree data, and however many groups are expanded. Group rows show their own subtotals inline; the grand total is computed from the underlying rows, never from those subtotals. (Before v3.0 the footer aggregated the *visible* rows under grouping, so expanding a group double-counted it, and `count` / `avg` were wrong even when collapsed.)
+
+Cells are read the way the grid shows them: a column with a `valueGetter` (for example `total = price × qty`) totals the computed values, not `row[field]`.
+
+### Footer layout
+
+The footer is laid out exactly like the rows: a hidden column has no footer cell, pinned columns keep their totals under the pinned column (left-pinned first, right-pinned last), and the totals stay aligned while scrolling horizontally, including when column virtualization renders only part of the columns and when the checkbox, detail-panel or row-reorder column is (or is not) pinned.
+
+### Server-side totals
+
+When a `dataSource` drives the rows (server or infinite pagination, server sorting, or server filtering), the grid only holds the rows the server returned, so it never totals them itself. The footer shows the `aggregationResults` returned by `getRows`, or the result of `dataSource.getAggregations`.
+
+- A result is only shown for the request it answered: after changing the aggregation model, filter or sort, the footer shows `—` until the new totals arrive, and keeps showing `—` if that request fails (the error is logged). It never shows the previous model's or filter's totals under the new label.
+- While a `getAggregations` request is pending the footer has `aria-busy="true"` and the class `ogx__aggregation-footer--loading`.
+- An inline `aggregationModel={{ salary: 'sum' }}` is a new object on every render of your component. The grid compares the model by content, so re-rendering with an equal model neither refetches nor clears the totals.
+
+If the server provides neither `aggregationResults` nor `getAggregations`, the footer shows `—`.
+
 ### Configuration
-You can control where the aggregation results appear:
-- **`footer`**: A sticky row at the bottom of the grid.
-- **`inline`**: Values displayed within group headers (when Row Grouping is active).
-- **`null`**: Skip aggregation for this group.
+`getAggregationPosition(groupNode)` controls where aggregation results appear. It is called for every group node (with its current `isExpanded`) and once with `null` for the grand total:
+- **`inline`** (default for groups): values on the group row.
+- **`footer`**: values on a subtotal row after the group's children while the group is expanded; the group row shows none. While the group is collapsed there is no subtotal row, so the values stay on the group row. For the grand total (`null`), `'footer'` (the default) shows the footer row.
+- **`null`**: no aggregation for that group (on screen and in `getGroupedExportRows()`); for the grand total, the footer row is hidden.
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   aggregationModel={model}
-  getAggregationPosition={(groupNode) => groupNode ? 'inline' : 'footer'}
+  rowGroupingModel={['department']}
+  // Subtotal rows below expanded groups, inline values on collapsed ones, and the grand total.
+  getAggregationPosition={() => 'footer'}
 />
 ```
 
+Group subtotals and the `(n)` count next to a group label cover only the rows that pass the filter, like the grand total; a group with no matching row is not shown.
+
 ---
 
 ## 🔄 Pivot Mode
@@ -51,29 +77,69 @@ const pivotModel: GridPivotModel = {
 };
 
 <DataGrid
+  rows={rows}
+  columns={columns}
   pivotMode={true}
   pivotModel={pivotModel}
 />
 ```
 
+`aggFn` is a `GridPivotAggFn`: `'sum' | 'avg' | 'count' | 'min' | 'max'`. `unique` is available to `aggregationModel`, but not to pivot value fields.
+
 ### Key Concepts
 - **Row Fields**: These become the static vertical axis of your pivot table.
 - **Column Fields**: Unique values in these fields become new columns.
 - **Value Fields**: The data that gets summarized at the intersection of row and column fields.
 
+The generated value columns are named `<field>␟<aggFn>` (for example `'salary\u001fsum'`) without column fields, and `<column key>␟<field>␟<aggFn>` with them.
+
+### Rows, filtering and sorting
+
+- **Filtering.** Filters on source fields (including the row fields) and the quick filter are applied to the **source rows before pivoting**, so every pivot value and the Grand Total reflect them. In pivot mode the quick filter searches every filterable source column. A condition on a generated value column (for example `'salary\u001fsum' > 1000`) is applied to the pivot rows. If a filter model mixes both kinds with `logicOperator: 'or'`, each kind is applied in its own stage, so the result is as if they were joined with `and`.
+- **Sorting** orders the pivot data rows. The Grand Total row always stays last.
+- **Pivot row ids** are derived from the row-field values (`'__pivot_row__:["Eng"]'`, `'__pivot_row__:["North","Q1"]'` for two row fields), so they never collide with source row ids and stay the same for the same group when the data changes (v3.0+; they were `0, 1, …`).
+- **Grand Total** is the last row (id `'__pivot_grand_total__'`). It totals the pivot rows shown, recomputed from the raw values (an average is the average of all underlying values, not of the row averages). It is not selected by the header select-all checkbox. When no source row is left, there is no Grand Total row and the no-rows overlay is shown; the value columns stay.
+- **Row ids.** Pivot rows carry their own ids (the `'__pivot_row__:…'` ids above and the Grand Total id). Your `getRowId` is not applied to them.
+- **Groups** are formed by each value's displayed string, as in row grouping, so `1` and `'1'` are one group. `null`, `undefined` and `''` form one blank group, labelled `null`.
+
+### Generated columns
+
+- **Row-label columns** keep the source column's `valueFormatter`, `renderCell`, `type`, alignment and `valueOptions` (the formatter and renderer receive a source row of that group). They always show, even if `columnVisibilityModel` hides the source column of the same field, and are `hideable: false`.
+- **Value columns** are formatted like every other aggregate (see [Formatting Totals](#-formatting-totals)).
+- **Column keys** are ordered by value: numbers and dates numerically, strings naturally (`'9'` before `'10'`), blanks last. Column-field header labels use the source column's `valueFormatter` (a boolean column formatted as Yes / No reads `Active: Yes — Salary (sum)`).
+- **Column rules.** A row or column field on a `groupable: false` column is skipped (as in row grouping), and a value field on an `aggregable: false` column, or whose function the column's `availableAggregationFunctions` does not allow, is skipped. Listing the same field and function twice produces one column. The toolbar's pivot panel offers only what these rules allow and never offers an `aggregable: false` column as a value.
+- **Column order.** The generated columns keep an order of their own: reordering them (in the header or the Columns panel) does not change your column order, and a controlled `columnOrder` (which names source columns) does not apply to them. When pivot mode is turned off, the previous column order is back.
+
+### Not combined with pivot mode
+
+- **Tree data and row grouping** are turned off while pivoting (the pivot rows are already grouped by the row fields). A development warning says so.
+- **`dataSource`**: pivoting is client-side, and a server-driven grid only holds one page of rows, so `pivotMode` is ignored when a `dataSource` is set (development warning). Pivot on the server, or pass the full dataset as `rows`.
+- **`aggregationModel`**: the footer is not shown, `apiRef.current.getAggregationResult()` returns `null` and `slots.footer` receives `aggregationResult: null`; the Grand Total row is the pivot's aggregate. The toolbar's Summaries panel does not list generated pivot columns.
+
 ---
 
 ## ⚙️ Aggregation Functions
 
-Built-in functions available:
+Built-in functions available (the same functions drive the footer, group rows, pivot and exports):
 - `sum`: Total of numeric values.
 - `avg`: Arithmetic mean.
 - `min`: Smallest value.
 - `max`: Largest value.
-- `count`: Number of items.
-- `unique`: Number of unique items.
+- `count`: Number of non-empty values.
+- `unique`: Number of distinct non-empty values.
+
+`sum`, `avg`, `min` and `max` use numbers, numeric strings and dates. Empty values (`null`, `undefined`, and strings that are empty or only whitespace), booleans and other values are ignored, so a blank cell never counts as `0`. `count` and `unique` ignore empty values too. `min` and `max` of dates return the date itself.
+
+The toolbar's Summaries panel offers these for each aggregable column, or only the ones listed in the column's `availableAggregationFunctions`. The same rules bind `aggregationModel` itself: an entry for an `aggregable: false` column, or with a function the column does not allow, is ignored by the footer, group rows and exports.
 
 ---
 
 ## 🎨 Formatting Totals
-Aggregation results automatically inherit the `valueFormatter` from their respective column definitions. If you need a specific format for aggregates only, use the `formatAggregationValue` utility.
+
+The footer, group rows, pivot value cells and every export format aggregates the same way:
+
+- `sum`, `avg`, `min` and `max` go through the column's `valueFormatter`, so totals keep the column's currency, unit or percent format. The formatter's `row` is the record of aggregated values: the footer totals, the group row, or the pivot row. A formatter that throws (typically because it reads row data an aggregate does not have) falls back to the default format instead of breaking the grid.
+- `count` and `unique` are plain counts: the column's `valueFormatter` is not applied (a count of a currency column is not an amount).
+- Without a formatter, numbers are locale-formatted (`avg` to at most two decimals) and dates show as locale dates.
+
+Exports follow the same rules; see [Aggregate values](export-guide.md#aggregate-values). Use `formatAggregationValue(value, fnName)` for the default number formatting elsewhere.