@opencorestack/opengridx 3.2.2 → 3.4.0

package/docs/features/cell-selection.md

@@ -0,0 +1,131 @@
+# Cell Range Selection
+
+*Since v3.3.0*
+
+Users select a rectangle of cells the way they do in Excel or Google Sheets, by dragging, Shift+clicking or pressing Shift+arrow keys, and copy it with Ctrl/Cmd+C. An optional status bar shows the count, sum and average of the selection.
+
+```tsx
+import { DataGrid } from '@opencorestack/opengridx';
+
+<DataGrid
+  rows={rows}
+  columns={columns}
+  cellSelection
+  showCellSelectionStats
+  height={500}
+/>
+```
+
+Everything is off unless `cellSelection` is set. Without it the grid behaves exactly as before.
+
+## Gestures
+
+| Input | Result |
+| :--- | :--- |
+| Click | Focus the cell. The range is that cell. A plain click still selects the row unless `disableRowSelectionOnClick` is set. |
+| Press and drag | Range from the pressed cell to the cell under the pointer. Holding the pointer near or past an edge of the body scrolls the grid, over virtualized rows and columns. |
+| Shift+click | Extend from the anchor (the active cell) to the clicked cell. |
+| Shift+Arrow | Move the far corner (head) by one cell. It does **not** wrap to the next row, though plain arrows still do. |
+| Shift+Home / Shift+End | Head to the first / last column of its row. |
+| Ctrl+Shift+Home / End (Cmd on macOS) | Head to the first / last cell of the page. |
+| Shift+PageUp / Shift+PageDown | Head one page up / down. |
+| Ctrl/Cmd+A | Select every data cell on the page. The header checkbox still selects all rows. |
+| Escape | Collapse the range to the anchor (when not editing). |
+| Ctrl/Cmd+C | Copy the range as TSV. |
+| Typing / Enter / F2 | Edit the anchor cell, as before. |
+
+Drag and Shift ranges never change the **row** selection, and the checkbox column keeps selecting rows.
+
+## The model
+
+```ts
+interface GridCellCoordinates { id: GridRowId; field: string }
+interface GridCellRange { anchor: GridCellCoordinates; head: GridCellCoordinates }
+type GridCellSelectionModel = readonly GridCellRange[];   // zero or one range in 3.3
+type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+```
+
+- `anchor` is the active cell. It keeps DOM focus and it is where an edit starts. `head` is the corner that moves, and the one that is scrolled into view. A single focused cell is a range whose `anchor` equals its `head`. It is not drawn as a range, but it is what Ctrl+C copies.
+- Corners are row **ids** and column **fields**, not indices. The rectangle is worked out from the current display order on every render, so after a sort or filter it follows the two corner rows (as Google Sheets does). If a corner's row or column is no longer displayed (filtered, on another page, removed or hidden), the range is cleared with `reason: 'dataChange'`.
+- Controlled or uncontrolled, like the other models:
+
+```tsx
+const [model, setModel] = useState<GridCellSelectionModel>([]);
+
+<DataGrid
+  cellSelection
+  cellSelectionModel={model}
+  onCellSelectionModelChange={(next, { reason }) => setModel(next)}
+/>
+```
+
+### Which cells take part
+
+- **Columns:** only data columns, in screen order: left-pinned, then centre, then right-pinned. The checkbox, detail-panel, reorder and grouping (`__group__`) columns never join a range, and clicking them works as before.
+- **Rows:** pinned top and bottom rows take part in screen order. Group headers, subtotals, tree auto-parents and the pivot Grand Total are highlighted when they fall inside the rectangle, but they are **skipped by copy** and by `getSelectedCells()`.
+- **Spans:** a range that touches part of a `colSpan` or `rowSpan` grows to cover the whole span, repeatedly until no span crosses its edge (as Excel does with merged cells). In a copy the span's value sits at its origin and the covered positions are empty.
+- **Pages:** a range covers the rows of the current page.
+
+## Copy
+
+With `cellSelection` on, Ctrl/Cmd+C copies the range (the focused cell when nothing else is selected):
+
+- values formatted the way the cells show them (`valueGetter`, then `valueFormatter`);
+- tabs between columns, line breaks between rows, **no header line**, and fields quoted where Excel needs it;
+- `exportable: false` columns are copied when they are in the range, because the user chose them on screen.
+
+Row copy stays available through `apiRef.current.copySelectedRows()`, which still includes the header line. `disableClipboardCopy` turns the shortcut off for both. Above 100,000 cells a development warning suggests `exportToCsv` instead. Nothing is truncated.
+
+## API
+
+| Method | Description |
+| :--- | :--- |
+| `getCellSelectionModel()` | The current model (`[]` when `cellSelection` is off). |
+| `setCellSelectionModel(model)` | Replace the model (only the first range is kept). Focus moves to its anchor. |
+| `selectCellRange(anchor, head)` | Select the rectangle between two cells. |
+| `clearCellSelection()` | Empty the selection (`reason: 'clear'`). |
+| `getSelectedCells()` | `{ id, field, value }[]` of the range in display order, values read through `valueGetter`. Synthetic rows and span-covered positions are left out. |
+| `copySelectedCells()` | Copy the range as TSV. Rejects when the clipboard write fails. |
+
+The methods do nothing while `cellSelection` is off.
+
+## Status bar
+
+`showCellSelectionStats` adds a strip under the grid (above the pagination area). While more than one cell is selected it shows:
+
+- **Count**: non-empty cells of data rows;
+- **Sum** and **Average**: of the numeric cells. Both are hidden when there are none.
+
+These use the shared aggregation functions. The strip keeps its height while one cell or none is selected, so the grid does not jump. Replace its content with `slots.cellSelectionStats`, which receives `GridCellSelectionStatsSlotProps` (`cellCount`, `rowCount`, `columnCount`, `count`, `numericCount`, `sum`, `average`, `apiRef`) plus `slotProps.cellSelectionStats`. The default component is exported as `CellSelectionStats`.
+
+```tsx
+function MyStats({ count, sum }: GridCellSelectionStatsSlotProps) {
+  return <span>{count} cells, total {sum ?? 0}</span>;
+}
+
+<DataGrid cellSelection showCellSelectionStats slots={{ cellSelectionStats: MyStats }} />
+```
+
+## Styling
+
+| Class / variable | Meaning |
+| :--- | :--- |
+| `ogx__cell--range` | Every cell in the range (tinted). |
+| `ogx__cell--range-top` / `-bottom` / `-left` / `-right` | Edge cells. The outline is an inset `box-shadow`, so nothing moves. |
+| `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`. |
+
+All five built-in themes define both variables. A custom `DataGridThemeProvider` theme derives them from `colors.primary` unless it sets them.
+
+## Accessibility
+
+- Cells in the range have `aria-selected="true"`, and the grid is `aria-multiselectable`.
+- 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)`.
+
+## 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.
+
+See also: [Clipboard](clipboard.md), [Keyboard Navigation](keyboard-navigation.md), [Theming](../customization/theming.md).

package/docs/features/clipboard.md

@@ -17,6 +17,8 @@ Selection and copying follow standard spreadsheet metaphors:
 | :--- | :--- |
 | `Ctrl + C` / `Cmd + C` | Copy currently selected rows to the clipboard. |
 
+> **Cell ranges (v3.3)**: with `cellSelection` on, Ctrl/Cmd+C copies the selected cell range instead (the focused cell at minimum), with no header line. `apiRef.current.copySelectedRows()` still copies rows. See [Cell Range Selection](cell-selection.md).
+
 > **Note**: The shortcut only copies while focus is inside the grid (a cell, a header, the toolbar), so with several grids on a page only the one in use copies, and Ctrl+C elsewhere on the page is never taken over (v3.0). It is also ignored while an input, textarea, or another editable element has focus, and while the page has a text selection, which the browser copies as usual. `apiRef.current.copySelectedRows()` is not affected by focus.
 >
 > The shortcut works with Caps Lock on and on non-Latin keyboard layouts (the key in the "C" position). Ctrl+Shift+C and Ctrl+Alt+C are not copy shortcuts and are left alone. Focus stays where it was after the copy.
@@ -99,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/keyboard-navigation.md

@@ -25,8 +25,31 @@ The grid follows the [WAI-ARIA data grid pattern](https://www.w3.org/WAI/ARIA/ap
 | **Alt+ArrowRight** / **Alt+ArrowLeft** | Tree data / row grouping: expand / collapse the focused row. |
 | **Shift+Space** | Select or deselect the focused row (when rows can be selected: `checkboxSelection`, or click selection not disabled). Synthetic group rows are not selectable. |
 | **Space** | On the row checkbox: toggle the row. On the detail-panel toggle: expand or collapse the panel. Elsewhere it does nothing (it never scrolls the grid). |
-| **Ctrl+A** (Cmd+A) | Select every row, when several rows can be selected. |
-| **Ctrl+C** (Cmd+C) | Copy the selected rows (see [Clipboard](clipboard.md)). |
+| **Ctrl+A** (Cmd+A) | Select every row, when several rows can be selected. With `cellSelection`: select every data cell of the page instead. |
+| **Ctrl+C** (Cmd+C) | Copy the selected rows (see [Clipboard](clipboard.md)). With `cellSelection`: copy the cell range, or the focused cell. |
+
+With [`cellSelection`](cell-selection.md) on (v3.3), on a data cell:
+
+| Key | Action |
+| :--- | :--- |
+| **Shift+Arrow keys** | Extend the cell range by one cell. Unlike plain arrows they do not wrap to the next row. Focus stays on the anchor. |
+| **Shift+Home** / **Shift+End** | Extend to the first / last column of the row. |
+| **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`. |
+
+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.
 
 Arrow, Home/End, PageUp/PageDown and Space are always consumed, so the viewport does not scroll natively when focus cannot move further.
 

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

