@opencorestack/opengridx 3.3.0 → 3.5.0

package/lib/types/index.ts

@@ -154,6 +154,18 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
   sortable?: boolean;
   /** If false, filtering is disabled for this column. */
   filterable?: boolean;
+  /**
+   * Set to `false` to leave this column's cell in the header filter row (`headerFilters`) empty.
+   * Columns with `filterable: false` or `type: 'image'` have no header filter either.
+   * @since v3.5
+   */
+  headerFilter?: boolean;
+  /**
+   * The operator a new header filter (`headerFilters`) for this column starts with. Defaults by type:
+   * `contains` (string), `=` (number), `is` (date, boolean, singleSelect).
+   * @since v3.5
+   */
+  headerFilterOperator?: GridFilterOperator;
   /** If false, the user cannot manually resize this column. */
   resizable?: boolean;
   /** If false, the column cannot be hidden via the UI. */
@@ -178,6 +190,14 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @since v3.0
    */
   valueSetter?(params: GridValueSetterParams<R>): R;
+  /**
+   * Turns pasted text into this column's value (clipboard paste), instead of the default parser for
+   * the column `type` (see `docs/features/clipboard.md`). Use it for locales such as `1.234,5` or for
+   * custom codes. Throw (or return `undefined`) to reject the text: the cell is skipped with reason
+   * `'invalidValue'`. The value then goes through `valueSetter` and `processRowUpdate` like an edit.
+   * @since v3.4
+   */
+  valueParser?(text: string, params: GridValueParserParams<R>): unknown;
   /**
    * Custom ascending comparator for client-side sorting by this column, used instead of the built-in
    * type-aware comparison. `v1` / `v2` are the cell values (`valueGetter` applied) and **include
@@ -188,6 +208,13 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @since v3.1
    */
   sortComparator?(v1: unknown, v2: unknown, params1: GridSortCellParams<R>, params2: GridSortCellParams<R>): number;
+  /**
+   * Decides the value the fill handle (or Ctrl/Cmd+D, Ctrl/Cmd+R) writes into a cell of this column.
+   * `params.value` is what the grid would write (a continued series, the repeated pattern or a copy);
+   * return it to keep that, or any other value. A throw skips the cell with reason `'invalidValue'`.
+   * The value then goes through `valueSetter` and `processRowUpdate` like an edit. @since v3.5
+   */
+  fillValue?(params: GridFillValueParams<R>): unknown;
   /** Function to format a value into a human-readable string. */
   valueFormatter?(params: GridValueFormatterParams<R>): string;
   /** Custom component or element to render in the cell. */
@@ -240,6 +267,16 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @default true
    */
   exportable?: boolean;
+
+  /**
+   * Example values for this column, put into the schema from `getGridAiSchema`
+   * (`@opencorestack/opengridx/ai`) to help a language model write filters ("Acme" → `customer`).
+   * **These values are sent to the model.** The grid never reads row data for the schema; only what
+   * you list here leaves the app, so list nothing private. Strings, numbers and booleans are used
+   * (at most 10); other values are ignored. Not used by the grid itself.
+   * @since v3.4
+   */
+  aiExamples?: unknown[];
 }
 
 /** Column definition used exclusively in List View mode. */
@@ -300,6 +337,40 @@ export interface GridValueGetterParams<R extends GridValidRowModel = GridRowMode
   value: unknown;
 }
 
