@opencorestack/opengridx 3.4.0 → 3.5.1

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

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

package/lib/utils/cellSelection.ts

@@ -184,26 +184,43 @@ export interface GridRowCellRange {
     isBottom: boolean;
     /** Rows from this one to the bottom of the range; only set (else 0) when the grid has row spans. */
     bottomOffset: number;
+    /** Data column index (`columnIndexMap`) of the cell carrying the fill handle; only set on its row. @since v3.5 */
+    fillHandleCol?: number;
+}
+
+/** Where the fill handle is drawn: a renderable row index and a data column index (`columnIndexMap`). */
+export interface GridFillHandlePosition {
+    row: number;
+    col: number;
 }
 
 export function getRowCellRange(
     range: { top: number; bottom: number; left: number; right: number } | null | undefined,
     rowIndex: number,
     hasRowSpan: boolean,
+    fillHandle?: GridFillHandlePosition | null,
 ): GridRowCellRange | null {
-    if (!range || rowIndex < range.top || rowIndex > range.bottom) return null;
-    return {
+    const handleCol = fillHandle && fillHandle.row === rowIndex ? fillHandle.col : undefined;
+    if (!range || rowIndex < range.top || rowIndex > range.bottom) {
+        // A single selected cell draws no range, only the handle: an empty column interval.
+        return handleCol === undefined
+            ? null
+            : { left: 0, right: -1, isTop: false, isBottom: false, bottomOffset: 0, fillHandleCol: handleCol };
+    }
+    const rowRange: GridRowCellRange = {
         left: range.left,
         right: range.right,
         isTop: rowIndex === range.top,
         isBottom: rowIndex === range.bottom,
         bottomOffset: hasRowSpan ? range.bottom - rowIndex : 0,
     };
+    if (handleCol !== undefined) rowRange.fillHandleCol = handleCol;
+    return rowRange;
 }
 
 export const isSameRowCellRange = (a: GridRowCellRange | null | undefined, b: GridRowCellRange | null | undefined): boolean =>
     a === b || (!!a && !!b && a.left === b.left && a.right === b.right && a.isTop === b.isTop && a.isBottom === b.isBottom
-        && a.bottomOffset === b.bottomOffset);
+        && a.bottomOffset === b.bottomOffset && a.fillHandleCol === b.fillHandleCol);
 
 /** Bit flags a cell receives for its place in the range (a number keeps memoised cells stable). */
 export const RANGE_CELL = 1;
@@ -211,6 +228,8 @@ export const RANGE_TOP = 2;
 export const RANGE_BOTTOM = 4;
 export const RANGE_LEFT = 8;
 export const RANGE_RIGHT = 16;
+/** The cell carries the fill handle (v3.5). */
+export const RANGE_FILL_HANDLE = 32;
 
 /**
  * The flags of the cell at data column `colIndex` (spanning `colSpan` columns and `rowSpan` rows from
@@ -218,9 +237,10 @@ export const RANGE_RIGHT = 16;
  */
 export function getCellRangeFlags(rowRange: GridRowCellRange | null | undefined, colIndex: number, colSpan: number, rowSpan: number): number {
     if (!rowRange) return 0;
+    const handle = rowRange.fillHandleCol === colIndex ? RANGE_FILL_HANDLE : 0;
     const lastCol = colIndex + Math.max(1, colSpan) - 1;
-    if (colIndex < rowRange.left || lastCol > rowRange.right) return 0;
-    let flags = RANGE_CELL;
+    if (colIndex < rowRange.left || lastCol > rowRange.right) return handle;
+    let flags = RANGE_CELL | handle;
     if (rowRange.isTop) flags |= RANGE_TOP;
     if (rowRange.isBottom || (rowSpan > 1 && rowSpan - 1 >= rowRange.bottomOffset)) flags |= RANGE_BOTTOM;
     if (colIndex === rowRange.left) flags |= RANGE_LEFT;