@opencorestack/opengridx 3.4.0 → 3.5.0

package/docs/features/fill-handle.md

@@ -0,0 +1,125 @@
+# Fill Handle
+
+With [`cellSelection`](cell-selection.md) on, the selected range has a small square on its bottom-right corner: the **fill handle** (v3.5). Drag it down, up, right or left to fill the next cells from the range, as in Excel. **Ctrl/Cmd+D** and **Ctrl/Cmd+R** fill from the keyboard. Every fill is written like a paste, through `valueSetter` and `processRowUpdate`, and is one [undo](undo-redo.md) step. Demo: **Fill Handle** (`/fill-handle`).
+
+```tsx
+import { DataGrid, type GridFillResult } from '@opencorestack/opengridx';
+
+<DataGrid
+  rows={rows}
+  columns={columns}             // fills only write editable columns
+  cellSelection                 // the fill handle comes with range selection
+  undoRedo                      // optional: one fill = one undo step
+  onFill={(result: GridFillResult) => console.log(result.direction, result.updated, result.skipped)}
+  processRowUpdate={saveRow}    // called once per filled row
+/>
+```
+
+## Dragging the handle
+
+- The handle sits on the bottom-right cell of the range, or on the only selected cell. It is shown while at least one column is `editable` and no editor is open.
+- Drag it beyond the range. The range grows in **one direction**: the side of the range the cell under the pointer lies beyond. When that cell lies beyond both a row edge and a column edge (a diagonal drag), the larger pointer movement wins.
+- Past the edge of the grid the body auto-scrolls, as in a range drag, also over rows and columns that are not rendered yet.
+- Release to fill. Releasing over the original range, pressing Escape or losing the pointer writes nothing and restores the range.
+- Hold **Alt** while releasing to **copy** instead of continuing a series (Excel uses Ctrl for this, which the grid keeps for range shortcuts).
+- The handle has a 24 px hit area and `touch-action: none`, so a touch drag on it fills instead of scrolling the grid.
+
+After the fill, the range covers the source and the filled cells.
+
+## What is written
+
+Each line along the fill (each column for a fill down or up, each row for a fill right or left) is filled from its source cells, read towards the new cells:
+
+| Source cells of the line | Fill |
+| :--- | :--- |
+| One cell | Copies the value |
+| Two or more numbers with an exactly equal step | Continues the series: 2, 4, 6 → 8, 10. Decimals are rounded to the source's decimal places, so 0.1, 0.2 → 0.3, not 0.30000000000000004 |
+| Two or more dates on the same day of the month, an equal number of months apart | Continues by months: 15 Jan, 15 Feb → 15 Mar. The day is clamped to the month's end (31 Jan, 31 Mar → 31 May; 31 Dec, 31 Jan → 28 Feb) |
+| Two or more dates at the same time of day, an equal number of days apart | Continues by days: Mon 5 Oct, Tue 6 Oct → Wed 7 Oct (calendar days, so a daylight-saving change does not break it) |
+| Anything else (text, booleans, unequal steps, mixed types, empty cells) | Repeats the source pattern: A, B → A, B, A |
+
+Filling up or left reads the source in that direction: 7, 9 filled up gives 5, 3.
+
+Values are typed already, so `valueParser` is not involved: a number copied into a text column stays a number. Synthetic rows (group headers, subtotals, tree auto-parents) in the source are left out of the series.
+
+### `GridColDef.fillValue`
+
+A column can decide what a fill writes into its cells:
+
+```ts
+{
+  field: 'amount', type: 'number', editable: true,
+  // params.value is what the grid would write; return it to keep it.
+  fillValue: ({ value, sourceValues, index, direction, copy, row, id }) =>
+    typeof value === 'number' ? Math.max(0, Math.round(value)) : value,
+}
+```
+
+| Param | Description |
+| :--- | :--- |
+| `value` | The grid's choice: the next value of the series, the repeated pattern or the copy |
+| `sourceValues` | The line's source values in fill order (the value next to the first filled cell is last) |
+| `index` | Position of the cell among the filled cells of its line, from 0 |
+| `direction` | `'down'`, `'up'`, `'right'` or `'left'` |
+| `copy` | `true` when Alt was held or the fill came from Ctrl/Cmd+D or Ctrl/Cmd+R |
+| `row`, `id`, `field`, `colDef` | The cell being filled |
+
+A `fillValue` that throws skips that cell with reason `'invalidValue'` (and warns once in development).
+
+## Keyboard
+
+While focus is on a cell of the grid and no editor is open:
+
+| Key | Action |
+| :--- | :--- |
+| **Ctrl+D** (Cmd+D) | Copies the range's top row into the rows below it |
+| **Ctrl+R** (Cmd+R) | Copies the range's left column into the columns right of it |
+
+The grid takes these keys (`preventDefault`, so no bookmark dialog or page reload) whenever a range or focused cell exists, `cellSelection` is on and `disableFillHandle` is not set. A range of one row (Ctrl+D) or one column (Ctrl+R) has nothing to fill. Inside an editor or a text field you render in a cell, the keys keep their native meaning.
+
+## How it writes
+
+A fill is a batch edit, the same path as [paste](clipboard.md):
+
+- `valueSetter` (when the column has one) builds each row, and `processRowUpdate` runs **once per row**; rows run in parallel, and a row that throws or rejects is reported to `onProcessRowUpdateError` without stopping the others.
+- All rows that succeeded are stored in one update.
+- With `undoRedo`, the whole fill is **one undo step**.
+- Cells that cannot be written are skipped with a reason:
+
+| Reason | Cell |
+| :--- | :--- |
+| `'notEditable'` | The column is not `editable`, `isCellEditable` returned false, the row is synthetic, or a span covers the cell |
+| `'invalidValue'` | The column's `fillValue` threw |
+
+`onFill` receives the result plus the direction:
+
+```ts
+interface GridFillResult extends GridBatchEditResult {
+  direction: 'down' | 'up' | 'right' | 'left';
+}
+// { updated: [3, 4, 5], failed: [], skipped: [{ id: 3, field: 'owner', reason: 'notEditable' }], direction: 'down' }
+```
+
+## Opting out
+
+`disableFillHandle` hides the handle and leaves Ctrl/Cmd+D and Ctrl/Cmd+R to the browser. A grid without `cellSelection` has no fill handle.
+
+## Styling
+
+| Hook | Description |
+| :--- | :--- |
+| `.ogx__cell-fill-handle` | The handle: a 24 × 24 px hit area in the corner of the cell (`cursor: crosshair`, `touch-action: none`). The visible square is its `::after` |
+| `--ogx-fill-handle-color` | The square's colour. Defaults to the range border (`--ogx-range-border`); theme key `grid.fillHandleColor` |
+
+```css
+.my-grid { --ogx-fill-handle-color: #16a34a; }
+.my-grid .ogx__cell-fill-handle::after { width: 9px; height: 9px; }
+```
+
+## API
+
+| Member | Description |
+| :--- | :--- |
+| `disableFillHandle?: boolean` | Hides the handle and turns off Ctrl/Cmd+D and Ctrl/Cmd+R. Default `false` |
+| `onFill?(result: GridFillResult)` | Fired after every fill |
+| `GridColDef.fillValue?(params: GridFillValueParams): unknown` | Decides the value written into a cell of the column |