@@ -70,18 +70,75 @@ This document tracks the current status of features in `OpenGridX` and outlines
 
 ---
 
-## 📅 Upcoming Features
+## 🗓️ Q4 2026 Roadmap (October – December)
 
-### Advanced Data Features
-*   **Interactive Pivot Builder**: Drag-and-drop UI for users to dynamically create pivot tables.
-*   **Advanced Charts Integration**: Inline sparklines and trend visualization.
+**Theme: free spreadsheet editing, with AI you control.** Range selection, paste, undo/redo and a fill handle are paid features in MUI X Premium and AG Grid Enterprise, and clipboard paste (476 👍) and cell range selection (317 👍) are among the most-requested grid features on GitHub. The research behind this plan compared ten competing grids and their AI features.
 
-### Demo Site
-*   **Full source viewer coverage**: Migrate all 32 examples to `DocsLayout` using Vite `?raw` auto-loading (eliminates string-literal source maintenance). See `docs/superpowers/plans/2026-07-29-demo-app-refactor.md`.
-*   **Syntax highlighting**: Prism.js token-based highlighting in the source viewer.
+**Team:** one maintainer plus an AI coding assistant. The plan is sized for that: one headline feature per release, and anything that slips moves to the next release instead of stretching the current one.
+
+**Compatibility:** everything ships in 3.x minor releases. Each new interaction is opt-in through a prop, so existing grids behave exactly as before until the feature is enabled.
+
+### Releases
+
+| 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** ✅ | 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) |
+| Freeze | 19 Dec – 5 Jan | Bug fixes only | — |
+
+### Across the quarter
+
+*   **Published benchmark**: reproducible 100k / 1M-row numbers (scroll frame rate, sort and filter time, memory) in `docs/performance.md`.
+*   **Next.js App Router guide**: using the grid from a `'use client'` component, with the stylesheet in `app/layout.tsx`.
+*   **RTL check**: verify right-to-left layouts and document the result.
+*   **Demo site**: source viewer on all examples (`DocsLayout` with Vite `?raw`) and syntax highlighting, done alongside each release's demo page.
+
+### Definition of done for each feature
+
+*   A short design note in `docs/superpowers/specs/` before coding starts (API, keyboard behaviour, ARIA).
+*   Unit tests, browser tests in Chromium, Firefox and WebKit, and a scenario in the package smoke suite.
+*   Keyboard-only and screen-reader pass: the grid stays a single Tab stop and announces selection changes.
+*   API reference, feature guide, demo page, CHANGELOG and `llms.txt` updated (the wiki follows automatically).
+*   Bundle budget: the core bundle grows only by the feature itself; the `/ai` entry point has no dependencies and adds nothing when it is not imported.
+
+### Rules for the AI toolkit
+
+*   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.
+*   The schema carries a `schemaVersion`, since apps will cache prompts against it.
+
+### Risks
+
+*   **Range selection touches focus and keyboard handling**, where most v3.0 fixes landed. It is opt-in and gets the longest test cycle; if it slips, 3.4.0 moves rather than shipping paste on an unstable base.
+*   **Undo must cover rejected updates**: a `processRowUpdate` that throws or a paste that partly fails must leave the history consistent.
+*   **Wrong AI filters** that look plausible: the validator, visible chips and undo are required, not optional.
+
+## 🔭 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.
+*   **Sparklines** and a charts adapter that passes grid state to any chart library.
+*   **AI toolkit, part 3**: smart paste (unstructured text → pending rows) and `apiRef.getAiContext()` for "summarise selection"; an `opengridx-mcp` docs server for coding assistants.
+*   **Tailwind / shadcn theme preset**, sticky header against page scroll.
+
+### Not planned
+
+*   **Spreadsheet formulas** (`=SUM(A1:A9)`): a formula engine is a product of its own; calculated columns cover most of the need.
+*   **AI on every cell**: the cost grows with each row and results are not reproducible.
+*   **Built-in semantic search or anomaly detection**: large models and app-specific logic; better built by the app on top of the grid.
+*   **Scaled scrolling past ~645,000 rows** and **list-view virtualization**: revisit if users ask.
 
 ## ✅ Implemented Features (Recent)
 
+### 3.x releases *(2026-09-29 → 2026-10-01)*
+- **3.0.0** correctness release (rows never modified, typed generics, React 18 support), **3.0.1** fill-height layout fix, **3.1.0** `sortComparator` and column auto-size, **3.2.0** non-blocking PDF export, **3.2.1** Safari boolean editor fix, **3.2.2** linear-time export regexes. Details in [CHANGELOG.md](../CHANGELOG.md); upgrade guide in [migration/v2-to-v3.md](migration/v2-to-v3.md).
+- Package smoke suite against the packed tarball in React 18 and 19 apps, pull-request CI, community files and a wiki generated from these docs.
+
 ### Consumer defect fixes *(v2.1.0, 2026-09-23)*
 - Row-grouping subtotals now use the shared aggregation functions (nulls ignored, `unique` supported, `availableAggregationFunctions` honoured); `min`/`max` no longer overflow the call stack on very large datasets.
 - Group and tree-data expansion state survives row updates, including server-side lazily loaded children.

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);
+  }
+}