@opencorestack/opengridx 3.3.0 → 3.5.0

package/lib/utils/headerFilters.ts

@@ -0,0 +1,189 @@
+import type { GridColDef, GridFilterGroup, GridFilterItem, GridFilterModel, GridFilterOperator } from '../types';
+import { NO_VALUE_OPERATORS, getOperatorsForType, isEmptyFilterValue } from './filtering';
+import { isSystemField } from './focus';
+
+/** Prefix of the ids of the filter items the header filter row owns: `header:<field>`. */
+export const HEADER_FILTER_ID_PREFIX = 'header:';
+
+/** Default height of the header filter row, in pixels. */
+export const DEFAULT_HEADER_FILTER_HEIGHT = 40;
+
+/** Debounce for typed values, the same as the filter panel's. */
+export const HEADER_FILTER_DEBOUNCE_MS = 300;
+
+/** The synthetic row-grouping column; it has no header filter. */
+const GROUPING_FIELD = '__group__';
+
+type FilterEntry = GridFilterItem | GridFilterGroup;
+
+const NO_ENTRIES: FilterEntry[] = [];
+
+export function getHeaderFilterItemId(field: string): string {
+    return `${HEADER_FILTER_ID_PREFIX}${field}`;
+}
+
+function isFilterGroup(entry: FilterEntry): entry is GridFilterGroup {
+    return 'items' in entry && Array.isArray(entry.items);
+}
+
+/** Whether a column gets a control in the header filter row. */
+export function hasHeaderFilter(col: Pick<GridColDef, 'field' | 'type' | 'filterable' | 'headerFilter' | 'isSpacer'>): boolean {
+    if (col.isSpacer || isSystemField(col.field) || col.field === GROUPING_FIELD) return false;
+    return col.headerFilter !== false && col.filterable !== false && col.type !== 'image';
+}
+
+/** The operator a new header filter starts with: `headerFilterOperator`, else the default for the type. */
+export function getHeaderFilterDefaultOperator(col: Pick<GridColDef, 'type' | 'headerFilterOperator'>): GridFilterOperator {
+    if (col.headerFilterOperator) return col.headerFilterOperator;
+    switch (col.type) {
+        case 'number': return '=';
+        case 'date':
+        case 'boolean':
+        case 'singleSelect':
+            return 'is';
+        default:
+            return 'contains';
+    }
+}
+
+/** The operators the operator menu offers: the type's operators, with the starting one first if the type does not list it. */
+export function getHeaderFilterOperators(col: Pick<GridColDef, 'type' | 'headerFilterOperator'>): GridFilterOperator[] {
+    const operators = getOperatorsForType(col.type);
+    const start = getHeaderFilterDefaultOperator(col);
+    return operators.includes(start) ? operators : [start, ...operators];
+}
+
+/**
+ * What a header filter cell shows:
+ * - `editable`: the cell owns `item` (the root-level item `header:<field>`), or there is none yet;
+ * - `custom`: the model holds a condition on the field the row cannot show (root `logicOperator`
+ *   `'or'`, another root item on the field, the field inside a nested group). The cell is read-only.
+ */
+export type GridHeaderFilterState =
+    | { kind: 'editable'; item: GridFilterItem | undefined }
+    | { kind: 'custom' };
+
+function groupMentionsField(group: GridFilterGroup, field: string): boolean {
+    return group.items.some(entry => (isFilterGroup(entry) ? groupMentionsField(entry, field) : entry.field === field));
+}
+
+/** Whether a model's root combines its items with OR (with something to combine). */
+export function isOrRootModel(model: GridFilterModel | null | undefined): boolean {
+    return (model?.logicOperator ?? 'and') === 'or' && (model?.items?.length ?? 0) > 0;
+}
+
+export function getHeaderFilterState(model: GridFilterModel | null | undefined, field: string): GridHeaderFilterState {
+    const items = model?.items ?? NO_ENTRIES;
+    if (isOrRootModel(model)) return { kind: 'custom' };
+    const ownId = getHeaderFilterItemId(field);
+    let own: GridFilterItem | undefined;
+    for (const entry of items) {
+        if (isFilterGroup(entry)) {
+            if (groupMentionsField(entry, field)) return { kind: 'custom' };
+            continue;
+        }
+        if (entry.field !== field) continue;
+        if (entry.id !== ownId || own) return { kind: 'custom' };
+        own = entry;
+    }
+    return { kind: 'editable', item: own };
+}
+
+/**
+ * The model with the header filter item for `field` replaced by `item` (added at the end when
+ * absent, removed when `item` is null). Every other entry, the logic operator and the quick filter
+ * pass through untouched. Returns `model` itself when the cell cannot own the field's filter.
+ */
+export function setHeaderFilterItem(model: GridFilterModel | null | undefined, field: string, item: GridFilterItem | null): GridFilterModel {
+    const base: GridFilterModel = model ?? { items: [] };
+    if (getHeaderFilterState(base, field).kind !== 'editable') return base;
+    const ownId = getHeaderFilterItemId(field);
+    const items = base.items ?? NO_ENTRIES;
+    const index = items.findIndex(entry => !isFilterGroup(entry) && entry.id === ownId);
+    const nextItem: GridFilterItem | null = item ? { ...item, id: ownId, field } : null;
+    let next: FilterEntry[];
+    if (index === -1) {
+        if (!nextItem) return base;
+        // With no items the logic operator means nothing yet; a leftover 'or' would make the
+        // next column's cell read the model as custom, so it starts as 'and'.
+        if (items.length === 0 && base.logicOperator === 'or') return { ...base, logicOperator: 'and', items: [nextItem] };
+        next = [...items, nextItem];
+    } else if (nextItem) {
+        next = items.map((entry, i) => (i === index ? nextItem : entry));
+    } else {
+        next = items.filter((_, i) => i !== index);
+    }
+    return { ...base, items: next };
+}
+
+/**
+ * The item a header filter cell stores for an operator and value, or null when it should hold no
+ * item: an empty value with the starting operator. An empty value with another operator keeps the
+ * item, so the chosen operator stays while the value is retyped (an empty value never filters).
+ */
+export function buildHeaderFilterItem(
+    col: Pick<GridColDef, 'field' | 'type' | 'headerFilterOperator'>,
+    operator: GridFilterOperator,
+    value: unknown,
+): GridFilterItem | null {
+    const noValue = NO_VALUE_OPERATORS.has(operator);
+    if (!noValue && isEmptyFilterValue(value) && operator === getHeaderFilterDefaultOperator(col)) return null;
+    return { id: getHeaderFilterItemId(col.field), field: col.field, operator, value: noValue ? undefined : value };
+}
+
+/** Carries a value over to a newly picked operator: lists for isAnyOf, scalars for the rest. */
+export function convertHeaderFilterValue(value: unknown, operator: GridFilterOperator): unknown {
+    if (NO_VALUE_OPERATORS.has(operator)) return undefined;
+    if (operator === 'isAnyOf') {
+        if (value == null || value === '') return [];
+        return Array.isArray(value) ? value : [value];
+    }
+    if (Array.isArray(value)) return value.length > 0 ? value[0] : '';
+    return value ?? '';
+}
+
+/** Short label shown on the operator button. */
+export const HEADER_FILTER_OPERATOR_SYMBOLS: Record<GridFilterOperator, string> = {
+    contains: '∋',
+    equals: '=',
+    startsWith: 'a…',
+    endsWith: '…a',
+    isEmpty: '∅',
+    isNotEmpty: '!∅',
+    isAnyOf: '∈',
+    '=': '=',
+    '!=': '≠',
+    '>': '>',
+    '>=': '≥',
+    '<': '<',
+    '<=': '≤',
+    is: '=',
+    not: '≠',
+    after: '>',
+    onOrAfter: '≥',
+    before: '<',
+    onOrBefore: '≤',
+};
+
+/** Readable operator names for the operator menu and labels. */
+export const HEADER_FILTER_OPERATOR_LABELS: Record<GridFilterOperator, string> = {
+    contains: 'Contains',
+    equals: 'Equals',
+    startsWith: 'Starts with',
+    endsWith: 'Ends with',
+    isEmpty: 'Is empty',
+    isNotEmpty: 'Is not empty',
+    isAnyOf: 'Is any of',
+    '=': 'Equals',
+    '!=': 'Does not equal',
+    '>': 'Greater than',
+    '>=': 'Greater than or equal',
+    '<': 'Less than',
+    '<=': 'Less than or equal',
+    is: 'Is',
+    not: 'Is not',
+    after: 'After',
+    onOrAfter: 'On or after',
+    before: 'Before',
+    onOrBefore: 'On or before',
+};

