@opencorestack/opengridx 3.3.0 → 3.5.0

package/docs/features/ai-toolkit.md

@@ -0,0 +1,213 @@
+# AI Toolkit: Schema, Validator, Assistant & Agent Tools
+
+*Since v3.4.0 (schema and validator); v3.5.0 (assistant panel, prompt handler, agent tools)* · Demos: [AI: Grid Schema & Validator](https://opencorestack.github.io/OpenGridX/ai-schema), [AI Assistant](https://opencorestack.github.io/OpenGridX/ai-assistant)
+
+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 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.
+- **`createGridAiPromptHandler(...)`** (v3.5) connects those two to your model for the grid's [**Ask AI** panel](#ai-assistant-panel) (`aiAssistant` prop).
+- **`createGridAgentTools(apiRef, columns)`** (v3.5) gives [AI agents](#agent-tools) plain tools to read and change the grid.
+
+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 6.7 kB gzipped with the v3.5 additions; the budget is 8 kB). 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. The `aiAssistant` panel enforces this: it applies only a validated (branded) state, shows every change as a chip and offers Undo.
+- **Rows stay in the app unless you opt in.** The assistant sends the prompt, the schema, the current models and the session's earlier prompts, never rows. Of the agent tools, only `get_row_summary` reads rows, and it exists only with `allowRowAccess: true`.
+- **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`.
+
+## AI assistant panel
+
+*Since v3.5.0.* The `aiAssistant` prop adds an **Ask AI** panel: users type (or dictate) what they want to see, your model answers, and the grid applies the validated reply at once, as one step they can undo.
+
+```tsx
+import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
+import { createGridAiPromptHandler } from '@opencorestack/opengridx/ai';
+
+const onPrompt = createGridAiPromptHandler({
+  columns,
+  // Your endpoint calls your model with request.schema as the structured-output format.
+  callModel: async (request, { signal }) => {
+    const res = await fetch('/api/grid-ai', { method: 'POST', body: JSON.stringify(request), signal });
+    return res.json();
+  },
+});
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  slots={{ toolbar: GridToolbar }}
+  aiAssistant={{ onPrompt, suggestions: ['Top 10 by revenue', 'Group by region'] }}
+/>;
+```
+
+- **Opening it.** The built-in toolbar shows an **Ask AI** button (sparkle icon; label `localeText.aiAssistantButton`). Without the toolbar, call `apiRef.current.openAiAssistant()`. `slots.aiAssistantPanel` replaces the panel; it receives `GridAiAssistantPanelProps`.
+- **The panel.** A prompt input (Enter sends), the `suggestions` as chips, a microphone button where the browser has `SpeechRecognition` (hidden elsewhere; the microphone is asked for only on click; `voice: false` turns it off), **Stop** while a request runs (aborts `context.signal`), the reply's `message`, and the session's earlier prompts.
+- **Applying.** The reply is applied immediately as one undoable step. Each change shows as a removable chip: a filter item, the quick-filter words, a sort key, a grouping field, an aggregation, a column shown or hidden, the pivot. Removing a chip re-applies the reply without it (a part with no chip left returns to its value from before the reply). **Undo** restores the state from before the reply. This view-state undo is separate from the cell-edit undo history (`undoRedo`).
+- **What is applied.** Each part in `result.state` replaces the grid's model, except column visibility, which is merged over the current model (`{ tax: false }` hides one column and leaves the others). Parts outside `aiAssistant.parts` are ignored. A part the validator emptied (every entry dropped, such as a sort on an unknown field) is not applied, so it cannot clear the grid's model by accident. Changes go through the same handlers as the UI, so `onSortModelChange`, `onRowGroupingModelChange` and the rest fire; with a controlled model, update your state from them.
+- **What was dropped** is listed under the chips, such as `Ignored: Unknown field "revnue"`.
+- **Accessibility.** The panel is a `role="dialog"` labelled "Ask AI". Focus moves to the input when it opens and back to the toolbar button (or wherever it was) when it closes. Escape closes it. The status ("Thinking…", "Applied 3 changes", errors) is announced through the grid's live region.
+- **Events.** `onAiAssistantApply(result)` after a reply was applied; `onAiAssistantError(error)` when `onPrompt` rejects (Stop does not count) or its result was not validated.
+
+### The brand rule
+
+The grid applies a result only when its `state` carries the brand `Symbol.for('opengridx.ai.validated')`. `validateGridAiState` sets it (non-enumerable, on the result and on its `state`), and `createGridAiPromptHandler` returns such a result. An unbranded result is not applied: the panel shows "The reply was not validated" and a development warning says why. This makes "validate before applying" a rule the grid enforces rather than advice.
+
+Writing `onPrompt` yourself:
+
+```ts
+import { validateGridAiState } from '@opencorestack/opengridx/ai';
+
+const onPrompt = async (prompt, { currentState, history, signal }) => {
+  const reply = await myModel({ prompt, currentState, history, signal });
+  const result = validateGridAiState(reply.json, columns);
+  return { ...result, message: reply.text }; // spreading keeps the branded state
+};
+```
+
+A copied state (`{ ...result.state }`) or a hand-built one is not branded.
+
+### `createGridAiPromptHandler({ columns, callModel, parts?, schemaOptions? })`
+
+Returns the `onPrompt` function. It builds the schema once (from `columns`, limited to `parts` and `schemaOptions`), then for each prompt:
+
+1. calls `callModel({ prompt, schema, currentState, history }, { signal })`;
+2. reads the reply: a state object, a JSON string, or text with a fenced `json` block (the text around the block becomes `result.message`). An object's string `message` key is the message, not state. Plain text with no JSON becomes the message with nothing to apply;
+3. validates it with `validateGridAiState` (same `parts`) and returns the branded `{ state, errors, message? }`.
+
+A `callModel` throw or rejection becomes `{ state: {}, errors: [{ path: '', message: 'The model call failed: …' }] }`. An abort (Stop, a new prompt, closing the panel) rejects with an `AbortError`, even when `callModel` ignores the signal.
+
+## Agent tools
+
+*Since v3.5.0.* `createGridAgentTools(apiRef, columns, options?)` returns plain tool objects, `{ name, description, inputSchema, execute }`, for an AI agent to read and change the grid. They have no SDK dependency, so they work with the Vercel AI SDK, CopilotKit, OpenAI or Anthropic tool calling, and WebMCP (`navigator.modelContext.registerTool`).
+
+```ts
+import { createGridAgentTools } from '@opencorestack/opengridx/ai';
+
+const tools = createGridAgentTools(apiRef, columns);
+// Anthropic / OpenAI style: describe them to the model …
+const toolSpecs = tools.map(({ name, description, inputSchema }) => ({ name, description, input_schema: inputSchema }));
+// … and run the call the model asks for.
+const result = await tools.find((t) => t.name === call.name)?.execute(call.input);
+```
+
+| Tool | Input | Does |
+| :--- | :--- | :--- |
+| `get_grid_state` | `{}` | Returns `{ ok, state, columns }`: the current models (`apiRef.getGridAiState()`) and `{ field, headerName, type }` per column |
+| `set_filter` | `{ filterModel }` | Replaces the filter model |
+| `set_sort` | `{ sortModel }` | Replaces the sort model |
+| `set_grouping` | `{ rowGroupingModel }` | Replaces the row grouping |
+| `set_aggregation` | `{ aggregationModel }` | Replaces the summaries |
+| `set_column_visibility` | `{ columnVisibilityModel }` | Shows or hides the listed columns; the others keep their visibility |
+| `clear_filters` | `{}` | Removes every filter and the quick-filter words |
+| `get_row_summary` | `{ limit? }` | **Only with `allowRowAccess: true`.** Returns `{ ok, rowCount, rows }`: the number of rows that pass the filter and the first `maxRows` (default 20) of them, limited to `options.fields`, values read through `valueGetter` (JSON-safe: dates as ISO strings, objects as `null`) |
+
+- Each `set_*` tool's `inputSchema` is the part's schema from `getGridAiSchema`; a tool whose part no column allows is left out.
+- Inputs are checked with `validateGridAiState`. A call with any error applies **nothing** and returns `{ ok: false, errors }`, so the agent can correct it; a valid call returns `{ ok: true, applied }`.
+- `execute` never throws or rejects: a grid that is not mounted, a throwing change callback or any input gives `{ ok: false, errors }`.
+- The tools read `apiRef.current` only when they run, so they can be created before the grid mounts.
+
+## 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)

package/docs/features/cell-selection.md

@@ -115,6 +115,8 @@ function MyStats({ count, sum }: GridCellSelectionStatsSlotProps) {
 | `ogx--range-dragging` | On the grid root during a pointer drag (`user-select: none`). |
 | `--ogx-range-background` | Range tint. Theme key `grid.rangeBackground`. |
 | `--ogx-range-border` | Range outline. Theme key `grid.rangeBorder`. |
+| `ogx__cell-fill-handle` | The fill handle on the range's bottom-right cell (v3.5, see [Fill Handle](fill-handle.md)). |
+| `--ogx-fill-handle-color` | Fill handle colour; defaults to the range outline. Theme key `grid.fillHandleColor` (v3.5). |
 
 All five built-in themes define both variables. A custom `DataGridThemeProvider` theme derives them from `colors.primary` unless it sets them.
 
@@ -124,8 +126,12 @@ All five built-in themes define both variables. A custom `DataGridThemeProvider`
 - DOM focus stays on the anchor. The grid stays a single Tab stop.
 - After each change the polite live region announces the size, for example "12 cells selected, 3 rows by 4 columns", debounced to 300 ms. Translate it with `localeText.cellSelectionAnnouncement(cells, rows, columns)`.
 
+## Fill handle (v3.5)
+
+The range's bottom-right cell carries a fill handle: drag it to continue a series or repeat the range into the next cells, or press Ctrl/Cmd+D / Ctrl/Cmd+R. See [Fill Handle](fill-handle.md); `disableFillHandle` turns it off.
+
 ## Not in 3.3
 
-Paste, Delete-to-clear and undo (planned for 3.4), the fill handle, several ranges at once (Ctrl+drag), touch selection (on touch a drag scrolls) and ranges across pages.
+Paste, Delete-to-clear and undo (added in 3.4), the fill handle (added in 3.5), several ranges at once (Ctrl+drag), touch selection (on touch a drag scrolls; the fill handle accepts touch drags) and ranges across pages.
 
-See also: [Clipboard](clipboard.md), [Keyboard Navigation](keyboard-navigation.md), [Theming](../customization/theming.md).
+See also: [Fill Handle](fill-handle.md), [Clipboard](clipboard.md), [Undo & Redo](undo-redo.md), [Keyboard Navigation](keyboard-navigation.md), [Theming](../customization/theming.md).

package/docs/features/clipboard.md

@@ -101,3 +101,91 @@ ID	Name	Email	Status
 ```
 
 When pasted into Excel or Google Sheets, this content will automatically be distributed into the correct cells.
+
+---
+
+## 📥 Paste from Excel and Google Sheets (v3.4)
+
+With `cellSelection` on, **Ctrl/Cmd+V** pastes tab-separated text into the grid's **editable** cells. Each value is parsed for its column and saved like an edit: `valueSetter`, then `processRowUpdate` **once per row**, then the grid stores every row that succeeded in one update. Demo: **Paste from Excel** (`/clipboard-paste`).
+
+```tsx
+<DataGrid
+  rows={rows}
+  columns={columns}          // columns with editable: true
+  cellSelection
+  processRowUpdate={saveRow}
+  onClipboardPaste={({ updated, skipped, failed, text }) =>
+    toast(`${updated.length} rows updated, ${skipped.length} cells skipped`)}
+/>
+```
+
+- Paste works while focus is in the grid and no editor is open. In an open editor, Ctrl/Cmd+V is the input's own paste.
+- The grid reads the `paste` event (`text/plain`), so the browser asks for no clipboard permission.
+- `disableClipboardPaste` turns the shortcut off. `apiRef.current.pasteText(text, anchor?)` still works, for a toolbar "Paste" button that reads the clipboard itself.
+
+### Where values land
+
+| Clipboard | Selection | Result |
+| :--- | :--- | :--- |
+| One value | One cell | That cell |
+| One value | A range | Every cell of the range (Excel's "fill selection") |
+| A block | One cell | The block, from that cell to the right and down |
+| A block | A range | The block from the range's top-left cell; cells past the range, the last row or the last column are dropped |
+
+No rows are created. Only displayed rows are reached: rows on other pages and inside collapsed groups are not. After the paste the pasted area becomes the selection, and one Ctrl/Cmd+Z undoes all of it (with `undoRedo`).
+
+### How text is parsed
+
+The clipboard is read as Excel and Sheets write it: tabs between columns, `\r\n` or `\n` between rows, quoted fields that may hold tabs, line breaks and doubled quotes. A trailing empty line is ignored. Each cell is then parsed for its column:
+
+| Column type | Accepted | Otherwise |
+| :--- | :--- | :--- |
+| `string` (default), `image` | The text as is (an `image` column takes the URL) | — |
+| `number` | `1234.5`, `1,234.5`, `-12`, `(12)`, `12%` (→ 0.12), `1e3`; currency symbols and spaces stripped | skipped, `'invalidValue'` |
+| `date` | ISO `2026-10-07` (that local day), and what `Date.parse` accepts. The value keeps the kind the cell holds: a `Date`, a timestamp, or a `YYYY-MM-DD` string | skipped |
+| `boolean` | `true`/`false`, `yes`/`no` (the grid's `Yes`/`No` labels), `1`/`0`, any case | skipped |
+| `singleSelect` | An option value or an option label, any case; the option's value is stored | skipped |
+| An empty cell | `null` for number, date, boolean and singleSelect; `''` for string | — |
+
+`1,5` is not read as a number: in a decimal-comma locale use a `valueParser`.
+
+### `valueParser`
+
+`GridColDef.valueParser(text, { row, field, colDef })` replaces the parser for one column. Throw (or return `undefined`) to reject the text: the cell is skipped with reason `'invalidValue'`.
+
+```tsx
+{
+  field: 'price',
+  type: 'number',
+  editable: true,
+  // "1.234,5" → 1234.5
+  valueParser: (text) => {
+    const n = Number(text.replace(/[\s€]/g, '').split('.').join('').replace(',', '.'));
+    if (Number.isNaN(n)) throw new Error('not a number');
+    return n;
+  },
+}
+```
+
+### What is skipped
+
+`result.skipped` lists every cell that was not written, with a reason:
+
+| Reason | When |
+| :--- | :--- |
+| `'notEditable'` | The column is not `editable`, `isCellEditable` returned false, the row is a synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total), or the cell is covered by a span |
+| `'invalidValue'` | The text does not parse for the column type, or `valueParser` rejected it |
+
+A row whose `valueSetter` or `processRowUpdate` throws or rejects is listed in `result.failed` and reported to `onProcessRowUpdateError`, as for a single edit; the other rows are still saved. Cells that already hold the pasted value are left alone.
+
+### Events
+
+- `onClipboardPaste(result)` fires after every paste, once every row has settled: `{ updated, failed, skipped, text }`.
+- `onBeforeClipboardPaste({ text, anchor })` runs first. Return `false` to cancel the paste, or a string to paste instead (for example to strip a header line). A throw cancels the paste.
+- Above 10,000 cells a paste logs a development warning.
+
+---
+
+## 🧹 Clear a range with Delete (v3.4)
+
+With `cellSelection` on and a range of **more than one cell**, **Delete** or **Backspace** empties every editable cell of the range: `''` in string and image columns, `null` elsewhere. It is one batch edit through `valueSetter` and `processRowUpdate`, so one undo. Non-editable cells and synthetic rows are left alone. On a single cell nothing changes (Delete is not bound). `disableRangeClear` turns it off; `disableClipboardPaste` does not affect it.

package/docs/features/editing-reordering.md

@@ -115,6 +115,56 @@ const columns: GridColDef[] = [
 
 Enter and Escape keydowns that bubble out of a custom editor also commit and cancel. An error thrown by `renderEditCell` is contained to its cell (the cell shows `⚠`), like `renderCell`.
 
+### Building custom editors with `Input`
+The built-in text, number and date editors are the exported `Input` component with `variant="cell"` (since v3.3.1). Use it in `renderEditCell` and a custom editor looks like the built-in ones: it fills the cell, has no border, background or focus ring of its own (the editing cell's outline shows), and uses the cell's font.
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { Input } from '@opencorestack/opengridx';
+import type { GridColDef, GridRenderEditCellParams } from '@opencorestack/opengridx';
+
+const isAmount = (t: string) => t.trim() !== '' && Number(t) >= 0;
+
+function PriceEditor({ value, onValueChange, onCommit, onCancel }: GridRenderEditCellParams) {
+  const [text, setText] = useState(String(value ?? ''));
+  const ref = useRef<HTMLInputElement>(null);
+  useEffect(() => { ref.current?.focus(); ref.current?.select(); }, []);
+  const valid = isAmount(text);
+
+  return (
+    <Input
+      ref={ref}              // reaches the <input>, on React 18 and 19
+      variant="cell"
+      startAdornment="$"     // or endAdornment="kg"
+      error={!valid}         // red inner edge + aria-invalid
+      inputMode="decimal"
+      value={text}
+      onChange={e => {
+        setText(e.target.value);
+        if (isAmount(e.target.value)) onValueChange(Number(e.target.value));
+      }}
+      onKeyDown={e => {
+        if (e.key === 'Enter') { e.stopPropagation(); if (valid) onCommit(); }
+        if (e.key === 'Escape') { e.stopPropagation(); onCancel(); }
+      }}
+      onBlur={() => (valid ? onCommit() : onCancel())}
+    />
+  );
+}
+
+const columns: GridColDef[] = [
+  { field: 'price', type: 'number', editable: true, renderEditCell: params => <PriceEditor {...params} /> },
+];
+```
+
+- `ref` reaches the `<input>` (focus it and select its text when the editor opens, as the built-in editors do).
+- `inputClassName` adds classes to the `<input>`; `className` goes to the `.ogx-input-wrapper` div around it.
+- `error` adds `ogx-input-wrapper--error` (an inset `--ogx-color-error` edge in the cell variant, drawn over the cell outline) and `aria-invalid="true"`.
+- Stop propagation of the Enter / Escape you handle yourself, or the grid also commits / cancels when they bubble out.
+- The grid's boolean editor is the exported `Checkbox`; its `<input>` is visually hidden and `ref` / `inputClassName` reach it.
+
+Live example: the *Custom Cell Editors* demo page (`/custom-editors`).
+
 ### Computed columns (`valueGetter` + `valueSetter`)
 An editable column with a `valueGetter` edits the derived value. Give it a `valueSetter` so the commit can write the value back to the fields it comes from; otherwise the commit writes `row[field]`, which the `valueGetter` ignores, and a development warning is logged.
 

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).