@opencorestack/opengridx 3.4.0 → 3.5.1

package/dist/index.d.ts

@@ -81,7 +81,8 @@ export declare interface CellProps<R extends GridRowModel = GridRowModel> {
     valueError?: unknown;
     /**
      * Place of the cell in the selected cell range (`cellSelection`), as bit flags: in range 1, top
-     * edge 2, bottom 4, left 8, right 16. 0 or absent: not in a range. @since v3.3
+     * edge 2, bottom 4, left 8, right 16; 32 draws the fill handle (v3.5). 0 or absent: not in a range.
+     * @since v3.3
      */
     rangeFlags?: number;
 }
@@ -192,6 +193,18 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
      * 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;
     /**
@@ -310,6 +323,16 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
     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. */
@@ -393,8 +416,13 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
     groupingColDef?: Partial<GridColDef<R>>;
     /** 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. */
@@ -453,6 +481,8 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
          * (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?: {
@@ -470,6 +500,8 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
         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. */
     listView?: boolean;
@@ -480,6 +512,17 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
      * 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;
 }
 
 export declare function DataGridThemeProvider({ theme, children, className, style }: DataGridThemeProviderProps): JSX.Element;
@@ -681,6 +724,111 @@ export declare type GridAggregationPosition = 'inline' | 'footer' | null;
 
 export declare type GridAggregationResult = Record<string, unknown>;
 
+/** The `aiAssistant` prop: the "Ask AI" prompt panel. @since v3.5 */
+declare 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[];
+}
+
+/** Props of `slots.aiAssistantPanel` and the built-in panel, rendered while the panel is open. @since v3.5 */
+declare 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;
+}
+
+/** The assistant panel's state. @since v3.5 */
+declare type GridAiAssistantStatus = 'idle' | 'running' | 'applied' | 'stopped' | 'error';
+
+/** One change the assistant applied, shown as a removable chip. @since v3.5 */
+declare interface GridAiChip {
+    id: string;
+    part: GridAiPart;
+    label: string;
+}
+
+/** One earlier prompt of this session and the state the assistant applied for it. @since v3.5 */
+declare interface GridAiHistoryEntry {
+    prompt: string;
+    applied: GridAiState;
+}
+
+/** A part of the grid state a model may change. @since v3.4 */
+declare type GridAiPart = 'filter' | 'sort' | 'grouping' | 'aggregation' | 'pivot' | 'columnVisibility';
+
+/** What `aiAssistant.onPrompt` receives next to the prompt. @since v3.5 */
+declare 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
+ */
+declare interface GridAiPromptResult {
+    state: GridAiState;
+    /** What the validator dropped; shown as "Ignored: …". */
+    errors: GridAiValidationError[];
+    /** The assistant's reply text, shown in the panel. */
+    message?: string;
+}
+
+/** Grid state as the AI toolkit reads and writes it. Only the parts present are applied. @since v3.4 */
+declare 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 */
+declare interface GridAiValidationError {
+    path: string;
+    message: string;
+}
+
 export declare type GridAlignment = 'left' | 'center' | 'right';
 
 /**
@@ -811,6 +959,25 @@ export declare 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;
 }
 
 /** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
@@ -954,6 +1121,18 @@ export declare 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. */
@@ -996,6 +1175,13 @@ export declare 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. */
@@ -1162,6 +1348,32 @@ export declare interface GridDetailPanelParams<R extends GridValidRowModel = Gri
  */
 export declare type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
 