package/lib/utils/parsing.ts

@@ -0,0 +1,252 @@
+import type { GridColDef, GridValidRowModel } from '../types';
+import { toDate } from './values';
+
+/**
+ * Text → typed values: the TSV reader clipboard paste uses, and the per-column-type parsers paste,
+ * `GridColDef.valueParser` defaults and the `/ai` validator share. Pure and React-free.
+ *
+ * Every pattern here is linear (CodeQL scans every push): no adjacent quantifiers that can match the
+ * same characters.
+ */
+
+/** A parsed value, or `{ ok: false }` when the text does not fit the column type. */
+export type GridParsedValue = { ok: true; value: unknown } | { ok: false };
+
+const INVALID: GridParsedValue = { ok: false };
+const valid = (value: unknown): GridParsedValue => ({ ok: true, value });
+
+/**
+ * Splits tab-separated text the way Excel, Google Sheets and LibreOffice write it: tabs between
+ * columns, `\r\n`, `\n` or `\r` between rows. A field that starts with a double quote is quoted: it
+ * may hold tabs, line breaks and doubled quotes (`""` → `"`), the reverse of `escapeTsvField`. A
+ * quote inside an unquoted field is kept as is. A trailing empty line is ignored, so `"a\tb\n"` is one
+ * row. Empty text gives no rows.
+ */
+export function parseTsv(text: string): string[][] {
+    const rows: string[][] = [];
+    if (text === '') return rows;
+    let row: string[] = [];
+    let field = '';
+    let i = 0;
+    const n = text.length;
+    let fieldStart = true;
+    while (i < n) {
+        const ch = text[i];
+        if (fieldStart && ch === '"') {
+            // A quoted field: read to the closing quote, `""` being one quote.
+            let j = i + 1;
+            let value = '';
+            let closed = false;
+            while (j < n) {
+                const q = text[j];
+                if (q === '"') {
+                    if (text[j + 1] === '"') {
+                        value += '"';
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    j += 1;
+                    break;
+                }
+                value += q;
+                j += 1;
+            }
+            if (!closed) {
+                // No closing quote: not a quoted field after all, read the quote as text.
+                field += ch;
+                i += 1;
+                fieldStart = false;
+                continue;
+            }
+            field += value;
+            i = j;
+            fieldStart = false;
+            continue;
+        }
+        fieldStart = false;
+        if (ch === '\t') {
+            row.push(field);
+            field = '';
+            fieldStart = true;
+            i += 1;
+        } else if (ch === '\n' || ch === '\r') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            fieldStart = true;
+            i += ch === '\r' && text[i + 1] === '\n' ? 2 : 1;
+        } else {
+            field += ch;
+            i += 1;
+        }
+    }
+    // The last line, unless the text ended with a line break (Excel always adds one).
+    if (!fieldStart || row.length > 0 || field !== '') {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+
+const PLAIN_NUMBER = /^\d+(?:\.\d*)?(?:e[+-]?\d+)?$/i;
+const LEADING_DOT_NUMBER = /^\.\d+(?:e[+-]?\d+)?$/i;
+const GROUPED_NUMBER = /^\d{1,3}(?:,\d{3})+(?:\.\d*)?$/;
+// Currency symbols (Unicode Sc) and every kind of space, including the no-break spaces Excel uses
+// as a thousands separator.
+const STRIPPED_CHARS = /[\p{Sc}\s]/gu;
+
+/**
+ * A number as spreadsheets copy it: `1234.5`, `1,234.5` (comma thousands groups only), `-12`,
+ * `(12)` (accounting negative), `12%` (→ 0.12), `1e3`, with currency symbols and spaces stripped.
+ * Empty text is `null`. `1,5` is not accepted (it is ambiguous): use a `valueParser` for
+ * decimal-comma locales.
+ */
+export function parseNumberText(text: string): GridParsedValue {
+    let s = text.replace(STRIPPED_CHARS, '');
+    if (s === '') return text.trim() === '' ? valid(null) : INVALID;
+    let negative = false;
+    if (s.startsWith('(') && s.endsWith(')')) {
+        negative = true;
+        s = s.slice(1, -1);
+    }
+    if (s.startsWith('-') || s.startsWith('+') || s.startsWith('−')) {
+        if (s[0] !== '+') negative = !negative;
+        s = s.slice(1);
+    }
+    let percent = false;
+    if (s.endsWith('%')) {
+        percent = true;
+        s = s.slice(0, -1);
+    }
+    if (GROUPED_NUMBER.test(s)) s = s.split(',').join('');
+    else if (!PLAIN_NUMBER.test(s) && !LEADING_DOT_NUMBER.test(s)) return INVALID;
+    let value = Number(s);
+    if (!Number.isFinite(value)) return INVALID;
+    if (percent) value /= 100;
+    if (negative) value = -value;
+    return valid(value);
+}
+
+const ISO_DATE_PREFIX = /^(\d{4}-\d{2}-\d{2})/;
+const pad2 = (n: number) => String(n).padStart(2, '0');
+const localDay = (date: Date) => `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+
+/**
+ * A date: ISO `2026-10-07` (read as that local calendar day) or anything `Date.parse` accepts. Empty
+ * text is `null`. The result takes the kind of `current` (the value the cell holds now), as the date
+ * editor does: a timestamp stays a timestamp, a date string stays a `YYYY-MM-DD` string (an ISO
+ * date-time string keeps its time part); otherwise it is a `Date`.
+ */
+export function parseDateText(text: string, current?: unknown): GridParsedValue {
+    const trimmed = text.trim();
+    if (trimmed === '') return valid(null);
+    const date = toDate(trimmed);
+    if (!date) return INVALID;
+    if (typeof current === 'number') return valid(date.getTime());
+    if (typeof current === 'string') {
+        const day = localDay(date);
+        return valid(ISO_DATE_PREFIX.test(current) && current.length > 10 ? day + current.slice(10) : day);
+    }
+    return valid(date);
+}
+
+/** Text read as `true` / `false`, besides the grid's own `Yes` / `No` cell labels. Lower case. */
+const TRUE_WORDS = new Set(['true', 'yes', '1']);
+const FALSE_WORDS = new Set(['false', 'no', '0']);
+
+export interface GridBooleanLabels {
+    /** Text shown for `true` (the grid shows `Yes`). */
+    trueLabel?: string;
+    /** Text shown for `false` (the grid shows `No`). */
+    falseLabel?: string;
+}
+
+/**
+ * A boolean: `true`/`false`, `yes`/`no` (the grid's own `Yes` / `No` cell labels), `1`/`0` and any
+ * `labels` given, case-insensitive. Empty text is `null`.
+ */
+export function parseBooleanText(text: string, labels?: GridBooleanLabels): GridParsedValue {
+    const s = text.trim().toLowerCase();
+    if (s === '') return valid(null);
+    if (labels?.trueLabel !== undefined && s === labels.trueLabel.trim().toLowerCase()) return valid(true);
+    if (labels?.falseLabel !== undefined && s === labels.falseLabel.trim().toLowerCase()) return valid(false);
+    if (TRUE_WORDS.has(s)) return valid(true);
+    if (FALSE_WORDS.has(s)) return valid(false);
+    return INVALID;
+}
+
+type ValueOption = NonNullable<GridColDef['valueOptions']>[number];
+
+/**
+ * A `singleSelect` value: the option whose value or label matches the text, case-insensitive (values
+ * first). Returns the option's own value, so a numeric option stays a number. Empty text is `null`.
+ */
+export function parseSingleSelectText(text: string, options: readonly ValueOption[] | undefined): GridParsedValue {
+    const s = text.trim();
+    if (s === '') return valid(null);
+    if (!options || options.length === 0) return INVALID;
+    const lower = s.toLowerCase();
+    for (const option of options) {
+        const value = typeof option === 'object' ? option.value : option;
+        if (String(value).toLowerCase() === lower) return valid(value);
+    }
+    for (const option of options) {
+        if (typeof option === 'object' && option.label.toLowerCase() === lower) return valid(option.value);
+    }
+    return INVALID;
+}
+
+type ParserColumn = Pick<GridColDef, 'type' | 'valueOptions'>;
+
+export interface GridParseTextOptions {
+    /** The value the cell holds now: a parsed date takes its kind (see `parseDateText`). */
+    current?: unknown;
+    /** Extra boolean labels, besides `Yes` / `No`. */
+    booleanLabels?: GridBooleanLabels;
+}
+
+/**
+ * Parses cell text by the column `type`, without `valueParser`:
+ *
+ * | type | accepted |
+ * | :--- | :--- |
+ * | `string` (default), `image` | the text as is (an empty cell is `''`) |
+ * | `number` | `parseNumberText` |
+ * | `date` | `parseDateText` |
+ * | `boolean` | `parseBooleanText` |
+ * | `singleSelect` | `parseSingleSelectText` |
+ *
+ * An empty cell is `null` for every type but `string` / `image`.
+ */
+export function parseValueByType(text: string, colDef: ParserColumn | undefined, options?: GridParseTextOptions): GridParsedValue {
+    switch (colDef?.type) {
+        case 'number': return parseNumberText(text);
+        case 'date': return parseDateText(text, options?.current);
+        case 'boolean': return parseBooleanText(text, options?.booleanLabels);
+        case 'singleSelect': return parseSingleSelectText(text, colDef.valueOptions);
+        default: return valid(text);
+    }
+}
+
+/**
+ * Parses the text pasted into one cell: the column's `valueParser` when it has one (a throw, or a
+ * returned `undefined`, rejects the text), otherwise `parseValueByType`.
+ */
+export function parseCellText<R extends GridValidRowModel>(
+    text: string,
+    colDef: GridColDef<R>,
+    row: R,
+    options?: GridParseTextOptions,
+): GridParsedValue {
+    const { valueParser } = colDef;
+    if (!valueParser) return parseValueByType(text, colDef as unknown as ParserColumn, options);
+    let value: unknown;
+    try {
+        value = valueParser(text, { row, field: colDef.field, colDef });
+    } catch {
+        return INVALID;
+    }
+    return value === undefined ? INVALID : valid(value);
+}

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 3.3.0
+# Version: 3.5.0
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 
@@ -97,6 +97,14 @@ export default function App() {
 | cellSelectionModel         | GridCellSelectionModel        | Controlled range: readonly { anchor: { id, field }, head: { id, field } }[] (0 or 1 range). Corners are ids/fields: the range follows sorting; cleared ('dataChange') when a corner is no longer displayed |
 | onCellSelectionModelChange | (model, { reason }) => void   | reason: 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange' |
 | showCellSelectionStats     | boolean                       | Status bar: Count (non-empty), Sum and Average (numeric) of the range; slots.cellSelectionStats replaces it |
+| disableClipboardPaste      | boolean (3.4.0+)              | With cellSelection, Ctrl/Cmd+V pastes TSV (Excel/Sheets) into editable cells: one value fills a range; a block goes from the range's top-left (or focused) cell, cut to the range and grid edges; no rows created. Parsed per column type, then valueSetter + processRowUpdate once per row. true = shortcut off (apiRef.pasteText still works) |
+| onClipboardPaste           | (result) => void (3.4.0+)     | After every paste: { updated: id[], failed: {id, error}[], skipped: {id, field, reason: 'notEditable'/'invalidValue'}[], text } |
+| onBeforeClipboardPaste     | ({ text, anchor }) => boolean / string | Return false to cancel, a string to paste instead; a throw cancels |
+| disableRangeClear          | boolean (3.4.0+)              | With cellSelection, Delete/Backspace on a multi-cell range empties editable cells ('' strings, null otherwise) as one edit; true = off |
+| undoRedo                   | boolean / { limit } (3.4.0+)  | Undo/redo of edits, pastes, range clears (default off, 100 actions). Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y on a cell with no editor open. Recorded only after processRowUpdate succeeds; replayed through valueSetter + processRowUpdate; cells changed since are skipped ('changed', compared by value), removed rows ('missing') |
+| onHistoryChange            | ({ canUndo, canRedo, size }) => void | History change (size = undoable actions) |
+| disableFillHandle          | boolean (3.5.0+)              | With cellSelection, the range's bottom-right cell has a fill handle: drag down/up/right/left (one direction; auto-scroll; touch) fills the new cells from the range — numbers and dates with an exactly equal step continue (2,4 → 6,8; 15 Jan,15 Feb → 15 Mar; 5 Oct,6 Oct → 7 Oct), anything else repeats, one cell copies; Alt at release copies; Escape cancels. Ctrl/Cmd+D fills down from the range's top row, Ctrl/Cmd+R right from its left column. valueSetter + processRowUpdate once per row, one undo step, non-editable/synthetic cells skipped ('notEditable'). true = no handle, keys left to the browser |
+| onFill                     | (result) => void (3.5.0+)     | After every fill: { updated, failed, skipped, direction: 'down'/'up'/'right'/'left' } |
 
 ### Sorting
 | Prop              | Type                        | Description                     |
@@ -112,6 +120,8 @@ export default function App() {
 | filterModel         | GridFilterModel                | Controlled filter state (optional: the grid keeps its own filter model otherwise) |
 | onFilterModelChange | (model: GridFilterModel) => void | Filter change callback          |
 | filterMode          | 'client' / 'server'            | 'server': rows are shown unfiltered as given |
+| headerFilters       | boolean (default false)        | Filter row under the column headers (3.5.0+): Input for string/number/date, Any/Yes/No select for boolean, valueOptions select for singleSelect, operator menu, clear button; 300 ms debounce. Each cell owns the root filterModel item with id 'header:<field>'; root logicOperator 'or', the field inside a group or another root item on the field shows a read-only "Custom filter" (opens the GridToolbar filter panel). Not rendered in pivot mode |
+| headerFilterHeight  | number (default 40)            | Height of the header filter row (--ogx-header-filter-height) |
 
 ### Pagination
 | Prop                    | Type                                    | Description                      |
@@ -163,7 +173,8 @@ export default function App() {
 ### Grouping & Aggregation
 | Prop                   | Type                      | Description                              |
 |------------------------|---------------------------|------------------------------------------|
-| rowGroupingModel       | string[]                  | Fields to group by (one nesting level per field). Disables pagination. groupable:false fields are skipped |
+| rowGroupingModel       | string[]                  | Fields to group by (one nesting level per field). Disables pagination. groupable:false fields are skipped. Passing it controls grouping; without it the grid keeps its own model (3.5.0+: apiRef.setRowGroupingModel, AI assistant) |
+| onRowGroupingModelChange | (model: string[]) => void | Grouping changed through apiRef.setRowGroupingModel or the AI assistant (3.5.0+) |
 | aggregationModel       | GridAggregationModel      | {field: 'sum'/'avg'/'min'/'max'/'count'/'unique'} |
 | onAggregationModelChange | (model) => void        | Aggregation model changed (toolbar Summaries panel) |
 | groupingColDef         | Partial<GridColDef<R>>    | Adds a dedicated `__group__` column pinned left (rowGroupingModel or treeData); no `field` needed; never exported |
@@ -245,6 +256,8 @@ There are no getRowClassName / getCellClassName / theme props: use GridColDef.ce
 | renderEditCell    | (params: GridRenderEditCellParams<R>) => ReactNode     | Custom editor: call params.onValueChange(v), params.onCommit(), params.onCancel() |
 | valueGetter       | ({row, field, value}) => unknown                       | Computed value; used by sort, filter, quick search, aggregation, copy, export. Must be pure (quick filter caches per row object); a throw reads as undefined + dev warning |
 | valueSetter       | ({value, row, field}) => R                             | Write an edited value back onto the row (editable valueGetter columns) |
+| valueParser       | (text, { row, field, colDef }) => unknown              | Paste parser for this column (3.4.0+), e.g. "1.234,5" → 1234.5. Throw/undefined skips the cell ('invalidValue'). Default by type: number "1,234.5"/"12%"/"$5"; date ISO or Date.parse (keeps the cell's kind); boolean true/false/yes/no/1/0; singleSelect value or label; empty → null ('' for strings) |
+| fillValue         | ({ value, sourceValues, index, direction, copy, row, id, field, colDef }) => unknown | Fill handle (3.5.0+): what a fill writes into this column's cell. value = the grid's choice (series / pattern / copy); return it to keep it. Throw skips the cell ('invalidValue') |
 | valueFormatter    | ({value, row, field}) => string                        | Format display value (value is `unknown`: cast before calling methods) |
 | cellClassName     | string / (params) => string                            | CSS class on cells                         |
 | headerClassName   | string                                                 | CSS class on header cell                   |
@@ -256,6 +269,8 @@ There are no getRowClassName / getCellClassName / theme props: use GridColDef.ce
 | sortable          | boolean (default true)                                 | Enable sorting                             |
 | sortComparator    | (v1, v2, params1, params2) => number                   | Custom ascending comparator (3.1.0+). v1/v2 are valueGetter values incl. null/undefined; params { id, field, row, value }. Negated for desc; multi-sort tie-break chain; groups by grouping value; tree siblings; pivot row labels. Throw/NaN = 0. Ignored in server sortingMode |
 | filterable        | boolean (default true)                                 | Enable filtering and quick search          |
+| headerFilter      | boolean (default true)                                 | false: empty cell in the header filter row (3.5.0+) |
+| headerFilterOperator | GridFilterOperator                                  | Starting header filter operator (default: contains / = / is by type) (3.5.0+) |
 | resizable         | boolean (default true)                                 | Enable resize handle (mouse, touch, Alt+Arrow on header); double-click or Enter on the handle auto-sizes to content (3.1.0+) |
 | hideable          | boolean (default true)                                 | Allow hiding via toolbar / column menu     |
 | pinnable          | boolean (default true)                                 | Allow pinning via column menu (does not affect drag-reorder) |
@@ -265,6 +280,7 @@ There are no getRowClassName / getCellClassName / theme props: use GridColDef.ce
 | groupingValueFormatter | ({field, value}) => string                        | Group row label (default "field: value")   |
 | aggregable        | boolean                                                | false = no aggregation. Summaries panel offers number columns + aggregable: true |
 | availableAggregationFunctions | string[]                                   | Restrict aggregation functions for this column |
+| aiExamples        | unknown[]                                              | Example values put into getGridAiSchema's schema (3.4.0+). SENT TO THE MODEL: real data, opt-in. Primitives only, max 10. Unused by the grid |
 
 ---
 
@@ -298,6 +314,15 @@ apiRef.current.getSortModel()          // → GridSortItem[]
 apiRef.current.setFilterModel(model)
 apiRef.current.getFilterModel()        // → GridFilterModel
 
+// Model setters (3.5.0+): each fires its change callback, like the UI
+apiRef.current.setSortModel(model)
+apiRef.current.setRowGroupingModel(fields)
+apiRef.current.setAggregationModel(model)
+apiRef.current.setColumnVisibilityModel(model)
+apiRef.current.setPivotModel(model)
+apiRef.current.getGridAiState()        // → { filterModel, sortModel, rowGroupingModel, aggregationModel, pivotModel, columnVisibilityModel }
+apiRef.current.openAiAssistant()       // opens the aiAssistant panel (no-op without aiAssistant); closeAiAssistant()
+
 // Pagination
 apiRef.current.setPage(page)
 apiRef.current.setPageSize(size)
@@ -321,6 +346,14 @@ apiRef.current.getSelectedCells()      // → { id, field, value }[]; synthetic
 apiRef.current.copySelectedCells()     // → Promise<void>; TSV, no header line
 apiRef.current.clearCellSelection()
 
+// Paste and undo/redo (3.4.0+)
+apiRef.current.pasteText(text, anchor?) // → Promise<GridBatchEditResult>; anchor default: range top-left, else focused cell
+apiRef.current.undo()                   // → Promise<GridBatchEditResult> (undoRedo)
+apiRef.current.redo()
+apiRef.current.canUndo()                // → boolean
+apiRef.current.canRedo()
+apiRef.current.clearHistory()
+
 // Aggregation
 apiRef.current.getAggregationResult()  // → Record<string, unknown> | null (null in pivot mode)
 apiRef.current.getAggregationModel()   // → GridAggregationModel | null
@@ -356,6 +389,22 @@ const processRowUpdate = (newRow: Person) => {
 
 Double-click or Enter opens the editor; Enter / Tab / blur commits; Escape cancels. An edit whose row scrolls, pages or filters away is committed, not dropped.
 
+Custom editors (3.3.1+): build them on the exported `Input` with `variant="cell"` — it fills the cell with no border/background/focus ring, like the built-in editors. `ref` reaches the `<input>` (forwardRef, React 18 + 19), `inputClassName` styles the `<input>` (`className` the wrapper), `startAdornment` / `endAdornment` add a unit, `error` adds an inset error edge and `aria-invalid`. Stop propagation of the Enter/Escape you handle.
+
+```tsx
+import { Input } from '@opencorestack/opengridx';
+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 = text.trim() !== '' && Number(text) >= 0;
+  return <Input ref={ref} variant="cell" startAdornment="$" error={!valid} value={text}
+    onChange={e => { setText(e.target.value); const n = Number(e.target.value); if (e.target.value.trim() !== '' && n >= 0) onValueChange(n); }}
+    onKeyDown={e => { if (e.key === 'Enter') { e.stopPropagation(); if (valid) onCommit(); } if (e.key === 'Escape') { e.stopPropagation(); onCancel(); } }}
+    onBlur={() => (valid ? onCommit() : onCancel())} />;
+}
+```
+
 ---
 
 ## SERVER-SIDE DATA SOURCE
@@ -524,6 +573,48 @@ await printGrid(rows, columns, 'My Report Title');
 
 ---
 
+## AI TOOLKIT (@opencorestack/opengridx/ai, 3.4.0+)
+
+Separate entry point: no React, no dependencies, ~6.7 kB gzip with the 3.5.0 additions; never loaded by the core import. OpenGridX calls no AI service: the app sends { prompt, schema, currentState } to its own model (structured output) and validates the reply.
+
+```ts
+import { getGridAiSchema, validateGridAiState } from '@opencorestack/opengridx/ai';
+
+const schema = getGridAiSchema(columns, { include: ['filter', 'sort', 'grouping', 'aggregation'] });
+const reply = await fetch('/api/grid-assistant', { method: 'POST', body: JSON.stringify({ prompt, schema, currentState }) });
+const { state, errors } = validateGridAiState(await reply.text(), columns);
+if (state.filterModel) setFilterModel(state.filterModel);   // apply only the parts present
+if (state.sortModel) setSortModel(state.sortModel);
+```
+
+- getGridAiSchema(columns, { include?, exclude?, descriptions = true, examples = true }) → JSON Schema draft 2020-12 with `schemaVersion: 1`. Parts (option name → key): filter → filterModel (items as oneOf per field, AND/OR groups ≤ 3 levels, quickFilterValues), sort → sortModel, grouping → rowGroupingModel, aggregation → aggregationModel, pivot → pivotModel, columnVisibility → columnVisibilityModel. Fields from filterable / sortable / groupable / hideable / aggregable !== false; operators = the column type's filter operators; aggregation: number (or aggregable: true) columns get sum/avg/count/min/max/unique, others count, limited by availableAggregationFunctions; singleSelect valueOptions become enums. Fields starting with `__` are skipped. Deterministic; reads no rows.
+- validateGridAiState(json | jsonString, columns, { include?, exclude? }) → { state: GridAiState, errors: { path, message }[] }. Drops unknown parts, fields, disallowed fields, wrong operators, enum values outside the list; coerces values like clipboard paste ("1,200"/"$1,200" → 1200, "12%" → 0.12, yes/no/1/0 → boolean, dates → "YYYY-MM-DD", singleSelect by value or label, case-insensitive); removes empty groups; lists capped at 200 entries, errors at 100. Never throws; never reads `__proto__`.
+- Privacy: no row data by default; `aiExamples` and `valueOptions` ARE sent; always apply `state`, never the raw reply.
+- Types (from /ai): GridAiColumn, GridAiPart, GridAiSchema, GridAiSchemaOptions, GridAiState, GridAiValidateOptions, GridAiValidationError, GridAiValidationResult.
+
+### AI toolkit part 2 (3.5.0+): Ask AI panel and agent tools
+
+```tsx
+import { createGridAiPromptHandler, createGridAgentTools } from '@opencorestack/opengridx/ai';
+
+const onPrompt = createGridAiPromptHandler({
+  columns,
+  callModel: async (request, { signal }) => (await fetch('/api/grid-ai', { method: 'POST', body: JSON.stringify(request), signal })).json(),
+});
+<DataGrid columns={columns} rows={rows} slots={{ toolbar: GridToolbar }} aiAssistant={{ onPrompt, suggestions: ['Top 10 by revenue'] }} />
+
+const tools = createGridAgentTools(apiRef, columns);   // [{ name, description, inputSchema, execute }]
+```
+
+- `aiAssistant` prop: { onPrompt(prompt, { currentState, history, signal }) => Promise<{ state, errors, message? }>, placeholder?, suggestions?, voice? = true, parts? }. GridToolbar shows an "Ask AI" button (localeText.aiAssistantButton); apiRef.openAiAssistant() without a toolbar; slots.aiAssistantPanel replaces the panel (GridAiAssistantPanelProps). Events: onAiAssistantApply(result), onAiAssistantError(error).
+- BRAND RULE: the grid applies a result only if `result.state` carries Symbol.for('opengridx.ai.validated'), set (non-enumerable) by validateGridAiState on the result and its state. Unbranded → not applied, "The reply was not validated" + dev warning. `{ ...result, message }` keeps the brand; `{ ...result.state }` loses it.
+- Applying: immediately, one undoable step (Undo restores the models from before the reply; separate from the cell-edit undoRedo history). Each change is a removable chip; removing one re-applies the reply without it. Parts replace the grid's models, except columnVisibilityModel (merged). Parts outside `parts`, and parts the validator emptied (all entries dropped), are not applied. Voice: mic button only where SpeechRecognition / webkitSpeechRecognition exists; the microphone is requested only on click. Panel: role=dialog "Ask AI", Escape closes and returns focus, status in the grid's live region; Stop aborts `signal`.
+- createGridAiPromptHandler({ columns, callModel, parts?, schemaOptions? }): schema built once; callModel({ prompt, schema, currentState, history }, { signal }); reply = state object | JSON string | text with a ```json fence (surrounding text / a `message` key → result.message; plain text → message only); validated + branded. callModel throw → { state: {}, errors: [{ path: '', message }] }; abort → rejects AbortError.
+- createGridAgentTools(apiRef, columns, { allowRowAccess?, fields?, maxRows? = 20 }): get_grid_state, set_filter, set_sort, set_grouping, set_aggregation, set_column_visibility (merged), clear_filters, and get_row_summary ONLY with allowRowAccess: true (the one tool that sends rows). Inputs validated with validateGridAiState; any error → nothing applied, { ok: false, errors }. execute never throws. Works with the Vercel AI SDK, CopilotKit, OpenAI / Anthropic tool calling, WebMCP.
+- More types (from /ai): GridAiPromptContext, GridAiPromptResult, GridAiHistoryEntry, GridAiAssistantOptions, GridAiAssistantPanelProps, GridAiChip, GridAiModelRequest, GridAiPromptHandlerOptions, GridAgentTool, GridAgentToolResult, GridAgentToolsOptions, GridAgentApi. /ai is ~6.7 kB gzip (budget 8 kB).
+
+---
+
 ## CSS CUSTOMIZATION
 
 All CSS variables use the `--ogx-` prefix and are declared on `:root` by the stylesheet. Override them on a wrapper (or use DataGridThemeProvider, which sets the same variables):
@@ -545,8 +636,11 @@ Class names use the `ogx__` BEM prefix, e.g.:
 - `ogx__row`, `ogx__row--selected`, `ogx__row--even`, `ogx__row--odd`
 - `ogx__cell`, `ogx__cell--focused`, `ogx__cell--editing`
 - Cell ranges (3.3.0+): `ogx__cell--range`, `ogx__cell--range-top|bottom|left|right` (inset box-shadow outline), `ogx--range-dragging` on the root during a drag; variables `--ogx-range-background`, `--ogx-range-border` (theme keys `grid.rangeBackground`, `grid.rangeBorder`)
+- Fill handle (3.5.0+): `ogx__cell-fill-handle` (24px hit area in the corner cell, visible square is `::after`), variable `--ogx-fill-handle-color` (defaults to `--ogx-range-border`; theme key `grid.fillHandleColor`)
 - `ogx__header-cell`, `ogx__header-cell--sorted`, `ogx__header-cell--wrap` (wrapHeaderText, 3.3.0+)
+- Header filter row (3.5.0+): `ogx__header-filter-row`, `ogx__header-filter-cell` (`--focused`, `--active`, `--custom`, `--empty`, `--system`, `--pinned*`), `ogx__header-filter-operator`, `ogx__header-filter-menu`, `ogx__header-filter-input-wrapper` / `ogx__header-filter-input`, `ogx__header-filter-select`, `ogx__header-filter-clear`, `ogx__header-filter-custom`; height variable `--ogx-header-filter-height`
 - Sticky wrappers: `ogx__sticky-top` (header + top-pinned rows), `ogx__sticky-bottom` (bottom-pinned rows + aggregation footer)
+- Form controls (3.3.1+): the toolbar search, column-panel search, filter value box and text/number/date editors render through `Input`: the `<input>` keeps its class (`ogx-global-search__input`, `ogx-column-visibility-panel__search-input`, `ogx-filter__value-input`, `ogx__edit-input`) inside a `div.ogx-input-wrapper` (`ogx-input-wrapper--cell` for editors) — use descendant selectors (`.ogx-global-search input`), not `> input`. The boolean editor and list-view row checkbox are the shared `Checkbox` (`.ogx-checkbox__box`; hidden `<input>`)
 
 ---
 
@@ -606,7 +700,7 @@ interface GridGetRowsResponse<R = GridRowModel> {
 
 ## KEYBOARD
 
-Arrows move between cells (skipping hidden columns); Home/End, Ctrl+Home/End, PageUp/PageDown; Enter edits an editable cell, otherwise acts like a row click (toggles group/tree rows); Tab leaves the grid (while editing it moves to the next editable cell); Shift+Space selects the row (Space toggles the checkbox or detail panel when those cells are focused); Ctrl/Cmd+A selects all; Ctrl/Cmd+C copies the selection; Alt+ArrowRight/Left expands/collapses; Enter/Space on a header sorts (Shift adds to the sort); Alt+ArrowDown or Ctrl+Enter on a header opens the column menu; Alt+ArrowLeft/Right on a header resizes it.
+Arrows move between cells (skipping hidden columns); Home/End, Ctrl+Home/End, PageUp/PageDown; Enter edits an editable cell, otherwise acts like a row click (toggles group/tree rows); Tab leaves the grid (while editing it moves to the next editable cell); Shift+Space selects the row (Space toggles the checkbox or detail panel when those cells are focused); Ctrl/Cmd+A selects all; Ctrl/Cmd+C copies the selection; Alt+ArrowRight/Left expands/collapses; Enter/Space on a header sorts (Shift adds to the sort); Alt+ArrowDown or Ctrl+Enter on a header opens the column menu; Alt+ArrowLeft/Right on a header resizes it. With headerFilters (3.5.0+): ArrowDown on a header moves to its filter cell, ArrowDown again to the first row; Enter/Space or typing focuses the filter control, Escape returns to the cell, Alt+ArrowDown opens the operator menu, Delete clears the filter; controls are not Tab stops (Tab leaves the grid).
 
 ---