@opencorestack/opengridx 3.4.0 → 3.5.0

package/lib/hooks/features/useGridAiAssistant.ts

@@ -0,0 +1,284 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { MutableRefObject } from 'react';
+import type {
+    GridAiAssistantOptions,
+    GridAiAssistantPanelProps,
+    GridAiAssistantStatus,
+    GridAiHistoryEntry,
+    GridAiPromptResult,
+    GridAiState,
+    GridAiValidationError,
+    GridApi,
+    GridColDef,
+} from '../../types';
+import { attempt } from '../../utils/attempt';
+import { isGridAiValidated } from '../../utils/aiBrand';
+import {
+    AI_PARTS,
+    applyGridAiState,
+    buildAiChips,
+    dropEmptiedParts,
+    effectiveState,
+    pickAllowedParts,
+    removeAiChip,
+    snapshotParts,
+} from '../../utils/aiAssistant';
+
+export interface UseGridAiAssistantParams {
+    apiRef: MutableRefObject<GridApi>;
+    /** The `aiAssistant` prop. Without it the hook is inert. */
+    options: GridAiAssistantOptions | undefined;
+    /** Columns, for the chip labels (header names). */
+    columns: readonly GridColDef[];
+    onApply?: (result: GridAiPromptResult) => void;
+    onError?: (error: unknown) => void;
+}
+
+export interface UseGridAiAssistantResult {
+    enabled: boolean;
+    open: boolean;
+    /** Opens the panel; focus returns to `trigger` (default: the focused element) when it closes. */
+    openPanel: (trigger?: HTMLElement | null) => void;
+    /** Opens the panel, or closes it when it is open. */
+    togglePanel: (trigger?: HTMLElement | null) => void;
+    closePanel: () => void;
+    /** Props of the panel while it is open, else null. */
+    panelProps: GridAiAssistantPanelProps | null;
+    /** The status line for the grid's live region. */
+    announcement: string;
+}
+
+const DEFAULT_PLACEHOLDER = 'Ask about this table…';
+const NO_SUGGESTIONS: string[] = [];
+const NO_ERRORS: GridAiValidationError[] = [];
+const NOT_VALIDATED = 'The reply was not validated';
+
+interface Applied {
+    /** The reply's parts the grid applied (chips are built from it). */
+    state: GridAiState;
+    /** The same parts as they were before: what Undo restores. */
+    previous: GridAiState;
+}
+
+/** Whether this browser has speech recognition. The microphone is never asked for here. */
+export function hasSpeechRecognition(): boolean {
+    return typeof window !== 'undefined' && ('SpeechRecognition' in window || 'webkitSpeechRecognition' in window);
+}
+
+function isAbortError(error: unknown): boolean {
+    return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'AbortError';
+}
+
+function errorText(error: unknown): string {
+    return error instanceof Error && error.message ? error.message : 'Unknown error';
+}
+
+function changesText(count: number, ignored: number): string {
+    const applied = count === 0 ? 'No changes' : `Applied ${count} ${count === 1 ? 'change' : 'changes'}`;
+    return ignored > 0 ? `${applied}, ${ignored} ignored` : applied;
+}
+
+/** Calls a consumer callback; a throw is warned about (development) and otherwise ignored. */
+function notify<T>(callback: ((value: T) => void) | undefined, value: T, name: string): void {
+    if (!callback) return;
+    const result = attempt(() => callback(value));
+    if (!result.ok && process.env.NODE_ENV !== 'production') console.warn(`[OpenGridX] ${name} threw.`, result.error);
+}
+
+/**
+ * The `aiAssistant` prompt panel: open state, the request (with Stop), applying a validated reply as
+ * one undoable step, chips, Undo, the session's prompts and the status line. Results are applied only
+ * when their `state` carries the brand of `validateGridAiState`. Installs `apiRef.openAiAssistant` /
+ * `closeAiAssistant`.
+ */
+export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiAssistantResult {
+    const { apiRef, options, columns } = params;
+    const enabled = Boolean(options);
+    const [open, setOpen] = useState(false);
+    const [status, setStatus] = useState<GridAiAssistantStatus>('idle');
+    const [statusText, setStatusText] = useState('');
+    const [message, setMessage] = useState<string | null>(null);
+    const [errors, setErrors] = useState<GridAiValidationError[]>(NO_ERRORS);
+    const [applied, setApplied] = useState<Applied | null>(null);
+    const [history, setHistory] = useState<GridAiHistoryEntry[]>([]);
+
+    const controllerRef = useRef<AbortController | null>(null);
+    const returnFocusRef = useRef<HTMLElement | null>(null);
+    const latestRef = useRef({ params, applied, history, open });
+    useLayoutEffect(() => {
+        latestRef.current = { params, applied, history, open };
+    });
+
+    const labelOf = useMemo(() => {
+        const byField = new Map(columns.map((col) => [col.field, col.headerName || col.field]));
+        return (field: string) => byField.get(field) ?? field;
+    }, [columns]);
+    const chips = useMemo(() => (applied ? buildAiChips(applied.state, labelOf) : []), [applied, labelOf]);
+
+    const abortRequest = useCallback(() => {
+        const controller = controllerRef.current;
+        controllerRef.current = null;
+        if (controller) controller.abort();
+    }, []);
+
+    // Abort a running request when the grid unmounts.
+    useEffect(() => abortRequest, [abortRequest]);
+
+    const openPanel = useCallback((trigger?: HTMLElement | null) => {
+        if (!latestRef.current.params.options) return;
+        const active = typeof document === 'undefined' ? null : document.activeElement;
+        returnFocusRef.current = trigger ?? (active instanceof HTMLElement ? active : null);
+        setOpen(true);
+    }, []);
+
+    const closePanel = useCallback(() => {
+        if (controllerRef.current) {
+            abortRequest();
+            setStatus('stopped');
+            setStatusText('Stopped');
+        }
+        setOpen(false);
+        const target = returnFocusRef.current;
+        returnFocusRef.current = null;
+        if (target && target.isConnected) target.focus();
+    }, [abortRequest]);
+
+    const togglePanel = useCallback((trigger?: HTMLElement | null) => {
+        if (latestRef.current.open) closePanel();
+        else openPanel(trigger);
+    }, [openPanel, closePanel]);
+
+    const fail = useCallback((text: string, error: unknown) => {
+        setStatus('error');
+        setStatusText(text);
+        setMessage(null);
+        setErrors(NO_ERRORS);
+        notify(latestRef.current.params.onError, error, 'onAiAssistantError');
+    }, []);
+
+    const applyResult = useCallback((prompt: string, result: GridAiPromptResult) => {
+        const { params: current } = latestRef.current;
+        const isObject = typeof result === 'object' && result !== null;
+        if (!isObject || !isGridAiValidated(result.state)) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[OpenGridX] aiAssistant: the onPrompt result was not applied because its state was not validated. Return the result of createGridAiPromptHandler, or pass the model reply through validateGridAiState (from @opencorestack/opengridx/ai) and return its state.');
+            }
+            fail(NOT_VALIDATED, new Error(NOT_VALIDATED));
+            return;
+        }
+        const allowed = pickAllowedParts(result.state, current.options?.parts ?? AI_PARTS);
+        const ignored = [...(Array.isArray(result.errors) ? result.errors : []), ...allowed.errors];
+        const state = dropEmptiedParts(allowed.state, ignored);
+        const api = apiRef.current;
+        const previous = snapshotParts(state, api.getGridAiState());
+        applyGridAiState(api, effectiveState(state, previous));
+        setApplied({ state, previous });
+        setErrors(ignored);
+        setMessage(typeof result.message === 'string' && result.message ? result.message : null);
+        setHistory((list) => [...list, { prompt, applied: state }]);
+        setStatus('applied');
+        setStatusText(changesText(buildAiChips(state, (f) => f).length, ignored.length));
+        notify(current.onApply, result, 'onAiAssistantApply');
+    }, [apiRef, fail]);
+
+    const submit = useCallback((text: string) => {
+        const prompt = text.trim();
+        const { params: current, history: earlier } = latestRef.current;
+        const onPrompt = current.options?.onPrompt;
+        if (!prompt || !onPrompt) return;
+        abortRequest();
+        const controller = new AbortController();
+        controllerRef.current = controller;
+        setStatus('running');
+        setStatusText('Thinking…');
+        setMessage(null);
+        setErrors(NO_ERRORS);
+        const context = { currentState: apiRef.current.getGridAiState(), history: earlier, signal: controller.signal };
+        const call = attempt(() => onPrompt(prompt, context));
+        const pending = call.ok ? Promise.resolve(call.value) : Promise.reject(call.error);
+        pending.then(
+            (result) => {
+                if (controllerRef.current !== controller) return;
+                controllerRef.current = null;
+                applyResult(prompt, result);
+            },
+            (error: unknown) => {
+                if (controllerRef.current !== controller) return;
+                controllerRef.current = null;
+                if (controller.signal.aborted || isAbortError(error)) {
+                    setStatus('stopped');
+                    setStatusText('Stopped');
+                    return;
+                }
+                fail(`The assistant could not answer: ${errorText(error)}`, error);
+            },
+        );
+    }, [apiRef, abortRequest, applyResult, fail]);
+
+    const stop = useCallback(() => {
+        if (!controllerRef.current) return;
+        abortRequest();
+        setStatus('stopped');
+        setStatusText('Stopped');
+    }, [abortRequest]);
+
+    const undo = useCallback(() => {
+        const last = latestRef.current.applied;
+        if (!last) return;
+        applyGridAiState(apiRef.current, last.previous);
+        setApplied(null);
+        setErrors(NO_ERRORS);
+        setMessage(null);
+        setStatus('idle');
+        setStatusText('Undone');
+    }, [apiRef]);
+
+    const removeChip = useCallback((id: string) => {
+        const last = latestRef.current.applied;
+        if (!last) return;
+        const state = removeAiChip(last.state, id);
+        applyGridAiState(apiRef.current, effectiveState(state, last.previous));
+        setApplied({ state, previous: last.previous });
+        setStatusText('Change removed');
+    }, [apiRef]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        api.openAiAssistant = () => openPanel();
+        api.closeAiAssistant = () => {
+            if (latestRef.current.open) closePanel();
+        };
+    }, [apiRef, openPanel, closePanel]);
+
+    const isOpen = enabled && open;
+    const panelProps = useMemo<GridAiAssistantPanelProps | null>(() => {
+        if (!isOpen || !options) return null;
+        return {
+            status,
+            statusText,
+            message,
+            errors,
+            chips,
+            history,
+            suggestions: options.suggestions ?? NO_SUGGESTIONS,
+            placeholder: options.placeholder ?? DEFAULT_PLACEHOLDER,
+            voiceAvailable: options.voice !== false && hasSpeechRecognition(),
+            canUndo: applied !== null,
+            submit,
+            stop,
+            undo,
+            removeChip,
+            close: closePanel,
+        };
+    }, [isOpen, options, status, statusText, message, errors, chips, history, applied, submit, stop, undo, removeChip, closePanel]);
+
+    return {
+        enabled,
+        open: isOpen,
+        openPanel,
+        togglePanel,
+        closePanel,
+        panelProps,
+        announcement: enabled ? statusText : '',
+    };
+}

