@opencorestack/opengridx 3.2.2 → 3.4.0

package/docs/API_REFERENCE.md

@@ -17,6 +17,7 @@ The main component for displaying and interacting with data.
 | `getRowId` | `(row: R) => GridRowId` | `row.id` | Returns a unique identifier for each row. It only keys the grid's internal store: rows reach `renderCell`, events, `apiRef` and `processRowUpdate` unchanged, and the id is never written to `row.id` (v3.0+). Pass it to export functions as `getRowId` when you export `selectedRows`. It must not throw: an id is a programming contract, so a throw is not contained (for a `dataSource` row it fails that request with the error overlay). |
 | `rowHeight` | `number` | `52` | Height of each row in pixels. Without it, an enclosing `DataGridThemeProvider`'s `grid.rowHeightStandard` applies (v3.0+). |
 | `headerHeight` | `number` | `56` | Height of the header row. Without it, the theme's `grid.headerHeight` applies (v3.0+). |
+| `wrapHeaderText` | `boolean` | `false` | Wraps header titles onto several lines instead of cutting them with an ellipsis (v3.3.0+). The header keeps `headerHeight`: a title takes as many lines as fit (2 at 56px, 3 at 72px, 4 at 88px) and ends in an ellipsis if it is still longer; raise `headerHeight` to show more lines. Wrapped headers get `ogx__header-cell--wrap` and their full title as the `title` tooltip (unless `description` is set). `GridColDef.wrapHeaderText` overrides it per column. See [Header](components/header.md). |
 | `autoHeight` | `boolean` | `false` | Adjust grid height to match row total. |
 | `overscanRowCount` | `number` | `3` | Minimum rows rendered outside the visible viewport. The grid adapts this upward automatically based on scroll velocity — this prop sets the floor. |
 | `loading` | `boolean` | `false` | With no rows, the body shows skeleton rows (or `slots.loadingOverlay`). With rows already shown, they stay and a progress bar runs along the top of the grid (or `slots.loadingOverlay` is shown over them). Works in list view too. |