+/** The way a fill extends the cell range. @since v3.5 */
+export type GridFillDirection = 'down' | 'up' | 'right' | 'left';
+
+/** Parameters passed to `GridColDef.fillValue`. @since v3.5 */
+export interface GridFillValueParams<R extends GridValidRowModel = GridRowModel> {
+  /** The row of the cell being filled, as stored now. */
+  row: R;
+  id: GridRowId;
+  field: string;
+  colDef: GridColDef<R>;
+  direction: GridFillDirection;
+  /** The source cells' values in fill order: the value next to the first filled cell is last. */
+  sourceValues: unknown[];
+  /** Position of this cell among the filled cells of its line, from 0 (next to the source). */
+  index: number;
+  /** What the grid would write: the continued series, the repeated pattern or a copy. */
+  value: unknown;
+  /** Whether a copy was asked for (Alt held at release, or the keyboard shortcuts), so no series. */
+  copy: boolean;
+}
+
+/** `onFill` details: the batch edit result plus the direction of the fill. @since v3.5 */
+export interface GridFillResult extends GridBatchEditResult {
+  direction: GridFillDirection;
+}
+
+/** Parameters passed to `GridColDef.valueParser`. @since v3.4 */
+export interface GridValueParserParams<R extends GridValidRowModel = GridRowModel> {
+  /** The row the text is pasted into, as stored now. */
+  row: R;
+  field: string;
+  colDef: GridColDef<R>;
+}
+
 /**
  * Parameters passed to the `valueSetter` function.
  * @since v3.0
@@ -803,6 +874,54 @@ export interface GridRowScrollEndParams {
   viewportHeight: number;
 }
 
+/**
+ * Why a cell of a batch edit (paste, range clear, undo, redo) was not written:
+ * - `'notEditable'`: the column is not `editable`, `isCellEditable` returned false, or the row is a
+ *   synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total);
+ * - `'invalidValue'`: the pasted text does not parse for the column type (or `valueParser` rejected it);
+ * - `'changed'`: undo/redo only, the cell no longer holds the value the history recorded;
+ * - `'missing'`: undo/redo only, the row is gone.
+ * @since v3.4
+ */
+export type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+
+/** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
+export interface GridBatchEditResult {
+  /** Rows whose `processRowUpdate` succeeded and that were stored, in the order they were first touched. */
+  updated: GridRowId[];
+  /** Rows whose `valueSetter` or `processRowUpdate` threw or rejected (also reported to `onProcessRowUpdateError`). */
+  failed: { id: GridRowId; error: unknown }[];
+  /** Cells that were not written, with the reason. */
+  skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[];
+}
+
+/** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
+export interface GridClipboardPasteResult extends GridBatchEditResult {
+  text: string;
+}
+
+/** `onBeforeClipboardPaste` params. @since v3.4 */
+export interface GridBeforeClipboardPasteParams {
+  /** The clipboard text (`text/plain`). */
+  text: string;
+  /** The cell the paste starts from (the range's top-left cell, or the focused cell). */
+  anchor: GridCellCoordinates | null;
+}
+
+/** `onHistoryChange` params. @since v3.4 */
+export interface GridHistoryChangeParams {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Number of actions that can be undone. */
+  size: number;
+}
+
+/** `undoRedo` options. @since v3.4 */
+export interface GridUndoRedoOptions {
+  /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
+  limit?: number;
+}
+
 /** Overrideable user-visible strings for internationalisation. All fields are optional; defaults match the built-in English strings. */
 export interface GridLocaleText {
     /** Label before the rows-per-page select. Default: `"Rows per page:"` */
@@ -819,6 +938,8 @@ export interface GridLocaleText {
      * @since v3.3
      */
     cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
+    /** Label of the toolbar button that opens the `aiAssistant` panel. Default: `"Ask AI"` @since v3.5 */
+    aiAssistantButton?: string;
 }
 
 /**
@@ -844,6 +965,18 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    * Defaults to `false`.
    */
   wrapHeaderText?: boolean;
+  /**
+   * Adds a filter row under the column headers: one control per column (text, number, date, a Yes / No
+   * select for booleans, the `valueOptions` for singleSelect) with an operator menu and a clear button.
+   * It reads and writes `filterModel`: each cell owns the root-level item with `id: 'header:<field>'`,
+   * so the filter panel, quick filter and `filterMode="server"` keep working. A model the row cannot
+   * show (root `logicOperator: 'or'`, other conditions on the column, nested groups) is shown as
+   * "Custom filter" and left untouched. See `docs/features/header-filters.md`. Defaults to `false`.
+   * @since v3.5
+   */
+  headerFilters?: boolean;
+  /** Height of the header filter row (`headerFilters`) in pixels. Defaults to 40. @since v3.5 */
+  headerFilterHeight?: number;
   /** If true, the grid height will adjust to match the total height of its rows. */
   autoHeight?: boolean;
   /**
@@ -939,6 +1072,49 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    */
   showCellSelectionStats?: boolean;
 
+  /**
+   * With `cellSelection` on, Ctrl/Cmd+V pastes tab-separated text (Excel, Google Sheets) into the
+   * editable cells from the range's top-left cell (or the focused cell), through `valueSetter` and
+   * `processRowUpdate`. `true` turns the shortcut off; `apiRef.pasteText()` still works. Default: false.
+   * @since v3.4
+   */
+  disableClipboardPaste?: boolean;
+  /**
+   * Fired after every paste with the result (`updated` rows, `failed` rows, `skipped` cells and why)
+   * and the pasted text. @since v3.4
+   */
+  onClipboardPaste?: (result: GridClipboardPasteResult) => void;
+  /**
+   * Called before a paste is applied. Return `false` to cancel it, or a string to paste instead of the
+   * clipboard text. A throw cancels the paste. @since v3.4
+   */
+  onBeforeClipboardPaste?: (params: GridBeforeClipboardPasteParams) => boolean | string;
+  /**
+   * With `cellSelection` on, Delete / Backspace on a range of more than one cell empties its editable
+   * cells (`null`, or `''` in string columns) as one edit. `true` turns that off. Default: false.
+   * @since v3.4
+   */
+  disableRangeClear?: boolean;
+  /**
+   * Undo and redo of cell edits, pastes and range clears: Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z and Ctrl+Y while
+   * focus is in the grid and no editor is open, and `apiRef.undo()` / `redo()`. Undo and redo write
+   * through `valueSetter` and `processRowUpdate`, like an edit. `{ limit }` sets how many actions are
+   * kept (default 100). Default: false. @since v3.4
+   */
+  undoRedo?: boolean | GridUndoRedoOptions;
+  /** Fired when what can be undone or redone changes (`undoRedo`). @since v3.4 */
+  onHistoryChange?: (params: GridHistoryChangeParams) => void;
+  /**
+   * With `cellSelection` on, a fill handle sits on the bottom-right corner of the range: dragging it
+   * down, up, right or left fills the new cells from the range (a series of numbers or dates with an
+   * equal step continues, anything else repeats; Alt at release copies), and Ctrl/Cmd+D / Ctrl/Cmd+R
+   * fill down from the range's top row / right from its left column. `true` hides the handle and turns
+   * the shortcuts off. Default: false. @since v3.5
+   */
+  disableFillHandle?: boolean;
+  /** Fired after every fill with the result and its direction. @since v3.5 */
+  onFill?: (result: GridFillResult) => void;
+
   /** Loading state. With no rows the body shows skeleton rows (or `slots.loadingOverlay`); with rows, they stay and a progress bar (or `slots.loadingOverlay`) is shown over them. */
   loading?: boolean;
   /** Visual density of the grid. */
@@ -1031,8 +1207,13 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   /** Initial expansion depth for Tree Data. */
   defaultGroupingExpansionDepth?: number;
 
-  /** Controlled state for row grouping. */
+  /**
+   * The row grouping model: the fields to group by, outermost first. Passing it controls grouping;
+   * without it the grid keeps its own model, which `apiRef.setRowGroupingModel` and the AI assistant change.
+   */
   rowGroupingModel?: GridRowGroupingModel;
+  /** Fired when the row grouping model changes (`apiRef.setRowGroupingModel`, the AI assistant). @since v3.5 */
+  onRowGroupingModelChange?: (model: GridRowGroupingModel) => void;
   /** Controlled state for data aggregation (e.g., { salary: 'sum' }). */
   aggregationModel?: GridAggregationModel;
   /** Callback fired when aggregation model changes. */
@@ -1096,6 +1277,8 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
      * (plus `slotProps.cellSelectionStats`). @since v3.3
      */
     cellSelectionStats?: React.ComponentType<GridCellSelectionStatsSlotProps & Record<string, unknown>>;
+    /** Replaces the `aiAssistant` panel. Receives `GridAiAssistantPanelProps` while the panel is open. @since v3.5 */
+    aiAssistantPanel?: React.ComponentType<GridAiAssistantPanelProps & Record<string, unknown>>;
   };
   /** Properties passed directly to custom slots. */
   slotProps?: {
@@ -1113,6 +1296,8 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
     footer?: Partial<GridFooterSlotProps> & Record<string, unknown>;
     /** Merged over the `GridCellSelectionStatsSlotProps` the grid passes to the status bar. */
     cellSelectionStats?: Partial<GridCellSelectionStatsSlotProps> & Record<string, unknown>;
+    /** Extra props for `slots.aiAssistantPanel`. */
+    aiAssistantPanel?: Record<string, unknown>;
   };
 
   /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