package/docs/features/filtering.md

@@ -7,6 +7,7 @@ OpenGridX provides a robust filtering system with support for both client-side a
 - **Column Filters**: Specific operators for different data types (string, number, date, etc.).
 - **Multi-Filter Groups**: Support for `AND`/`OR` logic operators.
 - **Server-Side Filtering**: Offload complex queries to your backend.
+- **Header Filters** (v3.5): a filter row under the column headers (`headerFilters`) that edits the same model. See [Header Filters](header-filters.md).
 
 ---
 
@@ -121,3 +122,5 @@ The filter panel is accessible through the built-in `GridToolbar`. To use your o
 ```
 
 The `FilterPanel` component is also exported from `@opencorestack/opengridx` if you need to embed it inside a custom layout. See [`<FilterPanel />`](../components/filter-panel.md) for how it edits the model.
+
+For a filter control on every column, set `headerFilters`: a row under the headers whose cells own the root items `id: 'header:<field>'` of the same `filterModel`, so the panel, the quick filter and the header row stay in sync. See [Header Filters](header-filters.md).

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

@@ -39,6 +39,9 @@ With [`cellSelection`](cell-selection.md) on (v3.3), on a data cell:
 | **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:
 
@@ -70,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:
@@ -95,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/roadmap.md

@@ -84,7 +84,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 | :--- | :--- | :--- | :--- |
 | **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** ✅ | 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** | 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.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/index.ts

@@ -1,12 +1,23 @@
-// @opencorestack/opengridx/ai: schema and validator for driving the grid from a language model.
-// No React, no dependencies and no AI SDK; the app sends the schema to its own model.
+// @opencorestack/opengridx/ai: schema, validator, prompt handler and agent tools for driving the grid
+// from a language model. No React, no dependencies and no AI SDK; the app calls its own model.
 export { getGridAiSchema } from './schema';
 export { validateGridAiState } from './validate';
+export { createGridAiPromptHandler } from './promptHandler';
+export { createGridAgentTools } from './agentTools';
 export type {
+  GridAgentApi,
+  GridAgentTool,
+  GridAgentToolResult,
+  GridAgentToolsOptions,
   GridAiColumn,
+  GridAiHistoryEntry,
   GridAiJsonSchema,
+  GridAiModelRequest,
   GridAiPart,
   GridAiPartOptions,
+  GridAiPromptContext,
+  GridAiPromptHandlerOptions,
+  GridAiPromptResult,
   GridAiSchema,
   GridAiSchemaOptions,
   GridAiState,
@@ -14,3 +25,9 @@ export type {
   GridAiValidationError,
   GridAiValidationResult,
 } from './types';
+export type {
+  GridAiAssistantOptions,
+  GridAiAssistantPanelProps,
+  GridAiAssistantStatus,
+  GridAiChip,
+} from '../types';