@@ -30,7 +31,7 @@ The main component for displaying and interacting with data.
 | `height` | `number \| string` | `undefined` | Total height of the grid. Without it the grid fills its container (`height: 100%`, or `flex: 1 1 auto; min-height: 0` as a flex item; v3.0.1+), and grows to fit every row in an auto-height container. |
 | `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density: compact = the theme's `grid.rowHeightCompact` or 32 px, standard = `rowHeight`, comfortable = the theme's `grid.rowHeightComfortable` or 72 px. |
 | `initialState` | `GridInitialState` | `undefined` | Starting state (sort, filter, pagination, columns, density), read on mount. Seeds the grid's uncontrolled state; see [State Persistence](features/state-persistence.md). |
-| `slots` | `GridSlots` | — | Custom component overrides: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`. See [`GridSlots`](#gridslots-and-gridslotprops) and the [Slots API](customization/slots-api.md). |
+| `slots` | `GridSlots` | — | Custom component overrides: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`, `cellSelectionStats`. See [`GridSlots`](#gridslots-and-gridslotprops) and the [Slots API](customization/slots-api.md). |
 | `slotProps` | `GridSlotProps` | — | Props passed to the slots, keyed like `slots`. `slotProps.toolbar` is typed as `Partial<GridToolbarProps>` (plus any extra keys your own toolbar reads), so `GridToolbar` render props are type-checked (v3.0+). |
 | `filterModel` | `GridFilterModel` | `undefined` | Active filters (controlled). Omit it to let the grid keep its own filter state, seeded from `initialState.filter` and changed by the toolbar or `apiRef.setFilterModel` (v3.0+). |
 | `sortModel` | `GridSortItem[]` | `undefined` | Active sorting. |
@@ -61,6 +62,55 @@ The main component for displaying and interacting with data.
 | `disableMultipleRowSelection` | `boolean` | `false` | When `true`, at most one row can be selected at a time — by click, checkbox, Space or `apiRef` — and the header select-all checkbox is not shown. |
 | `disableClipboardCopy` | `boolean` | `false` | When `true`, Ctrl+C / Cmd+C does not copy the selected rows, so the page or your own handler owns the shortcut. `apiRef.current.copySelectedRows()` still works. See [Clipboard](features/clipboard.md). |
 
+#### Cell Range Selection (v3.3)
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `cellSelection` | `boolean` | `false` | Spreadsheet-style cell ranges: drag (with auto-scroll), Shift+click, Shift+arrow / Home / End / PageUp / PageDown, Ctrl/Cmd+A (every data cell of the page) and Escape (collapse). While on, Ctrl/Cmd+C copies the range (the focused cell at minimum) as TSV without a header line; `apiRef.current.copySelectedRows()` still copies rows. Row selection is not changed by ranges. See [Cell Range Selection](features/cell-selection.md). |
+| `cellSelectionModel` | `GridCellSelectionModel` | — | Controlled cell selection (zero or one range). Ignored while `cellSelection` is off. |
+| `onCellSelectionModelChange` | `(model: GridCellSelectionModel, details: { reason: GridCellSelectionReason }) => void` | — | Fired when the cell selection changes. `reason`: `'pointer'`, `'keyboard'`, `'selectAll'`, `'api'`, `'clear'` or `'dataChange'` (a corner's row or column is no longer displayed, so the range was cleared). |
+| `showCellSelectionStats` | `boolean` | `false` | Status bar under the grid (above the pagination area) with Count of non-empty cells and Sum / Average of the numeric cells, while more than one cell is selected. Replaceable through `slots.cellSelectionStats`. Needs `cellSelection`. |
+
+```ts
+interface GridCellCoordinates { id: GridRowId; field: string }
+interface GridCellRange { anchor: GridCellCoordinates; head: GridCellCoordinates }  // anchor = active cell
+type GridCellSelectionModel = readonly GridCellRange[];
+type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+interface GridCellSelectionChangeDetails { reason: GridCellSelectionReason }
+interface GridSelectedCell { id: GridRowId; field: string; value: unknown }
+```
+
+Public CSS: `ogx__cell--range`, `ogx__cell--range-top` / `-bottom` / `-left` / `-right`, `ogx--range-dragging` (root, during a drag), `--ogx-range-background`, `--ogx-range-border`. Range cells carry `aria-selected="true"`.
+
+#### Paste and Range Clear (v3.4)
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `disableClipboardPaste` | `boolean` | `false` | With `cellSelection` on, Ctrl/Cmd+V pastes tab-separated text into the editable cells (through `valueSetter` and `processRowUpdate`, once per row). `true` turns the shortcut off; `apiRef.current.pasteText()` still works. See [Clipboard](features/clipboard.md#-paste-from-excel-and-google-sheets-v34). |
+| `onClipboardPaste` | `(result: GridClipboardPasteResult) => void` | — | Fired after every paste, once every row has settled: `{ updated, failed, skipped, text }`. |
+| `onBeforeClipboardPaste` | `(params: GridBeforeClipboardPasteParams) => boolean \| string` | — | Runs before a paste with `{ text, anchor }`. Return `false` to cancel, a string to paste instead. A throw cancels the paste. |
+| `disableRangeClear` | `boolean` | `false` | With `cellSelection`, Delete / Backspace on a range of more than one cell empties its editable cells (`''` for strings, `null` otherwise) as one edit. `true` turns that off. |
+
+#### Undo / Redo (v3.4)
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `undoRedo` | `boolean \| GridUndoRedoOptions` | `false` | History of committed edits, pastes and range clears: Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y (focus on a cell, no editor open) and `apiRef.undo()` / `redo()`. Undo and redo write through `valueSetter` and `processRowUpdate`; cells changed since are skipped (`'changed'`). `{ limit }`: actions kept, default 100. See [Undo & Redo](features/undo-redo.md). |
+| `onHistoryChange` | `(params: GridHistoryChangeParams) => void` | — | Fired when `canUndo`, `canRedo` or `size` (actions that can be undone) changes. |
+
+```ts
+type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+interface GridBatchEditResult {
+  updated: GridRowId[];                                   // rows stored (processRowUpdate succeeded)
+  failed: { id: GridRowId; error: unknown }[];            // also sent to onProcessRowUpdateError
+  skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[];
+}
+interface GridClipboardPasteResult extends GridBatchEditResult { text: string }
+interface GridBeforeClipboardPasteParams { text: string; anchor: GridCellCoordinates | null }
+interface GridHistoryChangeParams { canUndo: boolean; canRedo: boolean; size: number }
+interface GridUndoRedoOptions { limit?: number }
+```
+
 #### Column Visibility
 
 | Prop | Type | Default | Description |
@@ -210,6 +260,7 @@ The types of the `slots` and `slotProps` props (v3.0+ exports). Each slot is typ
 | `pagination` | The built-in `Pagination` bar (shown with `pagination`). | `GridPaginationSlotProps` (= `PaginationProps`: `page`, `pageSize`, `rowCount`, `pageSizeOptions`, `onPageChange`, `onPageSizeChange`, `localeText`), then `slotProps.pagination`. |
 | `noRowsOverlay` | The empty-state icon and label (shown when there are no rows and the grid is not loading). | `slotProps.noRowsOverlay` only (`GridOverlaySlotProps`). |
 | `loadingOverlay` | The loading indicator: the skeleton rows while loading with no rows, the progress bar while loading with rows shown (the slot is then shown over them). | `slotProps.loadingOverlay` only (`GridOverlaySlotProps`). |
+| `cellSelectionStats` | The status bar of `showCellSelectionStats` (v3.3). Rendered while more than one cell is selected. | `GridCellSelectionStatsSlotProps`: `apiRef`, `cellCount`, `rowCount`, `columnCount`, `count`, `numericCount`, `sum`, `average` (`null` without numeric cells), then `slotProps.cellSelectionStats`. |
 | `footer` | The pagination area. | `GridFooterSlotProps`: `apiRef`, `aggregationModel`, `aggregationResult`, `rowCount`, `pagination`, `paginationModel`, `pageSizeOptions`, `onPaginationModelChange`, then `slotProps.footer`. `rowCount` is the built-in pager's count (pinned rows excluded, v3.0+); under tree data or row grouping, the filtered data rows. |
 
 ```ts
@@ -301,6 +352,17 @@ Access these methods via the `apiRef` prop.
 | `getAggregationModel()` | `GridAggregationModel \| null` | Get the active aggregation configuration. |
 | `getAllFilteredRows()` | `R[]` | Get every row that passes the filter, sorted, regardless of pagination, including pinned rows. Under row grouping and tree data it returns the data rows (no group rows) in hierarchy order with every group expanded, ordered like the screen (also when sorting by the hierarchy column; v3.0+). With tree data and a filter, ancestors shown only to give a match its context are left out: the result is the set select-all and the aggregation footer act on (v3.0+). Use for full-dataset exports. |
 | `getGroupedExportRows()` | `GridGroupedExportRow[] \| null` | Get a flat ordered list reflecting the active row-grouping tree (group-header, leaf, subtotal, grand-total), sorted and filtered like the screen. Collapsed groups are included with their rows, and subtotals are computed over each group's exported rows. Group-header and subtotal entries carry `groupLabel`, the label the grid shows (v3.0+). Returns `null` when row grouping is not active. |
+| `getCellSelectionModel()` | `GridCellSelectionModel` | The cell selection (`[]` while `cellSelection` is off). Includes a change made earlier in the same tick (v3.3). |
+| `setCellSelectionModel(model)` | `void` | Replace the cell selection (only the first range is kept); focus moves to its anchor. `reason: 'api'` (v3.3). |
+| `selectCellRange(anchor, head)` | `void` | Select the rectangle between two `GridCellCoordinates`; `anchor` becomes the active cell (v3.3). |
+| `clearCellSelection()` | `void` | Empty the cell selection (`reason: 'clear'`) (v3.3). |
+| `getSelectedCells()` | `GridSelectedCell[]` | Cells of the range in display order with values read through `valueGetter`. Synthetic rows and span-covered positions are left out (v3.3). |
+| `copySelectedCells()` | `Promise<void>` | Copy the range (the focused cell when nothing else is selected) as TSV without a header line. Resolves without writing when there is nothing to copy; rejects when the clipboard write fails (v3.3). |
+| `pasteText(text, anchor?)` | `Promise<GridBatchEditResult>` | Paste tab-separated text as Ctrl/Cmd+V does, from `anchor` (default: the range's top-left cell, else the focused cell), with `onBeforeClipboardPaste` / `onClipboardPaste`. Works with `disableClipboardPaste` and without `cellSelection` (then pass `anchor` or focus a cell) (v3.4). |
+| `undo()` | `Promise<GridBatchEditResult>` | Undo the last action (`undoRedo`); resolves once every row has settled (v3.4). |
+| `redo()` | `Promise<GridBatchEditResult>` | Redo the last undone action (v3.4). |
+| `canUndo()` / `canRedo()` | `boolean` | Whether there is an action to undo / redo (v3.4). |
+| `clearHistory()` | `void` | Forget every undo and redo action (v3.4). |
 | `copySelectedRows()` | `Promise<void>` | Copy every selected row that passes the filter (other pages, collapsed groups and pinned rows included) as TSV, with the visible columns in screen order. Resolves without writing when no selected row is found; rejects when the clipboard write fails. |
 
 ---
@@ -346,6 +408,7 @@ Defines the behavior and appearance of a single column.
 | `flex` | `number` | — | Flex grow factor — distributes remaining space proportionally. When both are set, `flex` wins over `width` until the user resizes the column. |
 | `align` | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment of cell content. |
 | `headerAlign` | `'left' \| 'center' \| 'right'` | `align` | Horizontal alignment of the header cell content. Falls back to the column's `align`, then `'left'`. |
+| `wrapHeaderText` | `boolean` | grid's `wrapHeaderText` | Wraps this column's header title (v3.3.0+). Overrides the grid prop either way: `false` keeps one line with an ellipsis in a wrapping grid. |
 | `zIndex` | `number` | — | CSS `z-index` for the column's cells and header cell (pinned cells default to 3). |
 
 #### Data & Type
@@ -356,6 +419,7 @@ Defines the behavior and appearance of a single column.
 | `valueOptions` | `Array<string \| number \| { value: unknown; label: string }>` | — | Allowed values for `type: 'singleSelect'` — the filter panel offers them as a (multi-)select, and the edit cell uses them; cells and exports show the option's label. |
 | `valueGetter` | `(params: GridValueGetterParams) => unknown` | — | Derive a computed value from the row object. Runs before `valueFormatter` and `renderCell`. Client-side sorting, column filters and the quick filter use this value, and editors start from it (double-click and Enter alike). Keep it pure: the quick filter caches each row's search text per row object and column set. A getter that throws for a row shows an error in that cell and reads as `undefined` for sorting, filtering, aggregation, grouping, pivot and list view (v3.0+, with a one-time development warning per column); before, it crashed the grid once the column was sorted, filtered or aggregated. |
 | `valueSetter` | `(params: GridValueSetterParams) => R` | — | v3.0+. Maps an edited value back onto the row (`{ value, row, field }` → updated row) when an edit is committed. Needed for editable `valueGetter` columns; without it the commit writes `row[field]` and a development warning is logged. |
+| `valueParser` | `(text: string, params: GridValueParserParams) => unknown` | — | v3.4+. Turns pasted text into this column's value instead of the default parser for its `type` (`{ row, field, colDef }`). Throw or return `undefined` to skip the cell (`'invalidValue'`). See [Clipboard](features/clipboard.md#valueparser). |
 | `valueFormatter` | `(params: GridValueFormatterParams) => string` | — | Format the value into a display string (e.g. currency, dates). Does not affect editing, sorting or column filters; the quick filter also searches the formatted text. A formatter that throws leaves the value unformatted (the quick filter searches the raw value; v3.0+). |
 
 #### Rendering
@@ -404,6 +468,7 @@ Span values are floored; `Infinity` means "to the end"; `NaN`, `0` and negative
 | `groupingValueFormatter` | `(params: { field: string; value: unknown }) => string` | — | Custom formatter for group-header labels when this column is the active grouping field. Falls back to `"field: value"` when omitted or when it throws (v3.0+). |
 | `aggregable` | `boolean` | — | Whether this column can be aggregated. Unset, the toolbar's Summaries panel and the pivot panel's value fields offer it only for `type: 'number'` columns; `true` offers it for any type. `false` keeps it out of both panels, and an `aggregationModel` or `pivotModel` entry naming it is ignored (no footer total, group aggregate, pivot value or export total). |
 | `availableAggregationFunctions` | `string[]` | all built-ins | Restrict which aggregation functions are computed and available for this column (e.g. `['sum', 'avg']`). Functions outside this list are skipped even if set in `aggregationModel` or a pivot value field, the toolbar's Summaries panel and the pivot panel offer only these. |
+| `aiExamples` | `unknown[]` | — | Example values put into the schema from `getGridAiSchema` (`@opencorestack/opengridx/ai`) to help a model write filters. **These values are sent to the model**: the schema never reads row data, so only what you list here leaves the app. Strings, numbers and booleans, at most 10. Not used by the grid itself (v3.4.0+). |
 
 ---
 
@@ -424,6 +489,32 @@ Every exporter takes `columns` typed for your rows (`GridColDef<R>[]`) or untype
 
 ---
 
+## 🤖 AI Toolkit (`@opencorestack/opengridx/ai`)
+
+A separate entry point (v3.4.0+) with no React import and no dependencies; the core package never loads it. It does not call any AI service: the app sends the schema to its own model and validates the reply. Guide: [AI Toolkit](features/ai-toolkit.md).
+
+```ts
+import { getGridAiSchema, validateGridAiState } from '@opencorestack/opengridx/ai';
+import type { GridAiState, GridAiValidationError } from '@opencorestack/opengridx/ai';
+```
+
+| Function | Return | Description |
+| :--- | :--- | :--- |
+| `getGridAiSchema(columns, options?)` | `GridAiSchema` | JSON Schema (draft 2020-12, `schemaVersion: 1`) of the `filterModel` (nested AND/OR groups up to 3 levels, `quickFilterValues`), `sortModel`, `rowGroupingModel`, `aggregationModel`, `pivotModel` and `columnVisibilityModel` the columns allow, honouring `filterable`, `sortable`, `groupable`, `hideable`, `aggregable`, `availableAggregationFunctions` and `valueOptions`. Operators per column come from the column type. Reads column definitions only, never rows; deterministic for the same input. |
+| `validateGridAiState(json, columns, options?)` | `GridAiValidationResult` | `{ state, errors }`. `json` is an object or a JSON string. Drops unknown parts, fields, operators and enum values (each with an `{ path, message }` error), coerces values to the column type (`"1,200"` → `1200`, dates → `"YYYY-MM-DD"`), removes empty filter groups. Never throws. |
+
+`GridAiSchemaOptions`: `include` / `exclude` (`GridAiPart[]`: `'filter' \| 'sort' \| 'grouping' \| 'aggregation' \| 'pivot' \| 'columnVisibility'`; `exclude` wins), `descriptions` (default `true`: each column's `headerName` and `description` go into the schema), `examples` (default `true`: the columns' `aiExamples` go into the schema). `GridAiValidateOptions` takes `include` / `exclude`; parts outside them are dropped with an error.
+
+| Type | Description |
+| :--- | :--- |
+| `GridAiColumn` | The column properties the toolkit reads. A `GridColDef` (typed or untyped) is accepted as is. Fields starting with `__` (system columns) are skipped. |
+| `GridAiSchema` | The returned JSON Schema object: `$schema`, `schemaVersion: 1`, `title`, `type: 'object'`, `properties` (one per offered part) and `$defs`. |
+| `GridAiState` | The validated state: `filterModel?`, `sortModel?`, `rowGroupingModel?`, `aggregationModel?`, `pivotModel?`, `columnVisibilityModel?`, the same types the grid's props take. Only parts present in the reply are set. |
+| `GridAiValidationError` | `{ path: string; message: string }`, e.g. `{ path: 'filterModel.items[2].field', message: 'Unknown field "revenue"' }`. At most 100 are listed. |
+| `GridAiValidationResult` | `{ state: GridAiState; errors: GridAiValidationError[] }` |
+
+---
+
 ## 🧩 Standalone Components
 
 The grid's building blocks are exported with their props types (the props types since v3.0). `DataGrid` renders all of them itself; import them to build your own layout or slot.
@@ -438,8 +529,35 @@ The grid's building blocks are exported with their props types (the props types
 | `Header` | `HeaderProps` | The column header rows. See [Header](components/header.md). |
 | `Row` | `RowProps` | One body row. See [Row](components/row.md). |
 | `Cell` | `CellProps` | One body cell. See [Cell](components/cell.md). |
+| `CellSelectionStats` | `CellSelectionStatsProps` | The default status bar of `showCellSelectionStats` (v3.3), e.g. to wrap in a `cellSelectionStats` slot. |
 | `Skeleton` | `SkeletonProps` | Loading placeholder (`rows`, `columns`, both default 5). |
-| `Button`, `Input`, `Checkbox` | `ButtonProps`, `InputProps`, `CheckboxProps` | The grid's form controls. `Button` defaults to `type="button"`. |
+| `Button`, `Input`, `Checkbox` | `ButtonProps`, `InputProps`, `CheckboxProps` | The grid's form controls. `Button` defaults to `type="button"`. See [`Input`](#input) and [`Checkbox`](#checkbox) below. |
+
+### `Input`
+A text field: an `<input class="ogx-input">` inside a `<div class="ogx-input-wrapper">` that also holds the adornments. The grid's search boxes, filter value box and text / number / date cell editors render through it. Every other `<input>` attribute (`value`, `onChange`, `type`, `id`, `name`, `aria-*`, …) goes to the `<input>`.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLInputElement>` | — | Reaches the `<input>` (`forwardRef`, React 18 and 19). Since v3.3.1. |
+| `variant` | `'field' \| 'cell'` | `'field'` | `'field'`: bordered form field. `'cell'`: fills its container (a grid cell), no border, radius, background or focus shadow, cell font and the editor padding; adds `ogx-input-wrapper--cell`. Since v3.3.1. |
+| `inputClassName` | `string` | — | Classes added to the `<input>` next to `ogx-input`. Since v3.3.1. |
+| `className` | `string` | — | Classes added to the wrapper `<div>`. |
+| `fullWidth` | `boolean` | `false` | Wrapper takes 100% width (`ogx-input-wrapper--full-width`). |
+| `error` | `boolean` | `false` | `ogx-input-wrapper--error` (error border; inset error edge in the cell variant) and `aria-invalid="true"` on the `<input>`. |
+| `startAdornment` / `endAdornment` | `ReactNode` | — | Content before / after the `<input>` (`ogx-input__adornment--start` / `--end`), e.g. a currency or a unit. |
+| `disabled` | `boolean` | — | Disables the `<input>` and adds `ogx-input-wrapper--disabled`. |
+
+### `Checkbox`
+A styled checkbox: a visually hidden `<input type="checkbox" class="ogx-checkbox__input">` and a drawn `.ogx-checkbox__box`, inside a `<label class="ogx-checkbox-wrapper">`. Other props (`checked`, `onChange`, `onMouseDown`, `tabIndex`, `aria-*`, …) go to the `<input>`. The grid's row checkboxes, column panel, list view and boolean cell editor use it.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `ref` | `Ref<HTMLInputElement>` | — | Reaches the `<input>` (`forwardRef`). Since v3.3.1. |
+| `inputRef` | `Ref<HTMLInputElement>` | — | Also reaches the `<input>` (kept for compatibility). |
+| `inputClassName` | `string` | — | Classes added to the `<input>` next to `ogx-checkbox__input`. Since v3.3.1. |
+| `className` | `string` | — | Classes added to the wrapper `<label>`. |
+| `indeterminate` | `boolean` | `false` | Shows the indeterminate mark and sets the input's `indeterminate`. |
+| `label` | `string` | — | Visible label text after the box; also the accessible name. |
 
 ---
 
@@ -453,7 +571,7 @@ Context provider for overriding the grid's visual system.
 - **`colors`**: `primary`, `primaryDark`, `primaryLight`, `primaryFocus`, `secondary*`, `success`, `warning`, `error`, `info`, `white`, `black`, `gray` (`{ 50 … 900 }`). Toolbar, menu, selection and focus accents derive from `primary*` unless set directly.
 - **`typography`**: `fontFamily`, `fontFamilyMono`, `fontSizeXs` … `fontSizeXl`.
 - **`spacing`**: `xs` … `xxl`. **`borders`**: `widthThin/Medium/Thick`, `radiusSm` … `radiusXl`, `color`, `colorHover`. **`shadows`**: `sm` … `xl`.
-- **`grid`**: surfaces (`background`, `borderColor`, `headerBackground`, `headerText`, `headerHoverBackground`, `headerSortedBackground`, `rowText`, `rowHoverBackground`, `rowAlternateBackground`, `rowSelectedBackground`, `rowSelectedHoverBackground`, `cellFocusBorder`, `pinnedLeftShadow`, `pinnedRightShadow`, `checkboxBg`, `checkboxBorder`), sizing (`rowHeightCompact`, `rowHeightStandard`, `rowHeightComfortable`, `headerHeight` in px, read by the grid's layout; the `rowHeight` / `headerHeight` props win), `cellPaddingX`, `cellPaddingY`, `cellFontSize`, `headerFontSize`.
+- **`grid`**: surfaces (`background`, `borderColor`, `headerBackground`, `headerText`, `headerHoverBackground`, `headerSortedBackground`, `rowText`, `rowHoverBackground`, `rowAlternateBackground`, `rowSelectedBackground`, `rowSelectedHoverBackground`, `cellFocusBorder`, `rangeBackground`, `rangeBorder` (v3.3), `pinnedLeftShadow`, `pinnedRightShadow`, `checkboxBg`, `checkboxBorder`), sizing (`rowHeightCompact`, `rowHeightStandard`, `rowHeightComfortable`, `headerHeight` in px, read by the grid's layout; the `rowHeight` / `headerHeight` props win), `cellPaddingX`, `cellPaddingY`, `cellFontSize`, `headerFontSize`.
 - **`toolbar`**, **`overlays`**, **`scrollbar`** (`thumbColor`, `trackColor`, `size`), **`skeleton`** (`baseColor`, `highlightColor`), **`transitions`**.
 
 Presets: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compactTheme`. See [Theming](customization/theming.md).
@@ -690,6 +808,8 @@ interface GridLocaleText {
   paginationOf?: (from: number, to: number, count: number) => string;
   paginationPage?: (page: number, pageCount: number) => string;
   noRowsLabel?: string;
+  /** v3.3: live-region text after a cell range change. Default "12 cells selected, 3 rows by 4 columns". */
+  cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
 }
 ```
 
@@ -782,6 +902,15 @@ Passed to `valueSetter` (v3.0+).
 | `row` | `R` | The row as it was before the edit. |
 | `field` | `string` | The column field name. |
 
+### `GridValueParserParams<R>`
+Passed to `valueParser` (v3.4+).
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `row` | `R` | The row the text is pasted into, as stored now. |
+| `field` | `string` | The column field name. |
+| `colDef` | `GridColDef<R>` | The column. |
+
 ### `GridColumnOrderChangeParams`
 Passed to `onColumnOrderChange`.
 

package/docs/README.md

@@ -36,7 +36,9 @@ In-depth guides on the grid's functional capabilities.
 - **[Editing & Reordering](features/editing-reordering.md)** - Inline edits and Drag-and-Drop
 - **[Loading & Performance](features/loading-states.md)** - Skeletons, Lazy, and Infinite loading
 - **[Row Selection](features/selection.md)** - Multi & single choice selection
-- **[Clipboard](features/clipboard.md)** - Copy and Paste grid data
+- **[Clipboard](features/clipboard.md)** - Copy rows and ranges, paste from Excel / Sheets, clear a range with Delete
+- **[Cell Range Selection](features/cell-selection.md)** - Spreadsheet-style cell ranges, copy and a sum / average status bar
+- **[Undo & Redo](features/undo-redo.md)** - Ctrl+Z / Ctrl+Shift+Z for edits, pastes and range clears
 - **[Pinning](features/pinning.md)** - Sticky columns and rows
 - **[State Persistence](features/state-persistence.md)** - Save/Restore grid configuration
 - **[Aggregation & Pivot](features/aggregation-pivot.md)** - Data summarization and analytics
@@ -48,6 +50,7 @@ In-depth guides on the grid's functional capabilities.
 - **[Infinite Scroll](features/infinite-scroll.md)** - Advanced performance loading
 - **[Data Source](features/data-source.md)** - Server-side fetching and SSR
 - **[Export Guide](features/export-guide.md)** - Excel, CSV, JSON, and Print
+- **[AI Toolkit](features/ai-toolkit.md)** - JSON Schema of the grid state for your own model, and a validator for its replies (`@opencorestack/opengridx/ai`)
 
 ---
 

package/docs/architecture/datagrid-orchestration.md

@@ -17,6 +17,14 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
   `useGridAggregationApi` and `useGridScrollToIndexesApi` install once per `apiRef` in a layout
   effect and read the latest values from a ref refreshed in a layout effect, so the methods are
   live in a parent's layout effect and never answer from a previous render.
+- `useGridCellSelection` runs after `useGridSpanning` (it needs `getSpanOrigin` and the span caches) and
+  before `useGridKeyboardNavigation`, which receives its Shift-key handlers. `useGridCellSelectionApi` runs
+  after the keyboard hook because it reads and sets `focusedCell`.
+- `useGridBatchEdit` is created before `useGridEditing` (single edits store through it, so an undo right after an
+  edit reads the stored row before the next render). The history hook needs the focus and selection hooks, so it runs
+  late (36c); commits reach it through `useGridEditCommitChannel` (12a), whose listener it sets in a layout effect.
+  `useGridClipboardPaste` (36b) and `useGridUndoRedo` listen for keys on the grid root with native listeners, which
+  fire before React's delegated `onKeyDown` of the viewport; they act only on cell targets with no editor open.
 - `useGridLiveRowSelection` prunes the selection, and `useGridPageCorrection` corrects a page past the
   end, in effects that run before the later hooks' effects.
 
@@ -25,7 +33,7 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | # | Hook / util | File | Produces |
 | :- | :--- | :--- | :--- |
 | 0 | `useStableColumns` | `hooks/core/useStableColumns.ts` | The `columns` prop with a stable identity while every column is shallowly equal (inline columns do not re-run the row passes) |
-| 1 | `useGridControlledState` | `hooks/core/useGridControlledState.ts` | Controlled/uncontrolled sort, filter, aggregation, visibility, pinning, pivot, pagination, selection, density |
+| 1 | `useGridControlledState` | `hooks/core/useGridControlledState.ts` | Controlled/uncontrolled sort, filter, aggregation, visibility, pinning, pivot, pagination, selection, density, cell selection (v3.3) |
 | 2 | `useGridPivot` | `hooks/features/useGridPivot.ts` | Pivot rows/columns (or the source ones) and the pipeline filter/sort models |
 | 3 | `resolveGridModes` (pure) | `utils/gridModes.ts` | Which features are in effect: tree data, row grouping, pagination, row reordering, list view, grouping column |
 | 4 | `useGridThemeDimensions` | `hooks/core/useGridThemeDimensions.ts` | Row and header heights (props → theme provider → defaults) |
@@ -37,7 +45,9 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | 10 | `useGridRowIdOf` | `hooks/core/useGridRowIdOf.ts` | `getRowIdOf` and its stable event-handler twin |
 | 11 | `useGridApiRefBinding` | `hooks/core/useGridApiRefBinding.ts` | Binds the `apiRef` prop (layout effect) |
 | 12 | `useGridHierarchy` | `hooks/core/useGridHierarchy.ts` | `useTreeData` + `useRowGrouping`, the active handlers and `rowMetaMap` |
-| 13 | `useGridEditing` | `hooks/features/useGridEditing.ts` | Cell editing state and handlers |
+| 12a | `useGridEditCommitChannel` | `hooks/core/useGridUndoRedo.ts` | Stable `emit` / `setListener` pair: the commit paths below report stored changes through `emit`, and `useGridUndoRedo` (36c) registers the listener (v3.4) |
+| 12b | `useGridBatchEdit` | `hooks/features/useGridBatchEdit.ts` | Batch edits (v3.4): `applyEdits` runs `valueSetter` → `processRowUpdate` once per row (rows in parallel, failures isolated and sent to `onProcessRowUpdateError`) and stores every successful row in one `replaceRows` update; `getRow` sees rows stored since the last render; `storeRow` stores a single edit |
+| 13 | `useGridEditing` | `hooks/features/useGridEditing.ts` | Cell editing state and handlers; stores through `useGridBatchEdit.storeRow` and reports the committed change to the channel |
 | 14 | `useGridLiveRowSelection` | `hooks/core/useGridLiveRowSelection.ts` | Selection without removed rows |
 | 15 | `useGridDataSource` | `hooks/features/useGridDataSource.ts` | Server fetching |
 | 16 | `useServerTreeChildren` | `hooks/features/useServerTreeChildren.ts` | Lazy server tree children |
@@ -54,14 +64,18 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | 27 | `useGridAggregationApi` | `hooks/core/useGridAggregationApi.ts` | `getAggregationResult`, `getAggregationModel`, `getGroupedExportRows` |
 | 28 | `useLayout` | `hooks/core/useLayout.ts` | Row heights, pinned column split, widths |
 | 29 | `useGridSpanning` | `hooks/features/useGridSpanning.ts` | Row/column spans |
-| 30 | `useGridClipboardApi` | `hooks/core/useGridClipboardApi.ts` | Ctrl/Cmd+C and `copySelectedRows` |
+| 29a | `useGridCellSelection` | `hooks/core/useGridCellSelection.ts` | Cell range (v3.3): the model's range resolved against `allRenderableRows` and the data columns of `navigationColumns` (grown over spans), the render rectangle, pointer drag with auto-scroll and Shift+click, the Shift-key handlers for the keyboard hook, copy text, status-bar totals and the debounced live-region text. Inert while `cellSelection` is off |
+| 30 | `useGridClipboardApi` | `hooks/core/useGridClipboardApi.ts` | Ctrl/Cmd+C and `copySelectedRows`; with `cellSelection` the shortcut copies the range (`getCellRangeCopyText`) |
 | 31 | `useGridScrollToIndexesApi` | `hooks/core/useGridScrollToIndexesApi.ts` | `scrollToIndexes` |
 | 31a | `useGridColumnAutosize` | `hooks/core/useGridColumnAutosize.ts` | `autosizeColumn` / `autosizeColumns` on the API, and the resize handle's auto-size handler (v3.1) |
 | 32 | `useGridViewport` | `hooks/core/useGridViewport.ts` | Scroll sync, viewport measurement, viewport callback ref |
 | 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window |
 | 34 | `useGridSortHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Header sort / shift-sort |
-| 35 | `useGridKeyboardNavigation` | `hooks/core/useGridKeyboardNavigation.ts` | Focus and keyboard handling |
+| 35 | `useGridKeyboardNavigation` | `hooks/core/useGridKeyboardNavigation.ts` | Focus and keyboard handling; takes `cellSelection.keyboard` (Shift+navigation, Escape, Ctrl/Cmd+A) |
 | 36 | `useGridPointerFocusHandlers` | `hooks/core/useGridFocusHandlers.ts` | Cell and header click focus |
+| 36a | `useGridCellSelectionApi` | `hooks/core/useGridCellSelectionApi.ts` | Keeps the range anchor and the focused cell together (layout effect: a new anchor moves focus; focus moved to another data cell collapses the range), clears a range whose corner is gone (`'dataChange'`), and installs `getCellSelectionModel`, `setCellSelectionModel`, `selectCellRange`, `clearCellSelection`, `getSelectedCells`, `copySelectedCells` (once per `apiRef`, reading the latest values from a ref) |
+| 36b | `useGridClipboardPaste` | `hooks/core/useGridClipboardPaste.ts` | Paste and range clear (v3.4): `paste` and Delete/Backspace listeners on the grid root (only for cell targets, not editors or nested grids), TSV parsing (`utils/parsing.ts`), placement against the renderable rows and range columns (`utils/editing/targets.ts`), the batch edit, the new selection, `onBeforeClipboardPaste` / `onClipboardPaste`, and `apiRef.pasteText`. Inert without `cellSelection` except for `pasteText` |
+| 36c | `useGridUndoRedo` | `hooks/core/useGridUndoRedo.ts` | History (v3.4, `undoRedo`): records the channel's changes, replays them as batch edits with an `expect` value per cell (stale cells skipped), queues undo/redo, selects and scrolls to the affected cells, Ctrl/Cmd+Z / Shift+Z / Ctrl+Y on the grid root, `onHistoryChange`, and `apiRef.undo` / `redo` / `canUndo` / `canRedo` / `clearHistory` |
 | 37 | `useGridColumnMenuHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Column menu Hide / Pin (`pinColumnTo` in `utils/pinning`) |
 | 38 | `useGridAriaRows` | `hooks/core/useGridAriaRows.ts` | `aria-rowcount` and `aria-rowindex` bases |
 | 39 | `useGridSpanRowWindow` | `hooks/features/useGridSpanRenderWindow.ts` | Render window widened to whole row spans |
@@ -77,6 +91,9 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 
 `GridToolbarSlot`, `GridStandaloneColumnPanel`, `GridListView` (list view) or the viewport
 (`Header`, `GridPinnedRows` top, `GridEmptyState`, `GridVirtualRows`, `GridPinnedRows` bottom,
-`GridAggregationFooter`), then `slots.footer` or `GridPaginationArea`, `GridLiveRegion`,
+`GridAggregationFooter`), `GridCellSelectionStatsArea` (`showCellSelectionStats` with `cellSelection`), then `slots.footer` or `GridPaginationArea`, `GridLiveRegion`,
 `GridLoadingOverlay` and `GridErrorOverlay`. The props all three row renderers take alike are built
-once in `DataGrid.tsx` (`rowRenderProps`) and spread into each.
+once in `DataGrid.tsx` (`rowRenderProps`) and spread into each. `rowRenderProps.cellRange` is the cell range's
+render rectangle; each row renderer turns it into a per-row `cellRange` (`getRowCellRange`), `null` for rows
+outside it, and `Row` is memoised with a value comparison of that prop, so a drag only re-renders the rows the
+range enters or leaves.

package/docs/components/header.md

@@ -24,6 +24,31 @@ Manages the column headers, sorting triggers, column resizing, and column groupi
 | `focusedCell` | `{ id: GridRowId \| null; field: string } \| null` | The grid's focus position. `id: null` means the header cell of `field` is focused (v3.0; it used to be the string `'HEADER'`, which a real row id could collide with). DOM focus is moved by the grid, not by `<Header />`. |
 | `columnIndexMap` | `Map<string, number>` | Position of each visible data column in render order. Used for `aria-colindex` and the `colIndex` passed to `renderHeader`, so they match the body cells and do not change with horizontal scrolling. |
 
+## ↩️ Wrapped Header Text
+
+By default a header title stays on one line and is cut with an ellipsis. Pass `wrapHeaderText` to `<DataGrid>` (or set `GridColDef.wrapHeaderText` on a column) and long titles wrap instead (v3.3.0+):
+
+```tsx
+const columns: GridColDef[] = [
+  // Keeps one line with an ellipsis even though the grid wraps
+  { field: 'fund', headerName: 'Fund name and share class', wrapHeaderText: false },
+  { field: 'nav', headerName: 'Net asset value per share (USD)', width: 120 },
+];
+
+<DataGrid rows={rows} columns={columns} wrapHeaderText headerHeight={72} />
+```
+
+- **The header keeps `headerHeight`.** It does not grow to fit the title (sticky offsets and virtualization rely on a fixed header height). A wrapped title takes as many lines as fit — 2 at the default 56px, 3 at 72px, 4 at 88px (16px lines inside 8px vertical padding) — and ends in an ellipsis on the last line if it is still longer. Raise `headerHeight` to show more lines. When the column shows an aggregation label under its title, the title gets one line less.
+- **Precedence:** a column's `wrapHeaderText` wins over the grid prop, in both directions.
+- **Tooltip:** a wrapped header shows its full title as the `title` tooltip, unless the column has a `description`, which is shown instead. Only string titles are used; a `renderHeader` result gets no automatic tooltip.
+- **Layout:** the sort icon, the menu button and the resize handle stay where they are and stay clickable; only the title wraps.
+- **Auto-size:** double-clicking the resize handle (or `apiRef.current.autosizeColumn`) still measures the title on one line, so the column grows until the title no longer wraps.
+- **Class:** wrapped header cells get `ogx__header-cell--wrap`; the line count is set inline as `-webkit-line-clamp` on `.ogx__header-cell-title`.
+- **Themes:** the line count assumes the default header font (13px) and cell padding (8px). With a theme that changes `headerFontSize` or `cellPaddingY`, the title is still capped to the header height, but the last visible line may be cut without an ellipsis.
+- Column group header rows are not affected.
+
+`Header` takes the same `wrapHeaderText` prop and a `headerHeight` (default 56) when used on its own.
+
 ## 📐 Column Grouping
 
 The `<Header />` dynamically calculates the nesting depth of your `columnGroupingModel` and renders one group row per level above the main column headers. Group cells are sized from `allColumns`, so they match their member columns' resolved widths; cells over pinned columns are sticky. See [Column Group Headers](../API_REFERENCE.md#️-column-group-headers) for the full behaviour.

package/docs/customization/theming.md

@@ -83,7 +83,7 @@ interface GridTheme {
   spacing?:     GridThemeSpacing;
   borders?:     GridThemeBorders;
   shadows?:     GridThemeShadows;
-  grid?:        GridThemeGrid;        // surfaces, heights (px), cellPaddingX/Y, cellFontSize, headerFontSize, …
+  grid?:        GridThemeGrid;        // surfaces, heights (px), cellPaddingX/Y, cellFontSize, headerFontSize, rangeBackground, rangeBorder, …
   toolbar?:     GridThemeToolbar;
   overlays?:    GridThemeOverlays;
   scrollbar?:   GridThemeScrollbar;
@@ -213,6 +213,8 @@ All sub-theme types (`GridThemeColors`, `GridThemeGrayScale`, `GridThemeTypograp
 | `--ogx-grid-row-selected-background` | `#eff6ff` | `#1e3a5f` | Selected row fill |
 | `--ogx-grid-row-selected-hover-background` | `#dbeafe` | `#1d4ed8` | Selected row hover |
 | `--ogx-grid-cell-focus-border` | `#3b82f6` | `#60a5fa` | Keyboard focus ring |
+| `--ogx-range-background` | `rgba(59, 130, 246, 0.12)` | `rgba(96, 165, 250, 0.18)` | Tint over a selected cell range (`cellSelection`, v3.3). Theme key `grid.rangeBackground` |
+| `--ogx-range-border` | `var(--ogx-color-primary)` | `#60a5fa` | Outline of a selected cell range, drawn as an inset box-shadow on `ogx__cell--range-top/-bottom/-left/-right` (v3.3). Theme key `grid.rangeBorder` |
 | `--ogx-grid-pinned-left-shadow` | `4px 0 24px...` | (darker) | Shadow on left-pinned columns |
 | `--ogx-grid-pinned-right-shadow` | `-4px 0 24px...` | (darker) | Shadow on right-pinned columns |
 | `--ogx-checkbox-bg` | — | `#1e293b` | Checkbox background (dark only) |
@@ -338,4 +340,13 @@ const purpleTheme: GridTheme = {
 - The dark mode overrides are in the same file under `@media (prefers-color-scheme: dark)`
 - The CSS entry point for the entire library is `lib/styles/opengridx.css` (single barrel import)
 - BEM class prefix: `ogx__` (e.g. `ogx__cell`, `ogx__header-cell`)
+- **Form controls** — the toolbar search, column-panel search, filter value box and the text / number / date cell
+  editors render through the shared `Input` (v3.3.1+): their `<input>` keeps its own class (`ogx-global-search__input`,
+  `ogx-column-visibility-panel__search-input`, `ogx-filter__value-input`, `ogx__edit-input`) and also has `ogx-input`,
+  and sits inside a `div.ogx-input-wrapper`. Target it with a descendant selector (`.ogx-global-search input`), not a
+  child one (`.ogx-global-search > input`). Cell editors' wrappers also have `ogx-input-wrapper--cell` (fills the cell,
+  no border, background or focus shadow; `ogx-input-wrapper--error` adds an inset `--ogx-color-error` edge). The boolean
+  editor and list-view row checkbox are the shared `Checkbox` (`ogx-checkbox-wrapper`, `ogx-checkbox__box`; the `<input>`
+  keeps `ogx__edit-checkbox` and is visually hidden). `Input.css` loads first in `opengridx.css`, so component rules
+  override it at equal specificity.
 - Variable prefix: `--ogx-` (e.g. `--ogx-color-primary`)

package/docs/features/ai-toolkit.md

@@ -0,0 +1,119 @@
+# AI Toolkit: Grid Schema & Validator
+
+*Since v3.4.0* · Demo: [AI: Grid Schema & Validator](https://opencorestack.github.io/OpenGridX/ai-schema)
+
+Let users drive the grid in plain language ("paid orders over $10k in the North, biggest first") with the model your app already uses. The `@opencorestack/opengridx/ai` entry point gives you the two pieces the grid can own:
+
+- **`getGridAiSchema(columns, options?)`** turns your column definitions into a JSON Schema (draft 2020-12) of the grid state a model may return: filters, sort, row grouping, aggregation, pivot and column visibility, each limited to what the columns allow.
+- **`validateGridAiState(json, columns, options?)`** checks the model's reply against the columns and returns the state that is safe to apply, plus a list of what it dropped.
+
+OpenGridX never calls an AI service and bundles no AI SDK. Your app sends the prompt, the schema and the current state to its own model (with structured output), and passes the reply to the validator.
+
+```ts
+import { getGridAiSchema, validateGridAiState } from '@opencorestack/opengridx/ai';
+
+const schema = getGridAiSchema(columns, { include: ['filter', 'sort', 'grouping', 'aggregation'] });
+
+async function ask(prompt: string) {
+  // Your own endpoint calls your own model, with `schema` as the structured-output format.
+  const res = await fetch('/api/grid-assistant', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt, schema, currentState: { filterModel, sortModel } }),
+  });
+  const { state, errors } = validateGridAiState(await res.text(), columns);
+  if (errors.length) console.info('Dropped from the reply:', errors);
+  if (state.filterModel) setFilterModel(state.filterModel);
+  if (state.sortModel) setSortModel(state.sortModel);
+  if (state.rowGroupingModel) setRowGroupingModel(state.rowGroupingModel);
+  if (state.aggregationModel) setAggregationModel(state.aggregationModel);
+}
+```
+
+The entry point has no React import and no dependencies (about 4.5 kB gzipped). Importing `@opencorestack/opengridx` never loads it, and it works on a server too, so you can validate the reply in the same endpoint that calls the model.
+
+## Privacy rules
+
+- **No row data by default.** The schema is built from column definitions only: `field`, `headerName`, `description`, `type`, the operators of the type, `valueOptions` and the allowed aggregation functions. The grid never reads a row for it.
+- **`aiExamples` is real data.** `GridColDef.aiExamples` puts example values into the schema to help the model ("Acme" → `customer`). Those values are sent to the model. List only what you are happy to share; leave it out for anything personal. `options.examples: false` drops all of them.
+- **`valueOptions` are sent.** The options of a `singleSelect` column become an `enum` in the schema. If an option list is itself sensitive, mark the column `filterable: false` or pass a copy of the columns without it.
+- **Always validate before applying.** Model output is untrusted input. Apply `state`, never the raw reply; show `errors` (or log them) so users can see what was ignored. Show the change to the user and keep it easy to undo.
+- **Check `schemaVersion`.** The schema carries `schemaVersion: 1`. It changes only when the shape of the schema changes, so you can cache prompts or fine-tuning data per version. The validator accepts a `schemaVersion` key in the reply and reports any value other than 1.
+
+## `getGridAiSchema(columns, options?)`
+
+Returns a plain JSON object (no functions), deterministic for the same columns and options, so you can memoise it with the columns.
+
+| Part (state key) | Option name | Shape | Taken from the columns |
+| :--- | :--- | :--- | :--- |
+| `filterModel` | `'filter'` | `GridFilterModel`: `items`, `logicOperator`, nested AND/OR groups up to 3 levels, `quickFilterValues` | Fields with `filterable !== false`; per field the operators of `getOperatorsForType(type)`; `value` typed per column type (number, `YYYY-MM-DD` string, boolean, `valueOptions` enum or a list of them for `isAnyOf`) |
+| `sortModel` | `'sort'` | `GridSortItem[]` | Fields with `sortable !== false` |
+| `rowGroupingModel` | `'grouping'` | `string[]` | Fields with `groupable !== false` |
+| `aggregationModel` | `'aggregation'` | field → function | `type: 'number'` (or `aggregable: true`) columns get every built-in function, other columns `count`; never `aggregable: false`; limited by `availableAggregationFunctions` |
+| `pivotModel` | `'pivot'` | `GridPivotModel` | Groupable fields as row and column labels; value fields as for aggregation (`sum`, `avg`, `count`, `min`, `max`) |
+| `columnVisibilityModel` | `'columnVisibility'` | field → boolean | Fields with `hideable !== false` |
+
+Each filter item is a `oneOf` per field (`field` is a `const`, `operator` an `enum`, `value` typed by the column), which the main structured-output APIs accept. A part that no column allows is left out of the schema.
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `include` | every part | Parts to offer: `'filter' \| 'sort' \| 'grouping' \| 'aggregation' \| 'pivot' \| 'columnVisibility'` |
+| `exclude` | none | Parts to leave out; wins over `include` |
+| `descriptions` | `true` | Put each column's `headerName` and `description` into the schema, so the model can map the user's words ("revenue") to a field (`amt_usd`) |
+| `examples` | `true` | Include the columns' `aiExamples`. Columns without `aiExamples` never send example values |
+
+Columns whose field starts with `__` (the grid's own `__check__`, `__group__` …) are skipped, so `apiRef.current.getAllColumns()` can be passed as is. The `columns` parameter takes any object with the `GridColDef` properties above (`GridAiColumn`); renderers, getters and formatters are ignored.
+
+Example for two columns:
+
+```ts
+getGridAiSchema(
+  [
+    { field: 'amt_usd', headerName: 'Revenue', type: 'number' },
+    { field: 'status', headerName: 'Status', type: 'singleSelect', valueOptions: ['Open', 'Paid'], groupable: false },
+  ],
+  { include: ['filter', 'sort'], descriptions: false },
+);
+// {
+//   $schema: 'https://json-schema.org/draft/2020-12/schema', schemaVersion: 1, title: 'OpenGridX grid state',
+//   type: 'object', additionalProperties: false,
+//   properties: {
+//     filterModel: { type: 'object', additionalProperties: false, properties: {
+//       items: { type: 'array', items: { anyOf: [{ $ref: '#/$defs/filterItem' }, { $ref: '#/$defs/filterGroup1' }] } },
+//       logicOperator: { enum: ['and', 'or'] },
+//       quickFilterValues: { type: 'array', items: { type: 'string' } } } },
+//     sortModel: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['field', 'sort'],
+//       properties: { field: { enum: ['amt_usd', 'status'] }, sort: { enum: ['asc', 'desc'] } } } },
+//   },
+//   $defs: {
+//     filterItem: { oneOf: [
+//       { type: 'object', required: ['field', 'operator'], additionalProperties: false, properties: {
+//         field: { const: 'amt_usd' }, operator: { enum: ['=', '!=', '>', '>=', '<', '<=', 'isEmpty', 'isNotEmpty'] },
+//         value: { type: 'number' } } },
+//       { type: 'object', required: ['field', 'operator'], additionalProperties: false, properties: {
+//         field: { const: 'status' }, operator: { enum: ['isAnyOf', 'is', 'not'] },
+//         value: { anyOf: [{ enum: ['Open', 'Paid'] }, { type: 'array', items: { enum: ['Open', 'Paid'] } }] } } },
+//     ] },
+//     filterGroup1: { … items: filterItem | filterGroup2 }, filterGroup2: { … }, filterGroup3: { … items: filterItem },
+//   },
+// }
+```
+
+## `validateGridAiState(json, columns, options?)`
+
+Returns `{ state, errors }`, where `state` is a `GridAiState` (`filterModel`, `sortModel`, `rowGroupingModel`, `aggregationModel`, `pivotModel`, `columnVisibilityModel`, each present only when the reply contained it) and `errors` is a list of `{ path, message }`, such as `{ path: 'filterModel.items[2].field', message: 'Unknown field "revenue"' }`.
+
+- `json` may be an object or a JSON string. Bad JSON gives one error and an empty state.
+- Unknown parts, unknown fields, fields a column does not allow (`filterable: false` …), operators that do not fit the column type, and functions or enum values outside the allowed list are **dropped**, each with an error. Parts outside `options.include` / `options.exclude` are dropped too.
+- Values are coerced to the column type with the same rules as clipboard paste: `"1,200"`, `"$1,200"` → `1200`, `"12%"` → `0.12`; `"yes"` / `"no"` / `"1"` / `"0"` → booleans; dates (ISO or anything `Date.parse` reads) → the local day as `"YYYY-MM-DD"`, as the filter panel writes it; `singleSelect` values match an option value or label, case-insensitively, and become the option's value. A filter without a usable value is dropped.
+- `asc` / `desc`, `and` / `or`, operators and function names are matched case-insensitively and written in their canonical spelling.
+- A filter group left empty is removed; groups nested deeper than 3 levels are dropped.
+- Lists are read up to 200 entries and at most 100 errors are listed, so a runaway reply stays cheap.
+- It never throws, never returns a field the columns do not allow, and reads only own keys of the reply (never `__proto__`), so a reply cannot reach `Object.prototype`.
+
+Applying an empty part is meaningful: `{ sortModel: [] }` clears the sort. Only apply the parts present in `state`.
+
+## Related
+
+- [Filtering](filtering.md), [Sorting & Pagination](sorting-pagination.md), [Aggregation & Pivot](aggregation-pivot.md), [Tree Data & Grouping](tree-data-grouping.md): the models the schema describes.
+- [API Reference: AI Toolkit](../API_REFERENCE.md)