@@ -1125,6 +1310,18 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    * column headers, supporting multiple levels of nesting.
    */
   columnGroupingModel?: GridColumnGroupingModel;
+
+  /**
+   * The "Ask AI" prompt panel: users describe the view they want and the grid applies the validated
+   * reply as one undoable step, shown as removable chips. The built-in toolbar shows an **Ask AI**
+   * button; `apiRef.openAiAssistant()` opens it without one. Build `onPrompt` with
+   * `createGridAiPromptHandler` from `@opencorestack/opengridx/ai`. @since v3.5
+   */
+  aiAssistant?: GridAiAssistantOptions;
+  /** Fired after the assistant applied a reply. @since v3.5 */
+  onAiAssistantApply?: (result: GridAiPromptResult) => void;
+  /** Fired when `onPrompt` fails or returns a result that was not validated. @since v3.5 */
+  onAiAssistantError?: (error: unknown) => void;
 }
 
 /**
@@ -1328,4 +1525,149 @@ export interface GridApi<R extends GridValidRowModel = GridRowModel> {
    * copy; rejects when the clipboard write fails. @since v3.3
    */
   copySelectedCells: () => Promise<void>;
+
+  /**
+   * Pastes tab-separated text as Ctrl/Cmd+V does: from `anchor` (default: the range's top-left cell,
+   * else the focused cell), with `onBeforeClipboardPaste` and `onClipboardPaste`. Works with
+   * `disableClipboardPaste`. Resolves once every row's `processRowUpdate` has settled. @since v3.4
+   */
+  pasteText: (text: string, anchor?: GridCellCoordinates) => Promise<GridBatchEditResult>;
+  /** Undoes the last action (`undoRedo`). Resolves with what was written. @since v3.4 */
+  undo: () => Promise<GridBatchEditResult>;
+  /** Redoes the last undone action (`undoRedo`). @since v3.4 */
+  redo: () => Promise<GridBatchEditResult>;
+  /** Whether there is an action to undo. @since v3.4 */
+  canUndo: () => boolean;
+  /** Whether there is an undone action to redo. @since v3.4 */
+  canRedo: () => boolean;
+  /** Forgets every action (undo and redo). @since v3.4 */
+  clearHistory: () => void;
+
+  /** Replaces the sort model (fires `onSortModelChange`). @since v3.5 */
+  setSortModel: (model: GridSortItem[]) => void;
+  /** Replaces the row grouping model (fires `onRowGroupingModelChange`). @since v3.5 */
+  setRowGroupingModel: (model: GridRowGroupingModel) => void;
+  /** Replaces the aggregation model (fires `onAggregationModelChange`). @since v3.5 */
+  setAggregationModel: (model: GridAggregationModel) => void;
+  /** Replaces the column visibility model (fires `onColumnVisibilityModelChange`). @since v3.5 */
+  setColumnVisibilityModel: (model: GridColumnVisibilityModel) => void;
+  /** Replaces the pivot model (fires `onPivotModelChange`). @since v3.5 */
+  setPivotModel: (model: GridPivotModel) => void;
+  /**
+   * The current filter, sort, grouping, aggregation, pivot and column visibility models, in the shape
+   * of the AI toolkit (`GridAiState`). @since v3.5
+   */
+  getGridAiState: () => GridAiState;
+  /** Opens the `aiAssistant` panel (does nothing without `aiAssistant`). @since v3.5 */
+  openAiAssistant: () => void;
+  /** Closes the `aiAssistant` panel. @since v3.5 */
+  closeAiAssistant: () => void;
+}
+
+// ── AI toolkit (v3.4 state types; v3.5 assistant) ──────────────────────────────────────────────────
+// Type-only and React-free: the `@opencorestack/opengridx/ai` entry point re-exports them.
+
+/** A part of the grid state a model may change. @since v3.4 */
+export type GridAiPart = 'filter' | 'sort' | 'grouping' | 'aggregation' | 'pivot' | 'columnVisibility';
+
+/** Grid state as the AI toolkit reads and writes it. Only the parts present are applied. @since v3.4 */
+export interface GridAiState {
+  filterModel?: GridFilterModel;
+  sortModel?: GridSortItem[];
+  rowGroupingModel?: GridRowGroupingModel;
+  aggregationModel?: GridAggregationModel;
+  pivotModel?: GridPivotModel;
+  columnVisibilityModel?: GridColumnVisibilityModel;
+}
+
+/** One thing the validator dropped or could not use. `path` points into the model output. @since v3.4 */
+export interface GridAiValidationError {
+  path: string;
+  message: string;
+}
+
+/** One earlier prompt of this session and the state the assistant applied for it. @since v3.5 */
+export interface GridAiHistoryEntry {
+  prompt: string;
+  applied: GridAiState;
+}
+
+/** What `aiAssistant.onPrompt` receives next to the prompt. @since v3.5 */
+export interface GridAiPromptContext {
+  /** The grid's current models (`apiRef.getGridAiState()`). */
+  currentState: GridAiState;
+  /** Earlier prompts of this session, oldest first. */
+  history: GridAiHistoryEntry[];
+  /** Aborted when the user presses Stop, sends another prompt or closes the panel. */
+  signal: AbortSignal;
+}
+
+/**
+ * What `aiAssistant.onPrompt` resolves with. The grid applies it only when its `state` comes from
+ * `validateGridAiState` (or `createGridAiPromptHandler`), which brands the result and its `state`.
+ * @since v3.5
+ */
+export interface GridAiPromptResult {
+  state: GridAiState;
+  /** What the validator dropped; shown as "Ignored: …". */
+  errors: GridAiValidationError[];
+  /** The assistant's reply text, shown in the panel. */
+  message?: string;
+}
+
+/** The `aiAssistant` prop: the "Ask AI" prompt panel. @since v3.5 */
+export interface GridAiAssistantOptions {
+  /**
+   * Answers a prompt. Call your own model and return the validated result: `createGridAiPromptHandler`
+   * from `@opencorestack/opengridx/ai` builds this function, or call `validateGridAiState` yourself.
+   */
+  onPrompt: (prompt: string, context: GridAiPromptContext) => Promise<GridAiPromptResult>;
+  /** Placeholder of the prompt input. Default: `"Ask about this table…"` */
+  placeholder?: string;
+  /** Example prompts shown as clickable chips. */
+  suggestions?: string[];
+  /** Shows a microphone button where the browser has speech recognition; the microphone is asked for only on click. Default: true. */
+  voice?: boolean;
+  /** The parts of the state the assistant may change. Default: every part. */
+  parts?: GridAiPart[];
+}
+
+/** One change the assistant applied, shown as a removable chip. @since v3.5 */
+export interface GridAiChip {
+  id: string;
+  part: GridAiPart;
+  label: string;
+}
+
+/** The assistant panel's state. @since v3.5 */
+export type GridAiAssistantStatus = 'idle' | 'running' | 'applied' | 'stopped' | 'error';
+
+/** Props of `slots.aiAssistantPanel` and the built-in panel, rendered while the panel is open. @since v3.5 */
+export interface GridAiAssistantPanelProps {
+  status: GridAiAssistantStatus;
+  /** The status line: "Thinking…", "Applied 3 changes", an error. */
+  statusText: string;
+  /** The assistant's reply text (`result.message`). */
+  message: string | null;
+  /** What the last reply asked for that was ignored. */
+  errors: GridAiValidationError[];
+  /** The changes the last reply applied. */
+  chips: GridAiChip[];
+  /** Earlier prompts of this session, oldest first. */
+  history: GridAiHistoryEntry[];
+  suggestions: string[];
+  placeholder: string;
+  /** `voice` is on and this browser has speech recognition. */
+  voiceAvailable: boolean;
+  /** Undo can restore the state from before the last reply. */
+  canUndo: boolean;
+  submit: (prompt: string) => void;
+  /** Aborts the running request. */
+  stop: () => void;
+  /** Restores the state from before the last reply. */
+  undo: () => void;
+  /** Re-applies the last reply without this change. */
+  removeChip: (id: string) => void;
+  /** Closes the panel; focus returns to where it was before it opened. */
+  close: () => void;
 }

