@opencorestack/opengridx 3.3.0 → 3.5.0

package/docs/features/header-filters.md

@@ -0,0 +1,138 @@
+# Header Filters
+
+*Since v3.5.0*
+
+A filter row under the column headers, as in Excel's AutoFilter row: each column gets a small control (a text box, a number or date box, or a select), an operator button and a clear button. It reads and writes the grid's one `filterModel`, so the [filter panel](../components/filter-panel.md), the quick filter, `apiRef.setFilterModel` and server-side filtering keep working alongside it.
+
+```tsx
+import { DataGrid } from '@opencorestack/opengridx';
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  headerFilters
+  height={500}
+/>
+```
+
+The row is off unless `headerFilters` is set. Without it the grid renders and behaves exactly as before.
+
+## Controls per column type
+
+| Column `type` | Control | Starting operator |
+| :--- | :--- | :--- |
+| `string` (default) | text box (`Input`) | `contains` |
+| `number` | text box (`Input`, decimal keyboard on touch devices) | `=` |
+| `date` | date box (`Input type="date"`) | `is` |
+| `boolean` | select: Any / Yes / No | `is` |
+| `singleSelect` | select of `valueOptions` (Any + every option) | `is` |
+| `image` | none (empty cell) | — |
+
+- The **operator button** left of the box shows the current operator as a symbol (`∋` contains, `=`, `≥`, `≠` …) and opens a menu of the operators the column type allows (the same list as the filter panel). `isEmpty` / `isNotEmpty` need no value: the box is replaced by the operator's name.
+- The **clear button** (×) appears while the column has a filter and removes it.
+- Typing is **debounced by 300 ms**, as in the filter panel. Selects apply at once. Typing that is still waiting is committed if the column scrolls out of the render window or the row is turned off.
+- A `singleSelect` column without `valueOptions` gets a text box.
+
+### Column options
+
+| `GridColDef` field | Description |
+| :--- | :--- |
+| `headerFilter?: boolean` | `false` leaves the column's cell empty. Columns with `filterable: false` and `type: 'image'` have no control either. |
+| `headerFilterOperator?: GridFilterOperator` | The operator a new filter starts with, instead of the type's default (for example `'>='` for amounts, `'startsWith'` for codes). |
+
+### Grid props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `headerFilters` | `boolean` | `false` | Renders the filter row. |
+| `headerFilterHeight` | `number` | `40` | Height of the filter row in pixels (sets `--ogx-header-filter-height`). |
+
+## One shared filter model
+
+The row does not keep a model of its own. Each cell **owns one root-level item**, the one with `id: 'header:<field>'`:
+
+```ts
+// After typing "glo" under Customer and choosing "≥ 100" under Total:
+{
+  items: [
+    { id: 'header:customer', field: 'customer', operator: 'contains', value: 'glo' },
+    { id: 'header:total', field: 'total', operator: '>=', value: '100' },
+  ],
+}
+```
+
+- A cell adds its item at the end of `items`, updates it in place and removes it when cleared. Every other item and group, `logicOperator` and `quickFilterValues` pass through untouched.
+- Values are stored as the filter panel stores them: typed text as a string (number operators parse it), dates as `YYYY-MM-DD`, booleans as `true` / `false`, `singleSelect` values as the option's `value` (a one-item list for `isAnyOf`).
+- The filter panel shows and edits the same item: it edits the first root item of each column and keeps its `id`, so a header filter changed in the panel is still the header filter.
+- An item with an empty value does not filter. An empty box with the starting operator removes the item; with another operator the item stays, so the chosen operator is kept while the value is retyped.
+
+### Models the row cannot show
+
+The row never rewrites a model it cannot represent. A cell shows a read-only **"Custom filter"** label instead of its control when:
+
+- the root `logicOperator` is `'or'` (every cell: adding an item would widen the OR);
+- the column's field appears inside a filter group;
+- the column has a root item that is not `header:<field>` (one added by the filter panel, `apiRef`, an AI assistant or your own code), or more than one root item.
+
+With a built-in `GridToolbar` in `slots.toolbar`, the label is a button that opens the toolbar's filter panel, where the condition can be edited. Without one it is plain text. Clearing the model (the panel's *Clear all*, `setFilterModel({ items: [] })`) brings the controls back.
+
+## Server-side filtering
+
+With `filterMode="server"` the grid does not filter rows itself; header filter changes reach `onFilterModelChange` (or the `dataSource`'s `getRows`) like any other filter change. Items are tagged `header:<field>`, which the server can ignore.
+
+```tsx
+<DataGrid
+  rows={pageRows}
+  columns={columns}
+  headerFilters
+  filterMode="server"
+  filterModel={filterModel}
+  onFilterModelChange={(model) => { setFilterModel(model); refetch(model); }}
+/>
+```
+
+## Keyboard and screen readers
+
+The filter row is a header row (`role="row"`) between the column headers and the first data row. Its cells are `role="columnheader"`, labelled **"Filter &lt;header name&gt;"**, with the same `aria-colindex` as their column; `aria-rowcount` and the rows' `aria-rowindex` count it.
+
+| Key | On a filter cell |
+| :--- | :--- |
+| ArrowDown on a column header | Moves to that column's filter cell |
+| ArrowDown / ArrowUp | First data row / the column header |
+| ArrowLeft / ArrowRight, Home / End | Along the filter row |
+| Enter or Space | Focuses the cell's control ("Custom filter": opens the filter panel) |
+| Typing a character | Starts a new value in the text box (text and number columns) |
+| Alt+ArrowDown or Ctrl/Cmd+Enter | Opens the operator menu (arrows move, Enter picks, Escape closes) |
+| Delete / Backspace | Clears the column's filter |
+
+Inside a control, arrow keys edit the text (or move through a select) and do not move the grid's focus, as in a cell editor. **Escape** returns focus to the filter cell. **Tab** leaves the grid: the grid stays a single Tab stop and every control in the row has `tabIndex={-1}`.
+
+## Layout
+
+- The row sits inside the sticky header block (`.ogx__header-wrap`), under any column group rows and the column header row, so it stays at the top while rows scroll.
+- Each cell takes its column's width, flex and sticky offset from the same calculation as the column header, so filter cells line up with their columns with pinned columns, column virtualization and horizontal scrolling.
+- Scrolling a row into view (keyboard navigation, `apiRef.scrollToIndexes`, cell range auto-scroll) measures the sticky header, so rows are never left under the taller header.
+- With `pivotMode` active the row is not rendered: pivot columns are generated and are not the fields the filter model names.
+
+## Styling
+
+| Class | Element |
+| :--- | :--- |
+| `ogx__header-filter-row` | The row |
+| `ogx__header-filter-cell` | Every cell, plus `--focused`, `--active` (has a filter), `--custom` ("Custom filter"), `--empty` (no control), `--system` (under the checkbox, expand and reorder columns), `--pinned`, `--pinned-left`, `--pinned-right`, `--pinned-left-last`, `--pinned-right-first` |
+| `ogx__header-filter-operator` | The operator button (`--open` while its menu is open) |
+| `ogx__header-filter-menu` | The operator menu (also `ogx-column-menu`, so it looks like the column menu) |
+| `ogx__header-filter-input-wrapper` / `ogx__header-filter-input` | The `Input` wrapper and its `<input>` |
+| `ogx__header-filter-select` | The boolean and `singleSelect` select |
+| `ogx__header-filter-operator-label` | The operator name shown for `isEmpty` / `isNotEmpty` |
+| `ogx__header-filter-clear` | The clear button |
+| `ogx__header-filter-custom` | The "Custom filter" label or button |
+
+The row uses the header's theme variables (`--ogx-grid-header-background`, `--ogx-grid-border-color`, `--ogx-grid-header-text`, `--ogx-grid-header-hover-background`) and the shared input variables, so every built-in theme and dark mode style it without new variables. `--ogx-header-filter-height` holds its height.
+
+## See also
+
+- [Filtering & Search](filtering.md) — operators, AND/OR groups and the quick filter
+- [Filter Panel](../components/filter-panel.md)
+- [Keyboard & Accessibility](keyboard-navigation.md)
+- Demo: *Header Filters* (`/header-filters`)

package/docs/features/keyboard-navigation.md

@@ -37,6 +37,20 @@ With [`cellSelection`](cell-selection.md) on (v3.3), on a data cell:
 | **Ctrl+Shift+Home** / **Ctrl+Shift+End** (Cmd on macOS) | Extend to the first / last cell of the page. |
 | **Shift+PageUp** / **Shift+PageDown** | Extend one page up / down. |
 | **Escape** | Collapse the range to the anchor (when not editing). |
+| **Ctrl+V** (Cmd+V) | Paste tab-separated text into the editable cells from the range's top-left cell (v3.4, see [Clipboard](clipboard.md#-paste-from-excel-and-google-sheets-v34)). Off with `disableClipboardPaste`. |
+| **Delete** / **Backspace** | On a range of more than one cell: empty its editable cells in one edit (v3.4). Off with `disableRangeClear`. |
+| **Ctrl+D** (Cmd+D) | Fill down: copy the range's top row into the rows below it, in one edit (v3.5, see [Fill Handle](fill-handle.md)). The browser's bookmark shortcut does not fire. Off with `disableFillHandle`. |
+| **Ctrl+R** (Cmd+R) | Fill right: copy the range's left column into the columns right of it, in one edit (v3.5). The browser's reload shortcut does not fire. Off with `disableFillHandle`. |
+| **Escape** during a fill-handle drag | Cancel the fill: nothing is written and the range goes back (v3.5). |
+
+With `undoRedo` on (v3.4, see [Undo & Redo](undo-redo.md)), while focus is on a cell and no editor is open:
+
+| Key | Action |
+| :--- | :--- |
+| **Ctrl+Z** (Cmd+Z) | Undo the last edit, paste or range clear. |
+| **Ctrl+Shift+Z** (Cmd+Shift+Z) or **Ctrl+Y** | Redo. |
+
+Inside an open editor these keys belong to the input (its own paste and undo).
 
 A plain arrow key after a range collapses it to the newly focused cell. Shift+Space still selects the row.
 
@@ -59,10 +73,25 @@ When an edit ends, focus returns to the edited cell unless you moved it elsewher
 | **Enter** / **Space** | Sort the column (asc → desc → none), replacing the sort model; with `multiSort`, or with **Shift** held, the column is added to (or updated or removed from) the sort model instead, as a header click or shift-click does. On the select-all header: select or clear all rows. |
 | **Alt+ArrowDown** or **Ctrl+Enter** (Cmd+Enter) | Open the column menu. |
 | **Alt+ArrowRight** / **Alt+ArrowLeft** | Widen / narrow the column by 10px (with **Shift**: 50px). Not for `resizable: false` columns. |
-| **ArrowDown** | Move to the first row. |
+| **ArrowDown** | Move to the first row; with `headerFilters`, to the column's filter cell. |
 
 In the column menu, **ArrowUp** / **ArrowDown** / **Home** / **End** move between items, **Enter** / **Space** choose one, and **Escape** or **Tab** closes the menu. Focus returns to the column header.
 
+### Header filter row
+
+With `headerFilters` (v3.5, see [Header Filters](header-filters.md)) the filter row sits between the column headers and the first row. Its cells are navigation stops like any other cell:
+
+| Key | Action |
+| :--- | :--- |
+| **ArrowDown** / **ArrowUp** | To the first row / back to the column header. Arrow keys from the first row go up to the filter row. |
+| **ArrowLeft** / **ArrowRight**, **Home** / **End** | Along the filter row. |
+| **Enter** / **Space** | Focus the cell's text box or select. On "Custom filter": open the toolbar's filter panel. |
+| Typing a character | Start a new value in the text box (text and number columns). |
+| **Alt+ArrowDown** or **Ctrl+Enter** (Cmd+Enter) | Open the operator menu; it works like the column menu. |
+| **Delete** / **Backspace** | Clear the column's filter. |
+
+Inside the text box or select, the arrow keys belong to the control, as in a cell editor. **Escape** returns focus to the filter cell; **Tab** leaves the grid (the controls are not Tab stops).
+
 ### List view
 
 In `listView`, focus moves between whole rows instead of cells:
@@ -84,7 +113,7 @@ Keys pressed in content your `renderCell` puts in a row (inputs, buttons) are le
 | Element | Attributes |
 | :--- | :--- |
 | Viewport | `role="grid"`, `aria-rowcount`, `aria-colcount`, `aria-multiselectable` (true when several rows can be selected), `aria-busy`. |
-| Header rows | `role="row"` with `aria-rowindex`: column-group rows first, then the column header row. |
+| Header rows | `role="row"` with `aria-rowindex`: column-group rows first, then the column header row, then the header filter row (`headerFilters`), whose cells are `role="columnheader"` labelled "Filter <header>". |
 | Data rows | `role="row"`, `aria-rowindex` counted across the whole dataset (page 2 continues after page 1; bottom-pinned rows come after every page), `aria-selected`. Tree-data and row-grouping rows add `aria-level`; rows with children add `aria-expanded`. |
 | Cells and headers | `aria-colindex`, identical for a header and the body cells below it. The system columns (reorder handle, detail-panel toggle, checkbox) come first. |
 | Sorted headers | Only the primary sort column has `aria-sort="ascending"` / `"descending"`; with several sort keys every sorted header also gets an `aria-description` such as "Sorted descending, sort priority 2 of 2". |

package/docs/features/undo-redo.md

@@ -0,0 +1,79 @@
+# Undo & Redo
+
+`undoRedo` (v3.4) lets users undo and redo their cell edits, pastes and range clears. It is off by default: your app may already own Ctrl+Z, and undo writes data. Demo: **Undo & Redo** (`/undo-redo`).
+
+```tsx
+import { DataGrid, useGridApiRef, type GridHistoryChangeParams } from '@opencorestack/opengridx';
+
+function Budget({ rows, columns, saveRow }) {
+  const apiRef = useGridApiRef();
+  const [history, setHistory] = useState<GridHistoryChangeParams>({ canUndo: false, canRedo: false, size: 0 });
+
+  return (
+    <>
+      <button disabled={!history.canUndo} onClick={() => apiRef.current.undo()}>Undo</button>
+      <button disabled={!history.canRedo} onClick={() => apiRef.current.redo()}>Redo</button>
+      <DataGrid
+        rows={rows}
+        columns={columns}
+        apiRef={apiRef}
+        cellSelection               // for paste and range clear; undo works without it
+        undoRedo                    // or { limit: 50 }; default 100 actions
+        onHistoryChange={setHistory}
+        processRowUpdate={saveRow}  // undo and redo save through it too
+      />
+    </>
+  );
+}
+```
+
+## Keys
+
+| Key | Action |
+| :--- | :--- |
+| **Ctrl+Z** (Cmd+Z) | Undo |
+| **Ctrl+Shift+Z** (Cmd+Shift+Z) or **Ctrl+Y** | Redo |
+
+Only while focus is in the grid (a cell) and no editor is open. Inside an editor, a text field you render in a cell, or anywhere else on the page, the keys keep their native meaning (the input's own undo). After an undo or redo the affected cells become the selection (their bounding rectangle, with `cellSelection`; otherwise focus moves to the first one) and the first one is scrolled into view.
+
+## What is recorded
+
+Each committed action is a list of cell changes `{ id, field, before, after }`:
+
+| Action | Recorded |
+| :--- | :--- |
+| A single-cell edit | 1 change |
+| A paste or a range clear | Every cell that was written (skipped cells are not) |
+| Values `processRowUpdate` changed itself (a recomputed `total`) | Not recorded: only the fields the user changed. Your recomputation runs again on undo |
+
+An action is recorded **only after `processRowUpdate` succeeded**, with `after` read from the stored row through `valueGetter`. A row that `processRowUpdate` rejected is not recorded, so history never claims a change your app refused. A change whose stored value equals the old one (for example normalised back by `processRowUpdate`) is not recorded either.
+
+A new action after an undo clears the redo stack. Beyond `limit` actions the oldest is dropped.
+
+**Not undoable:** sorting, filtering, column changes, row reordering, row selection and cell selection. These are view state, not data.
+
+## How undo writes
+
+Undo writes the `before` values as a new batch edit, so `valueSetter` and `processRowUpdate` run as for any edit and your app persists the undo the way it persists edits. Redo writes the `after` values. One `processRowUpdate` call per row; rows run in parallel; a row that fails is reported to `onProcessRowUpdateError`, keeps its part of the action on the stack to try again, and does not stop the others.
+
+### Stale entries
+
+If a cell no longer holds its recorded `after` value (it was edited again, or the `rows` prop brought new data), undo **skips that cell** with reason `'changed'` and applies the rest. A row that no longer exists is skipped with reason `'missing'`. Values are compared, not row objects, so an app that re-fetches its rows after saving keeps a working history. Redo checks the same way against the value undo wrote.
+
+```ts
+const result = await apiRef.current.undo();
+// { updated: [3, 7], failed: [], skipped: [{ id: 5, field: 'price', reason: 'changed' }] }
+```
+
+## API
+
+| Member | Description |
+| :--- | :--- |
+| `undoRedo?: boolean \| { limit?: number }` | Turns history on. Default `false`; `limit` default 100. Turning it off clears the history. |
+| `onHistoryChange?({ canUndo, canRedo, size })` | Fired when what can be undone or redone changes. `size` is the number of actions that can be undone. |
+| `apiRef.current.undo()` | Undoes the last action. Resolves with a `GridBatchEditResult` once every row has settled. |
+| `apiRef.current.redo()` | Redoes the last undone action. |
+| `apiRef.current.canUndo()` / `canRedo()` | Whether there is something to undo / redo. |
+| `apiRef.current.clearHistory()` | Forgets every action. |
+
+Undo and redo calls run one after another, each on the rows the previous one stored.

package/docs/roadmap.md

@@ -83,8 +83,8 @@ This document tracks the current status of features in `OpenGridX` and outlines
 | Release | Target | Headline | Also in it |
 | :--- | :--- | :--- | :--- |
 | **3.3.0** ✅ | shipped 7 Oct | **Cell range selection** (opt-in `cellSelection` prop): mouse drag, Shift+click, Shift+arrows; Ctrl+C / Cmd+C copies the block as TSV | Selection status bar (count, sum, average of selected cells); wrapped header text; React Compiler compatibility check |
-| **3.4.0** | 20 Nov | **Paste from Excel / Google Sheets** into the selection, through `processRowUpdate` (values parsed per column type, non-editable cells skipped, `onClipboardPasteError`). **Undo / redo** for cell edits and pastes (Ctrl+Z, Ctrl+Shift+Z / Ctrl+Y, `apiRef.undo()` / `redo()`) | **AI toolkit, part 1** in a new `@opencorestack/opengridx/ai` entry point: `getGridAiSchema(columns)` (JSON Schema of the filter, sort, grouping, aggregation, pivot and visibility models the columns allow) and `validateGridAiState(json, columns)` (drops unknown fields and operators, coerces values, returns errors) |
-| **3.5.0** | 15 Dec | **AI toolkit, part 2**: `aiAssistant={{ onPrompt }}` prompt panel that calls the app's own model, shows the proposed changes as removable chips and applies them with undo; `createGridAgentTools(apiRef)` (plain tool objects for CopilotKit, the Vercel AI SDK or WebMCP) | Header filter row; **fill handle** as a stretch goal (moves to Q1 2027 if 3.3–3.4 run late) |
+| **3.4.0** ✅ | shipped 8 Oct | **Paste from Excel / Google Sheets** into the selection, through `processRowUpdate` (values parsed per column type or `valueParser`, non-editable cells skipped, `onClipboardPaste` summary); **Delete clears a range**; built-in inputs and editors use the shared `Input` / `Checkbox` (`Input variant="cell"`). **Undo / redo** for cell edits and pastes (Ctrl+Z, Ctrl+Shift+Z / Ctrl+Y, `apiRef.undo()` / `redo()`) | **AI toolkit, part 1** in a new `@opencorestack/opengridx/ai` entry point: `getGridAiSchema(columns)` (JSON Schema of the filter, sort, grouping, aggregation, pivot and visibility models the columns allow) and `validateGridAiState(json, columns)` (drops unknown fields and operators, coerces values, returns errors) |
+| **3.5.0** ✅ | shipped 9 Oct | **AI toolkit, part 2**: `aiAssistant={{ onPrompt }}` Ask AI panel (chips, Undo, voice) that calls the app's own model through `createGridAiPromptHandler`; only validated replies apply; `createGridAgentTools(apiRef, columns)` (plain tool objects for CopilotKit, the Vercel AI SDK, provider tool calling or WebMCP) | **Header filter row** (`headerFilters`); **fill handle** (series, Alt copy, Ctrl/Cmd+D / R); `rowGroupingModel` controlled/uncontrolled pair |
 | Freeze | 19 Dec – 5 Jan | Bug fixes only | — |
 
 ### Across the quarter
@@ -106,7 +106,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 
 *   OpenGridX never calls an AI service and never bundles an AI SDK. The app passes a function that calls whichever model it uses.
 *   By default only column definitions and grid state are sent, never row data. Example values are opt-in per column and documented as real data.
-*   Model output is always validated against the schema and shown to the user before it changes the grid, with one-click undo.
+*   Model output is always validated against the schema (the grid applies only a validated, branded result), and every change it makes is shown as a removable chip with one-click undo.
 *   The schema carries a `schemaVersion`, since apps will cache prompts against it.
 
 ### Risks
@@ -118,7 +118,6 @@ This document tracks the current status of features in `OpenGridX` and outlines
 ## 🔭 Next (Q1 2027)
 
 *   **Row reordering inside tree data and row groups**, touch-friendly (MUI #4821, 405 👍, not in MUI X).
-*   **Fill handle**, if it does not make 3.5.0.
 *   **Find & highlight** (Ctrl+F through cells), **right-click context menu**, **Excel-style value (set) filter**.
 *   **Calculated columns** (`[price] * [qty]` defined by users).
 *   **Interactive pivot builder**: drag-and-drop panel for pivot and grouping.

package/lib/ai/agentTools.ts

@@ -0,0 +1,160 @@
+// createGridAgentTools: plain tool objects ({ name, description, inputSchema, execute }) that let an AI
+// agent read and change the grid through its apiRef. No SDK: they fit the Vercel AI SDK, CopilotKit,
+// OpenAI or Anthropic tool calling and WebMCP. Every input is validated; execute never throws.
+import type { GridAiState, GridRowModel } from '../types';
+import { getCellValue } from '../utils/values';
+
+type CellColumn = Parameters<typeof getCellValue>[2];
+import { hasOwn, isPlainObject, PART_KEYS, usableColumns } from './columns';
+import { getGridAiSchema } from './schema';
+import type {
+  GridAgentApi,
+  GridAgentTool,
+  GridAgentToolResult,
+  GridAgentToolsOptions,
+  GridAiColumn,
+  GridAiJsonSchema,
+  GridAiPart,
+} from './types';
+import { validateGridAiState } from './validate';
+
+const DEFAULT_MAX_ROWS = 20;
+const MAX_ROWS_LIMIT = 1000;
+
+const SET_TOOLS: { name: string; part: GridAiPart; description: string }[] = [
+  { name: 'set_filter', part: 'filter', description: 'Replace the filter model of the grid (filters and quick-filter words).' },
+  { name: 'set_sort', part: 'sort', description: 'Replace the sort model of the grid, most significant field first. An empty list clears sorting.' },
+  { name: 'set_grouping', part: 'grouping', description: 'Group the rows by these fields, outermost first. An empty list removes grouping.' },
+  { name: 'set_aggregation', part: 'aggregation', description: 'Replace the summaries: field to aggregation function. An empty object removes them.' },
+  { name: 'set_column_visibility', part: 'columnVisibility', description: 'Show (true) or hide (false) columns. Columns not listed keep their visibility.' },
+];
+
+type ApiRef = { readonly current: GridAgentApi | null | undefined };
+
+function failure(message: string, path = ''): GridAgentToolResult {
+  return { ok: false, errors: [{ path, message }] };
+}
+
+/** Runs a tool body; a throw becomes `{ ok: false }`. */
+async function run(body: () => GridAgentToolResult): Promise<GridAgentToolResult> {
+  try {
+    return body();
+  } catch (error) {
+    return failure(error instanceof Error && error.message ? error.message : 'The tool failed');
+  }
+}
+
+function apiOf(apiRef: ApiRef): GridAgentApi | null {
+  const api = apiRef?.current;
+  return api && typeof api.getGridAiState === 'function' ? api : null;
+}
+
+/** A JSON-safe cell value: primitives as they are, a Date as an ISO string, anything else null. */
+function jsonValue(value: unknown): unknown {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  return typeof value === 'string' || typeof value === 'boolean' ? value : null;
+}
+
+function setTool(apiRef: ApiRef, columns: readonly GridAiColumn[], name: string, part: GridAiPart, description: string): GridAgentTool | null {
+  const key = PART_KEYS[part] as keyof GridAiState;
+  const schema = getGridAiSchema(columns, { include: [part] });
+  if (!hasOwn(schema.properties, key)) return null;
+  const { $schema: _version, schemaVersion: _schemaVersion, title: _title, description: _description, ...inputSchema } = schema;
+  return {
+    name,
+    description,
+    inputSchema: { ...inputSchema, required: [key] },
+    execute: (input) => run(() => {
+      const api = apiOf(apiRef);
+      if (!api) return failure('The grid is not ready');
+      if (!isPlainObject(input) || !hasOwn(input, key)) return failure(`Expected an object with "${key}"`, key);
+      const { state, errors } = validateGridAiState({ [key]: input[key] }, columns, { include: [part] });
+      // All or nothing: the agent gets the errors back and can correct its call.
+      if (errors.length > 0) return { ok: false, errors };
+      const applied: GridAiState = {};
+      if (state.filterModel) api.setFilterModel(applied.filterModel = state.filterModel);
+      if (state.sortModel) api.setSortModel(applied.sortModel = state.sortModel);
+      if (state.rowGroupingModel) api.setRowGroupingModel(applied.rowGroupingModel = state.rowGroupingModel);
+      if (state.aggregationModel) api.setAggregationModel(applied.aggregationModel = state.aggregationModel);
+      if (state.columnVisibilityModel) {
+        applied.columnVisibilityModel = { ...api.getGridAiState().columnVisibilityModel, ...state.columnVisibilityModel };
+        api.setColumnVisibilityModel(applied.columnVisibilityModel);
+      }
+      return { ok: true, applied };
+    }),
+  };
+}
+
+const NO_INPUT: GridAiJsonSchema = { type: 'object', properties: {}, additionalProperties: false };
+
+/**
+ * Tools for an AI agent: `get_grid_state`, `set_filter`, `set_sort`, `set_grouping`, `set_aggregation`,
+ * `set_column_visibility`, `clear_filters`, and `get_row_summary` only with `allowRowAccess: true` (the
+ * one tool that sends row values). Each tool is `{ name, description, inputSchema, execute }`; inputs are
+ * checked with `validateGridAiState` and applied through `apiRef` only when valid. `execute` never throws.
+ * @since v3.5
+ */
+export function createGridAgentTools<C extends GridAiColumn>(
+  apiRef: ApiRef,
+  columns: readonly C[],
+  options: GridAgentToolsOptions = {},
+): GridAgentTool[] {
+  const cols = usableColumns(columns);
+  const tools: GridAgentTool[] = [{
+    name: 'get_grid_state',
+    description: 'Read the current filter, sort, grouping, aggregation, pivot and column visibility of the grid, and its columns.',
+    inputSchema: NO_INPUT,
+    execute: () => run(() => {
+      const api = apiOf(apiRef);
+      if (!api) return failure('The grid is not ready');
+      return {
+        ok: true,
+        state: api.getGridAiState(),
+        columns: cols.map((c) => ({ field: c.field, headerName: typeof c.headerName === 'string' ? c.headerName : c.field, type: typeof c.type === 'string' ? c.type : 'string' })),
+      };
+    }),
+  }];
+  for (const { name, part, description } of SET_TOOLS) {
+    const tool = setTool(apiRef, cols, name, part, description);
+    if (tool) tools.push(tool);
+  }
+  tools.push({
+    name: 'clear_filters',
+    description: 'Remove every filter and the quick-filter words.',
+    inputSchema: NO_INPUT,
+    execute: () => run(() => {
+      const api = apiOf(apiRef);
+      if (!api) return failure('The grid is not ready');
+      const filterModel = { items: [] };
+      api.setFilterModel(filterModel);
+      return { ok: true, applied: { filterModel } };
+    }),
+  });
+  if (options.allowRowAccess === true) {
+    const maxRows = typeof options.maxRows === 'number' && options.maxRows >= 1 ? Math.min(Math.floor(options.maxRows), MAX_ROWS_LIMIT) : DEFAULT_MAX_ROWS;
+    const allowed = Array.isArray(options.fields) ? cols.filter((c) => options.fields?.includes(c.field)) : cols;
+    tools.push({
+      name: 'get_row_summary',
+      description: `Count the rows that pass the current filter and read the first ones (at most ${maxRows}, fields: ${allowed.map((c) => c.field).join(', ')}).`,
+      inputSchema: { type: 'object', properties: { limit: { type: 'integer', minimum: 1, maximum: maxRows } }, additionalProperties: false },
+      execute: (input) => run(() => {
+        const api = apiOf(apiRef);
+        if (!api) return failure('The grid is not ready');
+        const raw = isPlainObject(input) && hasOwn(input, 'limit') ? input.limit : maxRows;
+        const limit = typeof raw === 'number' && raw >= 1 ? Math.min(Math.floor(raw), maxRows) : maxRows;
+        const all = api.getAllFilteredRows();
+        const list = Array.isArray(all) ? all : [];
+        const rows = list.slice(0, limit).map((row) => {
+          const out: Record<string, unknown> = {};
+          if (!isPlainObject(row)) return out;
+          // Through the column's valueGetter, as the grid shows the cell.
+          for (const col of allowed) out[col.field] = jsonValue(getCellValue(row as GridRowModel, col.field, col as CellColumn));
+          return out;
+        });
+        return { ok: true, rowCount: list.length, rows };
+      }),
+    });
+  }
+  return tools;
+}

package/lib/ai/coerce.ts

@@ -0,0 +1,90 @@
+// Value coercion for the AI validator. Text goes through the same parsers as clipboard paste
+// (`lib/utils/parsing.ts`), so a value the grid accepts from Excel is accepted from a model and the
+// other way round. Model output is JSON, so typed values (a number, a boolean, a Date) are taken as
+// they are. Empty input is valid: null, or '' for text columns.
+import {
+  parseBooleanText,
+  parseDateText,
+  parseNumberText,
+  parseSingleSelectText,
+  type GridParsedValue,
+} from '../utils/parsing';
+
+export type CoerceResult<T = unknown> = { ok: true; value: T } | { ok: false; reason: 'invalidValue' };
+
+/** The column properties coercion reads. */
+export interface CoerceColumn {
+  type?: string;
+  valueOptions?: readonly (string | number | { value: unknown; label: string })[];
+}
+
+const ok = <T>(value: T): CoerceResult<T> => ({ ok: true, value });
+const INVALID: CoerceResult<never> = { ok: false, reason: 'invalidValue' };
+
+const fromParsed = <T>(parsed: GridParsedValue): CoerceResult<T> =>
+  parsed.ok ? ok(parsed.value as T) : INVALID;
+
+function isBlank(text: unknown): boolean {
+  return text == null || (typeof text === 'string' && text.trim() === '');
+}
+
+/** `string` and `image` columns: text as is. Numbers and booleans become their text. */
+export function coerceString(text: unknown): CoerceResult<string> {
+  if (text == null) return ok('');
+  if (typeof text === 'string') return ok(text);
+  if (typeof text === 'number' || typeof text === 'boolean') return ok(String(text));
+  return INVALID;
+}
+
+/** `number` columns: a finite number, or text in the paste format (`1,234.5`, `12%`, `$40`). */
+export function coerceNumber(text: unknown): CoerceResult<number | null> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text === 'number') return Number.isFinite(text) ? ok(text) : INVALID;
+  if (typeof text !== 'string') return INVALID;
+  return fromParsed(parseNumberText(text));
+}
+
+/** `date` columns: a Date, epoch milliseconds, or text in the paste format (ISO `2026-10-07` …). */
+export function coerceDate(text: unknown): CoerceResult<Date | null> {
+  if (isBlank(text)) return ok(null);
+  if (text instanceof Date) return Number.isNaN(text.getTime()) ? INVALID : ok(text);
+  if (typeof text === 'number') return Number.isFinite(text) ? ok(new Date(text)) : INVALID;
+  if (typeof text !== 'string') return INVALID;
+  return fromParsed(parseDateText(text));
+}
+
+/** `boolean` columns: a boolean, or `true`/`false`, `yes`/`no`, `1`/`0` (case-insensitive). */
+export function coerceBoolean(text: unknown): CoerceResult<boolean | null> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text === 'boolean') return ok(text);
+  if (typeof text !== 'string' && typeof text !== 'number') return INVALID;
+  return fromParsed(parseBooleanText(String(text)));
+}
+
+/**
+ * `singleSelect` columns: an option value or label, case-insensitive; returns the option's value.
+ * Without `valueOptions` the model has nothing to choose from, so any scalar is kept as it is.
+ */
+export function coerceSingleSelect(text: unknown, colDef: CoerceColumn): CoerceResult<unknown> {
+  if (isBlank(text)) return ok(null);
+  if (typeof text !== 'string' && typeof text !== 'number' && typeof text !== 'boolean') return INVALID;
+  const options = colDef.valueOptions;
+  if (!options || options.length === 0) return ok(text);
+  return fromParsed(parseSingleSelectText(String(text), options));
+}
+
+/** Coerces `text` for the column's `type`. */
+export function coerceValue(text: unknown, colDef: CoerceColumn): CoerceResult<unknown> {
+  switch (colDef.type) {
+    case 'number':
+      return coerceNumber(text);
+    case 'date':
+      return coerceDate(text);
+    case 'boolean':
+      return coerceBoolean(text);
+    case 'singleSelect':
+      return coerceSingleSelect(text, colDef);
+    default:
+      return coerceString(text);
+  }
+}

