@opencorestack/opengridx 3.5.1 → 3.7.0

package/lib/theme/types.ts

@@ -90,6 +90,13 @@ export interface GridThemeOverlays {
     itemSelectedText?: string;
     itemDangerBackground?: string;
     itemDangerText?: string;
+
+    /** Font of column menus, header filter menus, toolbar panels and the AI panel (`--ogx-overlay-font-family`). Default: the grid font. @since v3.7 */
+    fontFamily?: string;
+    /** Weight of menu items and panel labels (`--ogx-overlay-font-weight`). Default: each item's own weight (400, labels 500). @since v3.7 */
+    fontWeight?: string;
+    /** Size of menu items and panel labels (`--ogx-overlay-font-size`). Default: `--ogx-font-size-xs` (the AI panel: `--ogx-font-size-sm`). @since v3.7 */
+    fontSize?: string;
 }
 
 export interface GridThemeScrollbar {
@@ -145,8 +152,32 @@ export interface GridThemeGrid {
     cellFontSize?: string;
     /** Font size of header cells (`--ogx-grid-header-font-size`, default 13px). */
     headerFontSize?: string;
+    /** Font of header cells (`--ogx-grid-header-font-family`). Default: the grid font. @since v3.7 */
+    headerFontFamily?: string;
+    /** Weight of header cells (`--ogx-grid-header-font-weight`). Default: `600`. @since v3.7 */
+    headerFontWeight?: string;
+    /** Font of body cells (`--ogx-grid-cell-font-family`). Default: the grid font. @since v3.7 */
+    cellFontFamily?: string;
+    /** Weight of body cells (`--ogx-grid-cell-font-weight`). Default: inherited (400). @since v3.7 */
+    cellFontWeight?: string;
     cellPaddingX?: string;
   cellPaddingY?: string;
+    /** Horizontal padding of header cells (`--ogx-grid-header-padding-x`). Default: `cellPaddingX`. @since v3.7 */
+    headerPaddingX?: string;
+    /** Width of the grid's outer border (`--ogx-grid-border-width`). Default: `1px`. @since v3.7 */
+    borderWidth?: string;
+    /** Corner radius of the grid (`--ogx-grid-border-radius`). Default: `borders.radiusLg` (12px). @since v3.7 */
+    borderRadius?: string;
+    /** Width of the lines between body cells, aggregation footer cells and pinned sections (`--ogx-grid-column-divider-width`). Default: `1px`; `0` hides them. @since v3.7 */
+    columnDividerWidth?: string;
+    /** Width of the short separators between header and column-group cells (`--ogx-grid-header-column-divider-width`). Default: `1px`; `0` hides them. @since v3.7 */
+    headerColumnDividerWidth?: string;
+    /** Width of the lines under rows, the header row, column-group rows and the header filter row (`--ogx-grid-row-divider-width`). Default: `1px`; `0` hides them. @since v3.7 */
+    rowDividerWidth?: string;
+    /** Colour of the column dividers (`--ogx-grid-column-divider-color`). Default: `borderColor`. @since v3.7 */
+    columnDividerColor?: string;
+    /** Colour of the row dividers (`--ogx-grid-row-divider-color`). Default: `borderColor`. @since v3.7 */
+    rowDividerColor?: string;
     background?: string;
   borderColor?: string;
   headerBackground?: string;

package/lib/types/ai.ts

@@ -0,0 +1,109 @@
+import type { GridColumnVisibilityModel } from './columns';
+import type { GridSortItem } from './sorting';
+import type { GridFilterModel } from './filtering';
+import type { GridRowGroupingModel, GridAggregationModel, GridPivotModel } from './grouping';
+
+/** 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/types/api.ts

@@ -0,0 +1,169 @@
+import type { GridRowId, GridRowModel, GridValidRowModel } from './rows';
+import type { GridColDef, GridColumnVisibilityModel } from './columns';
+import type { GridSortDirection, GridSortItem } from './sorting';
+import type { GridFilterModel } from './filtering';
+import type { GridBatchEditResult } from './editing';
+import type { GridGroupedExportRow } from './export';
+import type { GridCellCoordinates, GridCellSelectionModel, GridSelectedCell } from './selection';
+import type { GridRowGroupingModel, GridAggregationModel, GridPivotModel } from './grouping';
+import type { GridAiState } from './ai';
+
+/**
+ * The Imperative API for interacting with the DataGrid.
+ * Access this via the `apiRef` prop or a ref passed to the component.
+ */
+/**
+ * The imperative grid API. `R` types the row getters (`getRow`, `getAllRows`, `getVisibleRows`,
+ * `getAllFilteredRows`); it defaults to `GridRowModel`, so `GridApi` alone keeps working.
+ */
+export interface GridApi<R extends GridValidRowModel = GridRowModel> {
+  /**
+   * Returns the row model with the given ID.
+   * @param id The row unique ID.
+   */
+  getRow: (id: GridRowId) => R | null;
+  /** Returns all rows currently loaded into the grid. */
+  getAllRows: () => R[];
+  /** Returns all rows currently visible after filtering and sorting. */
+  getVisibleRows: () => R[];
+  /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
+  getAllFilteredRows: () => R[];
+  /**
+   * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
+   * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a
+   * grand-total entry at the end. Returns `null` when no `rowGroupingModel` is active.
+   * Pass the result to export functions that accept a `groupedRows` option.
+   */
+  getGroupedExportRows: () => GridGroupedExportRow[] | null;
+  /** Returns the current aggregation results. */
+  getAggregationResult: () => Record<string, unknown> | null;
+  /** Returns the active aggregation configuration. */
+  getAggregationModel: () => GridAggregationModel | null;
+
+  /** Returns the column definition for the given field. */
+  getColumn: (field: string) => GridColDef | null;
+  /** Returns all defined columns. */
+  getAllColumns: () => GridColDef[];
+  /** Returns all columns currently visible. */
+  getVisibleColumns: () => GridColDef[];
+
+  /**
+   * Sets the selection state of a specific row.
+   * @param id The row unique ID.
+   * @param isSelected Visibility state.
+   */
+  selectRow: (id: GridRowId, isSelected?: boolean) => void;
+  /**
+   * Sets the selection state for multiple rows at once.
+   * @param ids Array of row IDs.
+   * @param isSelected Visibility state.
+   */
+  selectRows: (ids: GridRowId[], isSelected?: boolean) => void;
+  /** Returns an array of IDs for all currently selected rows. */
+  getSelectedRows: () => GridRowId[];
+
+  /**
+   * Triggers sorting on a specific column.
+   * @param field The column field.
+   * @param direction Sort order ('asc', 'desc', or null to clear).
+   */
+  sortColumn: (field: string, direction: GridSortDirection) => void;
+  /** Returns the active sorting model. */
+  getSortModel: () => GridSortItem[];
+
+  /** Programmatically sets the filtering model. */
+  setFilterModel: (model: GridFilterModel) => void;
+  /** Returns the current filtering model. */
+  getFilterModel: () => GridFilterModel;
+
+  /** Changes the current page. */
+  setPage: (page: number) => void;
+  /** Changes the current page size. */
+  setPageSize: (pageSize: number) => void;
+
+  /** Scrolls the grid viewport to a specific row or column index. */
+  scrollToIndexes: (params: { rowIndex?: number; colIndex?: number }) => void;
+
+  /**
+   * Sizes a column to fit its header and the cells rendered right now (the virtualization window),
+   * clamped to `minWidth` (default 50px) / `maxWidth`, like double-clicking its resize handle.
+   * Does nothing for `resizable: false` columns or a column that is not rendered.
+   * A flex column gets a fixed width. @since v3.1
+   */
+  autosizeColumn: (field: string) => void;
+  /** `autosizeColumn` for several columns (default: every column). @since v3.1 */
+  autosizeColumns: (fields?: readonly string[]) => void;
+
+  /**
+   * Programmatically copies all currently selected rows to the clipboard as TSV: every selected
+   * row that passes the filter (other pages, collapsed groups and pinned rows included), with the
+   * visible columns in screen order. Equivalent to the user pressing Ctrl+C / Cmd+C.
+   * @returns A Promise that resolves when the text is written (or when no selected row was found,
+   * in which case nothing is written) and rejects when the clipboard write fails.
+   */
+  copySelectedRows: () => Promise<void>;
+
+  /** The cell selection (`[]` when `cellSelection` is off or nothing is selected). @since v3.3 */
+  getCellSelectionModel: () => GridCellSelectionModel;
+  /**
+   * Replaces the cell selection (only the first range is kept) and moves focus to its anchor.
+   * Does nothing while `cellSelection` is off. @since v3.3
+   */
+  setCellSelectionModel: (model: GridCellSelectionModel) => void;
+  /** Selects the rectangle between two cells; `anchor` becomes the active cell. @since v3.3 */
+  selectCellRange: (anchor: GridCellCoordinates, head: GridCellCoordinates) => void;
+  /** Empties the cell selection. Focus stays where it is. @since v3.3 */
+  clearCellSelection: () => void;
+  /**
+   * Cells of the current range in display order (row by row, columns in screen order), values read
+   * through the column's `valueGetter`. Synthetic rows (group headers, subtotals, tree auto-parents, the
+   * pivot Grand Total) and positions covered by a span are left out. @since v3.3
+   */
+  getSelectedCells: () => GridSelectedCell[];
+  /**
+   * Copies the cell range (the focused cell when nothing is selected) as tab-separated text, formatted
+   * the way the cells show it, with no header line. Resolves without writing when there is nothing to
+   * 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.

package/lib/types/columns.ts

@@ -0,0 +1,341 @@
+import type { GridRowModel, GridValidRowModel, GridRowMeta } from './rows';
+import type { GridSortCellParams } from './sorting';
+import type { GridFilterOperator } from './filtering';
+import type { GridFillValueParams } from './editing';
+
+/**
+ * A callback that is checked bivariantly in its parameter, like a method. Used for `GridColDef`
+ * options that are either a value or a function, so a column typed for your rows (`GridColDef<Row>`)
+ * can still be used where an untyped `GridColDef` is expected.
+ */
+type GridColDefCallback<P, T> = { bivarianceHack(params: P): T }['bivarianceHack'];
+
+export type GridAlignment = 'left' | 'center' | 'right';
+
+/**
+ * Metadata for a single column.
+ * Governs rendering, sorting, filtering, and data transformation.
+ */
+export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
+  /** The unique identifier for the column, typically matching a row object key. */
+  field: string;
+  /** Text displayed in the column header. */
+  headerName?: string;
+  /** Tooltip shown on header hover — used as the column's accessibility label. */
+  description?: string;
+  /** If true, this column can be used as a grouping dimension. */
+  groupable?: boolean;
+
+  /**
+   * Custom formatter for the group-header label when this column is used as a grouping field.
+   * Receives the field name and grouped value; return the string to display.
+   * Falls back to `"field: value"` when omitted.
+   */
+  groupingValueFormatter?: (params: { field: string; value: unknown }) => string;
+
+  /** If true, this column can be summarized using aggregation functions. */
+  aggregable?: boolean;
+  /** Restricts which aggregation functions are offered for this column (e.g., ['sum', 'avg']). */
+  availableAggregationFunctions?: string[];
+
+  /** Width in pixels or a percentage string. Defaults to automatic calculation. */
+  width?: number | string;
+  /** Minimum width in pixels. */
+  minWidth?: number;
+  /** Maximum width in pixels. */
+  maxWidth?: number;
+  /** Relative flex weight used when distributing extra space. */
+  flex?: number;
+  /** Content alignment within cells. */
+  align?: GridAlignment;
+  /** Content alignment within the header cell. */
+  headerAlign?: GridAlignment;
+  /**
+   * Wraps this column's header title onto several lines instead of cutting it with an ellipsis.
+   * Overrides the grid's `wrapHeaderText`. The header keeps `headerHeight`: the title shows as many
+   * lines as fit and ends in an ellipsis if it is still longer. Raise `headerHeight` for more lines.
+   */
+  wrapHeaderText?: boolean;
+  /** If false, sorting is disabled for this column. */
+  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. */
+  hideable?: boolean;
+  /** If false, the column cannot be pinned. */
+  pinnable?: boolean;
+  /** Internal: marks this column as a virtual spacer used for horizontal virtualization. */
+  isSpacer?: boolean;
+  /** Type used to determine default operators and formatting logic. */
+  type?: 'string' | 'number' | 'date' | 'boolean' | 'singleSelect' | 'image';
+  /** Options used for 'singleSelect' type. */
+  valueOptions?: Array<string | number | { value: unknown; label: string }>;
+
+  // The row callbacks below are declared as methods so that `GridColDef<Row>` stays assignable to an
+  // untyped `GridColDef` (method parameters are checked bivariantly).
+  /** Function to compute a cell value from raw row data. */
+  valueGetter?(params: GridValueGetterParams<R>): unknown;
+  /**
+   * Maps an edited value back onto the row when an edit is committed; return the updated row.
+   * Needed for editable columns with a `valueGetter`, whose value is not stored in `row[field]`.
+   * Without it the commit writes `row[field] = value`.
+   * @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
+   * `null` / `undefined`**, so the comparator decides where empty values go. The grid reverses the
+   * result for 'desc' and chains it with the other sort keys in a multi-sort. Row grouping uses the
+   * grouping column's comparator to order groups by their grouping value. A comparator that throws
+   * or returns NaN is read as 0 (with a one-time dev warning). Ignored with `sortingMode="server"`.
+   * @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. */
+  renderCell?(params: GridRenderCellParams<R>): React.ReactNode;
+  /** Custom component or element to render in the header. */
+  renderHeader?(params: GridRenderHeaderParams): React.ReactNode;
+  /** Component to render when the cell is in edit mode. Receives `onValueChange`, `onCommit` and `onCancel`. */
+  renderEditCell?(params: GridRenderEditCellParams<R>): React.ReactNode;
+  /** If true, the cell's value can be modified by the user. */
+  editable?: boolean;
+  /** Optional stacking order (CSS z-index). */
+  zIndex?: number;
+  /** If true, the column kebab/hamburger menu is disabled. */
+  disableColumnMenu?: boolean;
+
+  /**
+   * Number of columns this cell should occupy horizontally: the origin plus the next visible columns
+   * in render order, clamped to the end of the origin's pinned section. Fractions are floored,
+   * `Infinity` means "to the end", and NaN / values below 1 mean no span. `params.value` is the
+   * `valueGetter` result. A function that throws is treated as 1.
+   */
+  colSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
+  /**
+   * Number of rows this cell should occupy vertically, clamped to the end of its row section
+   * (top-pinned, scrolling or bottom-pinned rows) and to the first row with an expanded detail
+   * panel. Normalised like `colSpan`. With both set, the origin covers the whole rectangle.
+   */
+  rowSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
+
+  /**
+   * Custom CSS class applied to every cell in this column.
+   * Can be a static string or a function that receives the cell params and returns a string.
+   * Useful for per-row conditional styling without custom renderCell.
+   * @example
+   *   cellClassName: 'my-class'
+   *   cellClassName: ({ value }) => value > 100 ? 'cell--high' : 'cell--low'
+   */
+  cellClassName?: string | GridColDefCallback<GridRenderCellParams<R>, string>;
+
+  /**
+   * Custom CSS class applied to the header cell of this column.
+   * @example
+   *   headerClassName: 'my-header'
+   */
+  headerClassName?: string;
+
+  /**
+   * If false, this column is excluded from all exports (CSV, Excel, JSON, Print).
+   * Useful for action columns with buttons.
+   * @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. */
+export interface GridListViewColDef<R extends GridValidRowModel = GridRowModel> {
+  field: string;
+  renderCell(params: GridRenderCellParams<R>): React.ReactNode;
+}
+
+/**
+ * Describes one level of column grouping.
+ * Groups can be nested by placing child GridColumnGroup objects in `children`.
+ * Leaf groups reference actual column fields via `children: string[]`.
+ *
+ * Example – two levels:
+ * [
+ *   { groupId: 'q1', headerName: 'Q1 2024', children: ['q1Sales', 'q1Target'] },
+ *   { groupId: 'info', headerName: 'Info', children: [
+ *       { groupId: 'personal', headerName: 'Personal', children: ['name', 'age'] }
+ *   ] }
+ * ]
+ */
+export interface GridColumnGroup {
+  /** Unique identifier for this group. */
+  groupId: string;
+  /** Text displayed in the group header cell. */
+  headerName: string;
+  /** CSS class(es) added to this group's header cell(s). */
+  headerClassName?: string;
+  /**
+   * Either an array of column field strings (leaf group)
+   * or an array of child GridColumnGroup objects (nested group).
+   */
+  children: Array<string | GridColumnGroup>;
+}
+
+export type GridColumnGroupingModel = GridColumnGroup[];
+
+/** Parameters passed to the `valueGetter` function. */
+export interface GridValueGetterParams<R extends GridValidRowModel = GridRowModel> {
+  /** The row object. */
+  row: R;
+  /** The field name. */
+  field: string;
+  /** The raw value from the row object. */
+  value: unknown;
+}
+
+/** 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
+ */
+export interface GridValueSetterParams<R extends GridValidRowModel = GridRowModel> {
+  /** The committed value from the editor. */
+  value: unknown;
+  /** The row as it was before the edit. */
+  row: R;
+  /** The field name. */
+  field: string;
+}
+
+/** Parameters passed to the `valueFormatter` function. */
+export interface GridValueFormatterParams<R extends GridValidRowModel = GridRowModel> {
+  /** The raw value to format. */
+  value: unknown;
+  /** The row object. */
+  row: R;
+  /** The field name. */
+  field: string;
+}
+
+/** Parameters passed to the `renderCell` function. */
+export interface GridRenderCellParams<R extends GridValidRowModel = GridRowModel> {
+  /** The current cell value. */
+  value: unknown;
+  /**
+   * The value after `colDef.valueFormatter` (or `String(value)` when no formatter is set; `''` for null/undefined).
+   * @since v2.1
+   */
+  formattedValue?: string;
+  /** The row object. */
+  row: R;
+  /** The field name and unique ID. */
+  field: string;
+  /** The column definition. */
+  colDef: GridColDef<R>;
+  /** The index of the row in the currently visible dataset. */
+  rowIndex: number;
+  /** The index of the column. */
+  colIndex: number;
+  /**
+   * Hierarchy metadata for this row. `undefined` for flat rows (no tree-data or row-grouping active).
+   * @since v1.1
+   */
+  rowMeta?: GridRowMeta;
+}
+
+/**
+ * Parameters passed to `renderEditCell`. `value` is the pending (uncommitted) value.
+ * @since v3.0
+ */
+export interface GridRenderEditCellParams<R extends GridValidRowModel = GridRowModel> extends GridRenderCellParams<R> {
+  /** Updates the pending value. Call it on every change; nothing is saved until `onCommit`. */
+  onValueChange: (value: unknown) => void;
+  /** Commits the pending value (runs `processRowUpdate`) and leaves edit mode. */
+  onCommit: () => void;
+  /** Discards the pending value and leaves edit mode. */
+  onCancel: () => void;
+}
+
+export interface GridRenderHeaderParams {
+  field: string;
+  colDef: GridColDef;
+  colIndex: number;
+}
+
+export type GridPinnedPosition = 'left' | 'right';
+
+export type GridColumnVisibilityModel = Record<string, boolean>;
+
+/** Configuration for pinning columns to the grid edges. */
+export interface GridColumnPinning {
+  /** Field strings to pin to the left edge. */
+  left?: string[];  
+  /** Field strings to pin to the right edge. */
+  right?: string[]; 
+}
+
+export interface GridColumnOrderChangeParams {
+  column: GridColDef;
+  oldIndex: number;
+  targetIndex: number;
+}
+
+export type GridColumnOrder = string[];
+
+export interface GridPinnedColumns {
+  left?: string[];
+  right?: string[];
+}
+
+export interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
+  row: R;
+  field: string;
+  value: unknown;
+  colDef: GridColDef<R>;
+  rowIndex: number;
+  colIndex: number;
+}