package/lib/utils/aiAssistant.ts

@@ -0,0 +1,205 @@
+// Pure helpers of the `aiAssistant` panel: which parts of a reply it may apply, what to restore on
+// Undo, the removable chips and what a state looks like without one of them. No AI code: the reply
+// was validated by the `/ai` entry point before it reaches the grid.
+import type {
+    GridAiChip,
+    GridAiPart,
+    GridAiState,
+    GridAiValidationError,
+    GridApi,
+    GridFilterGroup,
+    GridFilterItem,
+} from '../types';
+
+export const AI_PARTS: readonly GridAiPart[] = ['filter', 'sort', 'grouping', 'aggregation', 'pivot', 'columnVisibility'];
+
+const PART_KEYS: Record<GridAiPart, keyof GridAiState> = {
+    filter: 'filterModel',
+    sort: 'sortModel',
+    grouping: 'rowGroupingModel',
+    aggregation: 'aggregationModel',
+    pivot: 'pivotModel',
+    columnVisibility: 'columnVisibilityModel',
+};
+
+type StateKey = keyof GridAiState;
+
+function keysOf(state: GridAiState): StateKey[] {
+    return AI_PARTS.map((part) => PART_KEYS[part]).filter((key) => state[key] !== undefined);
+}
+
+/** The parts of `state` that `parts` allows, and an error for each part it does not. */
+export function pickAllowedParts(state: GridAiState, parts: readonly GridAiPart[]): { state: GridAiState; errors: GridAiValidationError[] } {
+    const picked: GridAiState = {};
+    const errors: GridAiValidationError[] = [];
+    for (const part of AI_PARTS) {
+        const key = PART_KEYS[part];
+        if (state[key] === undefined) continue;
+        if (parts.includes(part)) Object.assign(picked, { [key]: state[key] });
+        else errors.push({ path: key, message: 'Part not allowed' });
+    }
+    return { state: picked, errors };
+}
+
+function isEmptyPart(state: GridAiState, key: StateKey): boolean {
+    const value = state[key];
+    if (Array.isArray(value)) return value.length === 0;
+    if (key === 'filterModel') {
+        const model = state.filterModel;
+        return !model || ((model.items ?? []).length === 0 && (model.quickFilterValues ?? []).length === 0);
+    }
+    if (key === 'pivotModel') {
+        const model = state.pivotModel;
+        return !model || (model.rowFields.length === 0 && model.columnFields.length === 0 && model.valueFields.length === 0);
+    }
+    return typeof value === 'object' && value !== null && Object.keys(value).length === 0;
+}
+
+/** The state key an error path starts with (`'sortModel[0].field'` → `'sortModel'`). */
+function errorKey(path: string): string {
+    let end = path.length;
+    for (const sep of ['.', '[']) {
+        const at = path.indexOf(sep);
+        if (at >= 0 && at < end) end = at;
+    }
+    return path.slice(0, end);
+}
+
+/**
+ * Leaves out a part that is empty only because the validator dropped everything in it (`sortModel`
+ * naming an unknown field comes back as `[]`): applying it would clear the grid's model, which the
+ * reply did not ask for. An empty part without errors ("clear the sort") is kept.
+ */
+export function dropEmptiedParts(state: GridAiState, errors: readonly GridAiValidationError[]): GridAiState {
+    const failed = new Set(errors.map((error) => errorKey(typeof error.path === 'string' ? error.path : '')));
+    const out: GridAiState = {};
+    for (const key of keysOf(state)) {
+        if (!(failed.has(key) && isEmptyPart(state, key))) Object.assign(out, { [key]: state[key] });
+    }
+    return out;
+}
+
+/** The current values of the parts `state` changes: what Undo restores. */
+export function snapshotParts(state: GridAiState, current: GridAiState): GridAiState {
+    const snapshot: GridAiState = {};
+    for (const key of keysOf(state)) Object.assign(snapshot, { [key]: current[key] });
+    return snapshot;
+}
+
+/**
+ * The models to apply for `applied` over `previous` (the snapshot taken before the reply): column
+ * visibility is merged over the previous model; a part removed from `applied` gets its previous value back.
+ */
+export function effectiveState(applied: GridAiState, previous: GridAiState): GridAiState {
+    const out: GridAiState = {};
+    for (const key of AI_PARTS.map((part) => PART_KEYS[part])) {
+        if (!(key in previous) && applied[key] === undefined) continue;
+        if (applied[key] === undefined) Object.assign(out, { [key]: previous[key] });
+        else if (key === 'columnVisibilityModel') out.columnVisibilityModel = { ...previous.columnVisibilityModel, ...applied.columnVisibilityModel };
+        else Object.assign(out, { [key]: applied[key] });
+    }
+    return out;
+}
+
+type GridAiStateSetters = Pick<GridApi, 'setFilterModel' | 'setSortModel' | 'setRowGroupingModel' | 'setAggregationModel' | 'setPivotModel' | 'setColumnVisibilityModel'>;
+
+/** Applies every part present in `state` through the API (each fires its change callback). */
+export function applyGridAiState(api: GridAiStateSetters, state: GridAiState): void {
+    if (state.filterModel) api.setFilterModel(state.filterModel);
+    if (state.sortModel) api.setSortModel(state.sortModel);
+    if (state.rowGroupingModel) api.setRowGroupingModel(state.rowGroupingModel);
+    if (state.aggregationModel) api.setAggregationModel(state.aggregationModel);
+    if (state.pivotModel) api.setPivotModel(state.pivotModel);
+    if (state.columnVisibilityModel) api.setColumnVisibilityModel(state.columnVisibilityModel);
+}
+
+function valueText(value: unknown): string {
+    if (Array.isArray(value)) return value.map(valueText).join(', ');
+    if (value instanceof Date) return value.toISOString().slice(0, 10);
+    return value === undefined || value === null ? '' : String(value);
+}
+
+function filterLabel(node: GridFilterItem | GridFilterGroup, label: (field: string) => string): string {
+    if ('items' in node) return `(${node.items.map((child) => filterLabel(child, label)).join(` ${node.logicOperator} `)})`;
+    return [label(node.field), node.operator, valueText(node.value)].filter(Boolean).join(' ');
+}
+
+const FN_LABELS: Record<string, string> = { sum: 'Sum', avg: 'Average', count: 'Count', min: 'Min', max: 'Max', unique: 'Unique' };
+
+/** One chip per change: filter item, quick-filter words, sort key, grouping field, aggregation, visibility change, pivot. */
+export function buildAiChips(applied: GridAiState, label: (field: string) => string): GridAiChip[] {
+    const chips: GridAiChip[] = [];
+    const { filterModel, sortModel, rowGroupingModel, aggregationModel, pivotModel, columnVisibilityModel } = applied;
+    if (filterModel) {
+        const items = filterModel.items ?? [];
+        items.forEach((item, i) => chips.push({ id: `filter:${i}`, part: 'filter', label: filterLabel(item, label) }));
+        const words = filterModel.quickFilterValues ?? [];
+        if (words.length > 0) chips.push({ id: 'filter:quick', part: 'filter', label: `Search: ${words.join(' ')}` });
+        if (items.length === 0 && words.length === 0) chips.push({ id: 'filter:clear', part: 'filter', label: 'No filters' });
+    }
+    if (sortModel) {
+        sortModel.forEach((s, i) => chips.push({ id: `sort:${i}`, part: 'sort', label: `Sort: ${label(s.field)}, ${s.sort === 'desc' ? 'descending' : 'ascending'}` }));
+        if (sortModel.length === 0) chips.push({ id: 'sort:clear', part: 'sort', label: 'No sorting' });
+    }
+    if (rowGroupingModel) {
+        rowGroupingModel.forEach((field, i) => chips.push({ id: `grouping:${i}`, part: 'grouping', label: `Group: ${label(field)}` }));
+        if (rowGroupingModel.length === 0) chips.push({ id: 'grouping:clear', part: 'grouping', label: 'No grouping' });
+    }
+    if (aggregationModel) {
+        const fields = Object.keys(aggregationModel);
+        fields.forEach((field) => {
+            const fn = aggregationModel[field];
+            chips.push({ id: `aggregation:${field}`, part: 'aggregation', label: `${FN_LABELS[fn] ?? fn}: ${label(field)}` });
+        });
+        if (fields.length === 0) chips.push({ id: 'aggregation:clear', part: 'aggregation', label: 'No summaries' });
+    }
+    if (pivotModel) {
+        const fields = [...pivotModel.rowFields, ...pivotModel.columnFields, ...pivotModel.valueFields.map((v) => v.field)];
+        chips.push({ id: 'pivot', part: 'pivot', label: fields.length > 0 ? `Pivot: ${fields.map(label).join(', ')}` : 'No pivot' });
+    }
+    if (columnVisibilityModel) {
+        for (const field of Object.keys(columnVisibilityModel)) {
+            chips.push({ id: `columnVisibility:${field}`, part: 'columnVisibility', label: `${columnVisibilityModel[field] ? 'Show' : 'Hide'}: ${label(field)}` });
+        }
+    }
+    return chips;
+}
+
+/**
+ * `applied` without the change a chip stands for. A part left with no change is dropped, so
+ * `effectiveState` gives it its value from before the reply.
+ */
+export function removeAiChip(applied: GridAiState, id: string): GridAiState {
+    const next: GridAiState = { ...applied };
+    const sep = id.indexOf(':');
+    const part = sep < 0 ? id : id.slice(0, sep);
+    const rest = sep < 0 ? '' : id.slice(sep + 1);
+    const index = Number(rest);
+    if (part === 'filter' && next.filterModel) {
+        const model = { ...next.filterModel };
+        if (rest === 'quick') delete model.quickFilterValues;
+        else if (rest === 'clear') model.items = [];
+        else model.items = (model.items ?? []).filter((_, i) => i !== index);
+        if ((model.items ?? []).length === 0 && (model.quickFilterValues ?? []).length === 0) delete next.filterModel;
+        else next.filterModel = model;
+    } else if (part === 'sort' && next.sortModel) {
+        next.sortModel = next.sortModel.filter((_, i) => i !== index);
+        if (next.sortModel.length === 0 || rest === 'clear') delete next.sortModel;
+    } else if (part === 'grouping' && next.rowGroupingModel) {
+        next.rowGroupingModel = next.rowGroupingModel.filter((_, i) => i !== index);
+        if (next.rowGroupingModel.length === 0 || rest === 'clear') delete next.rowGroupingModel;
+    } else if (part === 'aggregation' && next.aggregationModel) {
+        const model = { ...next.aggregationModel };
+        delete model[rest];
+        if (Object.keys(model).length === 0) delete next.aggregationModel;
+        else next.aggregationModel = model;
+    } else if (part === 'columnVisibility' && next.columnVisibilityModel) {
+        const model = { ...next.columnVisibilityModel };
+        delete model[rest];
+        if (Object.keys(model).length === 0) delete next.columnVisibilityModel;
+        else next.columnVisibilityModel = model;
+    } else if (part === 'pivot') {
+        delete next.pivotModel;
+    }
+    return next;
+}

package/lib/utils/aiBrand.ts

@@ -0,0 +1,17 @@
+// The "validated" brand of the AI toolkit. `validateGridAiState` (in the `/ai` entry point) puts it on
+// its result and on the result's `state`; the grid's `aiAssistant` applies a state only when it carries
+// it. Shared by both bundles, so it holds no AI code: just the registered symbol and two helpers.
+
+/** `Symbol.for('opengridx.ai.validated')`: the same symbol in every bundle and realm. */
+export const GRID_AI_VALIDATED_BRAND: symbol = Symbol.for('opengridx.ai.validated');
+
+/** Brands `value` (non-enumerable, so it does not change equality, spreading or JSON) and returns it. */
+export function brandGridAiValidated<T extends object>(value: T): T {
+    Object.defineProperty(value, GRID_AI_VALIDATED_BRAND, { value: true, enumerable: false });
+    return value;
+}
+
+/** Whether `value` carries the brand. */
+export function isGridAiValidated(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && (value as Record<symbol, unknown>)[GRID_AI_VALIDATED_BRAND] === true;
+}