+/** The way a fill extends the cell range. @since v3.5 */
+export declare type GridFillDirection = 'down' | 'up' | 'right' | 'left';
+
+/** `onFill` details: the batch edit result plus the direction of the fill. @since v3.5 */
+export declare interface GridFillResult extends GridBatchEditResult {
+    direction: GridFillDirection;
+}
+
+/** Parameters passed to `GridColDef.fillValue`. @since v3.5 */
+export declare 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;
+}
+
 /** Describes a group of filters combined with a logical operator. */
 export declare interface GridFilterGroup {
     /** Optional ID for the group. */
@@ -1301,6 +1513,8 @@ export declare 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;
 }
 
 /**
@@ -1399,6 +1613,8 @@ declare 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;
 }
 
 export declare type GridRowGroupingModel = string[];
@@ -1635,6 +1851,8 @@ export declare 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;
@@ -1722,7 +1940,7 @@ export declare interface GridThemeTypography {
     fontSizeXl?: string;
 }
 
-export declare function GridToolbar({ columns, baseColumns, aggregationModel, onAggregationModelChange, pivotModel, onPivotModelChange, filterModel, onFilterModelChange, columnVisibilityModel, onColumnVisibilityModelChange, onColumnReorder, onColumnOrderReset, forceColumnsOpen, onColumnsPanelClose, children, rightContent, style, renderColumnsButton, renderFilterButton, renderAggregationButton, renderExportButton, renderQuickFilter, className, showNonHideableColumns, }: GridToolbarProps): JSX.Element;
+export declare function GridToolbar({ columns, baseColumns, aggregationModel, onAggregationModelChange, pivotModel, onPivotModelChange, filterModel, onFilterModelChange, columnVisibilityModel, onColumnVisibilityModelChange, onColumnReorder, onColumnOrderReset, forceColumnsOpen, onColumnsPanelClose, forceFiltersOpen, onFiltersPanelClose, children, rightContent, style, renderColumnsButton, renderFilterButton, renderAggregationButton, renderExportButton, renderQuickFilter, className, showNonHideableColumns, onAiAssistantToggle, aiAssistantOpen, aiAssistantLabel, }: GridToolbarProps): JSX.Element;
 
 export declare interface GridToolbarProps {
     columns?: GridColDef[];
@@ -1743,6 +1961,10 @@ export declare interface GridToolbarProps {
     onColumnOrderReset?: () => void;
     forceColumnsOpen?: boolean;
     onColumnsPanelClose?: () => void;
+    /** Opens the filter panel when it turns true (the grid passes it for the header filter row). @since v3.5 */
+    forceFiltersOpen?: boolean;
+    /** Called whenever the filter panel closes. @since v3.5 */
+    onFiltersPanelClose?: () => void;
     children?: default_2.ReactNode;
     rightContent?: default_2.ReactNode;
     style?: default_2.CSSProperties;
@@ -1775,6 +1997,16 @@ export declare interface GridToolbarProps {
     className?: string;
     /** Show columns with `hideable: false` in the Columns panel as disabled rows. Default: false. */
     showNonHideableColumns?: boolean;
+    /**
+     * Opens or closes the `aiAssistant` panel. The grid passes it when `aiAssistant` is set; the
+     * **Ask AI** button is shown only with it. Receives the button, which gets focus back on close.
+     * @since v3.5
+     */
+    onAiAssistantToggle?: (trigger: HTMLElement | null) => void;
+    /** Whether the `aiAssistant` panel is open. @since v3.5 */
+    aiAssistantOpen?: boolean;
+    /** Label of the Ask AI button (`localeText.aiAssistantButton`). Default: `"Ask AI"`. @since v3.5 */
+    aiAssistantLabel?: string;
 }
 
 /**
@@ -1917,10 +2149,14 @@ export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onDragOver?: (field: string) => (event: default_2.DragEvent) => void;
     onDragEnd?: () => void;
     onDrop?: (targetField: string) => (event: default_2.DragEvent) => void;
-    /** The grid's focus position; `id: null` means a header cell is focused. */
+    /**
+     * The grid's focus position; `id: null` means a header cell is focused, and `headerFilter: true`
+     * a cell of the header filter row.
+     */
     focusedCell?: {
         id: string | number | null;
         field: string;
+        headerFilter?: boolean;
     } | null;
     onHeaderClick?: (field: string) => void;
     onSortAdd?: (field: string, direction: GridSortDirection) => void;
@@ -1934,6 +2170,14 @@ export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     wrapHeaderText?: boolean;
     /** Header row height in pixels; sets how many lines a wrapped title may take. Defaults to 56. */
     headerHeight?: number;
+    /** Renders the header filter row under the column headers (`DataGridProps.headerFilters`). */
+    headerFilters?: boolean;
+    /** The filter model the header filter row reads. */
+    filterModel?: GridFilterModel;
+    /** Receives the filter model after a header filter changes. */
+    onFilterModelChange?: (model: GridFilterModel) => void;
+    /** Opens the filter panel; a header filter cell showing "Custom filter" calls it. */
+    onOpenFilterPanel?: () => void;
 }
 
 /**