package/lib/ai/columns.ts

@@ -0,0 +1,90 @@
+// Which columns may take part in each part of the state. The schema and the validator both read
+// these, so the model is never offered a field the validator would drop.
+import { getOperatorsForType } from '../utils/filtering';
+import type { GridFilterOperator, GridPivotAggFn } from '../types';
+import type { GridAiColumn, GridAiPart, GridAiPartOptions } from './types';
+
+/** The built-in aggregation functions (`AGGREGATION_FUNCTIONS` in lib/utils/aggregation). */
+export const AGGREGATION_FNS: readonly string[] = ['sum', 'avg', 'count', 'min', 'max', 'unique'];
+/** The functions a pivot value field takes (`GridPivotAggFn`). */
+export const PIVOT_FNS: readonly GridPivotAggFn[] = ['sum', 'avg', 'count', 'min', 'max'];
+/** Operators without a value. */
+export const NO_VALUE_OPS: readonly string[] = ['isEmpty', 'isNotEmpty'];
+/** Deepest nesting of filter groups. */
+export const MAX_FILTER_DEPTH = 3;
+
+export const ALL_PARTS: readonly GridAiPart[] = ['filter', 'sort', 'grouping', 'aggregation', 'pivot', 'columnVisibility'];
+
+/** State key of each part, in output order. */
+export const PART_KEYS: Record<GridAiPart, string> = {
+  filter: 'filterModel',
+  sort: 'sortModel',
+  grouping: 'rowGroupingModel',
+  aggregation: 'aggregationModel',
+  pivot: 'pivotModel',
+  columnVisibility: 'columnVisibilityModel',
+};
+
+export function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function selectedParts(options: GridAiPartOptions | undefined): GridAiPart[] {
+  const include = Array.isArray(options?.include) ? options.include : ALL_PARTS;
+  const exclude = Array.isArray(options?.exclude) ? options.exclude : [];
+  return ALL_PARTS.filter((part) => include.includes(part) && !exclude.includes(part));
+}
+
+/**
+ * The usable columns, first one per field. System columns (`__check__`, `__group__`, …), spacers
+ * and fields that are not plain strings are skipped.
+ */
+export function usableColumns(columns: readonly GridAiColumn[] | unknown): GridAiColumn[] {
+  if (!Array.isArray(columns)) return [];
+  const seen = new Set<string>();
+  const out: GridAiColumn[] = [];
+  for (const col of columns as unknown[]) {
+    if (!isPlainObject(col)) continue;
+    const field = col.field;
+    if (typeof field !== 'string' || field === '' || field.startsWith('__') || col.isSpacer === true || seen.has(field)) continue;
+    seen.add(field);
+    out.push(col as unknown as GridAiColumn);
+  }
+  return out;
+}
+
+export function operatorsOf(col: GridAiColumn): GridFilterOperator[] {
+  return getOperatorsForType(col.type);
+}
+
+export const isFilterable = (col: GridAiColumn): boolean => col.filterable !== false;
+export const isSortable = (col: GridAiColumn): boolean => col.sortable !== false;
+export const isGroupable = (col: GridAiColumn): boolean => col.groupable !== false;
+export const isHideable = (col: GridAiColumn): boolean => col.hideable !== false;
+
+/**
+ * Aggregation functions for a column, as the Summaries panel offers them: every built-in function
+ * for number columns (or `aggregable: true`), `count` for the others, never with `aggregable: false`,
+ * and limited by `availableAggregationFunctions`.
+ */
+export function aggregationFnsOf(col: GridAiColumn, fns: readonly string[] = AGGREGATION_FNS): string[] {
+  if (col.aggregable === false) return [];
+  const base = col.type === 'number' || col.aggregable === true ? fns : fns.filter((fn) => fn === 'count');
+  const allowed = col.availableAggregationFunctions;
+  return Array.isArray(allowed) ? base.filter((fn) => allowed.includes(fn)) : [...base];
+}
+
+/** JSON-safe option values of a singleSelect column, in order, without duplicates. */
+export function optionValues(col: GridAiColumn): (string | number)[] {
+  const out: (string | number)[] = [];
+  if (!Array.isArray(col.valueOptions)) return out;
+  for (const option of col.valueOptions) {
+    const value: unknown = option !== null && typeof option === 'object' ? option.value : option;
+    if ((typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value))) && !out.includes(value)) out.push(value);
+  }
+  return out;
+}