package/lib/hooks/features/useGridBatchEdit.ts

@@ -11,8 +11,8 @@ import {
 } from '../../utils/editing/commit';
 import type { GridCellChange } from '../../utils/editing/commit';
 
-/** What made a commit: history records `edit`, `paste` and `clear`; `undo` / `redo` replay it. */
-export type GridEditSource = 'edit' | 'paste' | 'clear' | 'undo' | 'redo';
+/** What made a commit: history records `edit`, `paste`, `clear` and `fill`; `undo` / `redo` replay it. */
+export type GridEditSource = 'edit' | 'paste' | 'clear' | 'fill' | 'undo' | 'redo';
 
 /** One cell to write in a batch edit. */
 export interface GridBatchCellEdit {

package/lib/index.ts

@@ -112,6 +112,9 @@ export type {
     GridEditSkipReason,
     GridBatchEditResult,
     GridClipboardPasteResult,
+    GridFillDirection,
+    GridFillResult,
+    GridFillValueParams,
     GridBeforeClipboardPasteParams,
     GridHistoryChangeParams,
     GridUndoRedoOptions,

package/lib/styles/opengridx.css

@@ -4,6 +4,7 @@
 @import '../components/ui/Input.css';
 @import '../components/DataGrid/DataGrid.css';
 @import '../components/Header/Header.css';
+@import '../components/HeaderFilter/HeaderFilter.css';
 @import '../components/Row/Row.css';
 @import '../components/Cell/Cell.css';
 @import '../components/Cell/GridEditInputCell.css';
@@ -27,3 +28,4 @@
 @import '../components/ColumnGroupHeader/ColumnGroupHeader.css';
 @import '../components/Tooltip/Tooltip.css';
 @import '../components/CellSelectionStats/CellSelectionStats.css';
+@import '../components/AiAssistant/GridAiAssistantPanel.css';

package/lib/theme/DataGridThemeProvider.tsx

@@ -11,6 +11,7 @@ const primaryDerived: Record<string, string> = {
     '--ogx-grid-cell-focus-border': 'var(--ogx-color-primary)',
     '--ogx-range-background': 'color-mix(in srgb, var(--ogx-color-primary) 12%, transparent)',
     '--ogx-range-border': 'var(--ogx-color-primary)',
+    '--ogx-fill-handle-color': 'var(--ogx-range-border)',
     '--ogx-toolbar-btn-primary-bg': 'var(--ogx-color-primary)',
     '--ogx-toolbar-btn-primary-hover': 'var(--ogx-color-primary-dark)',
     '--ogx-toolbar-input-focus-border': 'var(--ogx-color-primary)',
@@ -285,6 +286,7 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-cell-focus-border', g.cellFocusBorder);
         set('--ogx-range-background', g.rangeBackground);
         set('--ogx-range-border', g.rangeBorder);
+        set('--ogx-fill-handle-color', g.fillHandleColor);
         set('--ogx-grid-pinned-left-shadow', g.pinnedLeftShadow);
         set('--ogx-grid-pinned-right-shadow', g.pinnedRightShadow);
         set('--ogx-checkbox-bg', g.checkboxBg);

package/lib/theme/types.ts

@@ -163,6 +163,8 @@ export interface GridThemeGrid {
     rangeBackground?: string;
     /** Outline of a selected cell range (`--ogx-range-border`). Default: the primary colour. @since v3.3 */
     rangeBorder?: string;
+    /** The fill handle on the range's corner (`--ogx-fill-handle-color`). Default: the range border colour. @since v3.5 */
+    fillHandleColor?: string;
     pinnedLeftShadow?: string;
   pinnedRightShadow?: string;
     checkboxBg?: string;

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. */
@@ -196,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. */
@@ -318,6 +337,32 @@ 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. */
@@ -893,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;
 }
 
 /**
@@ -918,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;
   /**
@@ -1045,6 +1104,16 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   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;
@@ -1138,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. */
@@ -1203,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?: {
@@ -1220,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. */
@@ -1232,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;
 }
 
 /**
@@ -1452,4 +1542,132 @@ export interface GridApi<R extends GridValidRowModel = GridRowModel> {
   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;
 }