@opencorestack/opengridx 3.2.2 → 3.4.0

package/dist/index.d.ts

@@ -79,14 +79,35 @@ export declare interface CellProps<R extends GridRowModel = GridRowModel> {
     rowMeta?: GridRowMeta;
     /** The error the column's valueGetter threw for this cell (computed by Row); shown as a cell error. */
     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
+     */
+    rangeFlags?: number;
 }
 
-export declare const Checkbox: default_2.FC<CheckboxProps>;
+/**
+ * The status bar of `showCellSelectionStats`: count of non-empty cells, and the sum and average of
+ * the numeric cells of the selected range. Replace it with `slots.cellSelectionStats`, or wrap it.
+ * @since v3.3
+ */
+export declare function CellSelectionStats({ count, sum, average }: CellSelectionStatsProps): JSX.Element;
+
+export declare type CellSelectionStatsProps = GridCellSelectionStatsSlotProps & Record<string, unknown>;
+
+/**
+ * A styled checkbox: a visually hidden `<input type="checkbox">` inside a `<label>`. Other props
+ * (`onChange`, `onMouseDown`, `tabIndex`, `aria-*`, …) go to the `<input>`, and so does `ref`.
+ */
+export declare const Checkbox: default_2.ForwardRefExoticComponent<CheckboxProps & default_2.RefAttributes<HTMLInputElement>>;
 
 export declare interface CheckboxProps extends Omit<default_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
     indeterminate?: boolean;
     label?: string;
+    /** A ref to the `<input>`; the forwarded `ref` reaches it as well. */
     inputRef?: default_2.Ref<HTMLInputElement>;
+    /** Classes added to the `<input>` itself, next to `ogx-checkbox__input`. `className` goes to the wrapper `<label>`. */
+    inputClassName?: string;
 }
 
 declare type ColumnKey = string;
@@ -164,6 +185,13 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
     rowHeight?: number;
     /** Height of the header row in pixels. Defaults to 56. */
     headerHeight?: number;
+    /**
+     * Wraps header titles onto several lines instead of cutting them with an ellipsis. The header
+     * keeps `headerHeight` (2 lines at the default 56px, 3 at 72px, 4 at 88px); a title that still
+     * does not fit ends in an ellipsis. `GridColDef.wrapHeaderText` overrides it per column.
+     * Defaults to `false`.
+     */
+    wrapHeaderText?: boolean;
     /** If true, the grid height will adjust to match the total height of its rows. */
     autoHeight?: boolean;
     /**
@@ -233,6 +261,55 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
      * the shortcut. `apiRef.current.copySelectedRows()` still works. Default: false.
      */
     disableClipboardCopy?: boolean;
+    /**
+     * Lets users select a rectangle of cells (drag, Shift+click, Shift+arrows, Ctrl/Cmd+A) and copy it
+     * with Ctrl/Cmd+C as tab-separated text. While on, Ctrl/Cmd+C copies the cell range (the focused
+     * cell at minimum) instead of the selected rows; `apiRef.copySelectedRows()` still copies rows.
+     * Default: false. @since v3.3
+     */
+    cellSelection?: boolean;
+    /** Controlled cell selection (zero or one range). Needs `cellSelection`. @since v3.3 */
+    cellSelectionModel?: GridCellSelectionModel;
+    /** Fired when the cell selection changes, with what changed it. @since v3.3 */
+    onCellSelectionModelChange?: (model: GridCellSelectionModel, details: GridCellSelectionChangeDetails) => void;
+    /**
+     * Shows a status bar under the grid with the count of non-empty cells and the sum and average of the
+     * numeric cells in the range, while more than one cell is selected. Replaceable through
+     * `slots.cellSelectionStats`. Needs `cellSelection`. Default: false. @since v3.3
+     */
+    showCellSelectionStats?: boolean;
+    /**
+     * With `cellSelection` on, Ctrl/Cmd+V pastes tab-separated text (Excel, Google Sheets) into the
+     * editable cells from the range's top-left cell (or the focused cell), through `valueSetter` and
+     * `processRowUpdate`. `true` turns the shortcut off; `apiRef.pasteText()` still works. Default: false.
+     * @since v3.4
+     */
+    disableClipboardPaste?: boolean;
+    /**
+     * Fired after every paste with the result (`updated` rows, `failed` rows, `skipped` cells and why)
+     * and the pasted text. @since v3.4
+     */
+    onClipboardPaste?: (result: GridClipboardPasteResult) => void;
+    /**
+     * Called before a paste is applied. Return `false` to cancel it, or a string to paste instead of the
+     * clipboard text. A throw cancels the paste. @since v3.4
+     */
+    onBeforeClipboardPaste?: (params: GridBeforeClipboardPasteParams) => boolean | string;
+    /**
+     * With `cellSelection` on, Delete / Backspace on a range of more than one cell empties its editable
+     * cells (`null`, or `''` in string columns) as one edit. `true` turns that off. Default: false.
+     * @since v3.4
+     */
+    disableRangeClear?: boolean;
+    /**
+     * Undo and redo of cell edits, pastes and range clears: Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z and Ctrl+Y while
+     * focus is in the grid and no editor is open, and `apiRef.undo()` / `redo()`. Undo and redo write
+     * through `valueSetter` and `processRowUpdate`, like an edit. `{ limit }` sets how many actions are
+     * kept (default 100). Default: false. @since v3.4
+     */
+    undoRedo?: boolean | GridUndoRedoOptions;
+    /** Fired when what can be undone or redone changes (`undoRedo`). @since v3.4 */
+    onHistoryChange?: (params: GridHistoryChangeParams) => void;
     /** 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. */
@@ -371,6 +448,11 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
          * Receives `GridFooterSlotProps` (plus `slotProps.footer`).
          */
         footer?: React.ComponentType<GridFooterSlotProps & Record<string, unknown>>;
+        /**
+         * Replaces the status bar of `showCellSelectionStats`. Receives `GridCellSelectionStatsSlotProps`
+         * (plus `slotProps.cellSelectionStats`). @since v3.3
+         */
+        cellSelectionStats?: React.ComponentType<GridCellSelectionStatsSlotProps & Record<string, unknown>>;
     };
     /** Properties passed directly to custom slots. */
     slotProps?: {
@@ -386,6 +468,8 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
         loadingOverlay?: GridOverlaySlotProps;
         /** Merged over the `GridFooterSlotProps` the grid passes to the footer slot. */
         footer?: Partial<GridFooterSlotProps> & Record<string, unknown>;
+        /** Merged over the `GridCellSelectionStatsSlotProps` the grid passes to the status bar. */
+        cellSelectionStats?: Partial<GridCellSelectionStatsSlotProps> & Record<string, unknown>;
     };
     /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
     listView?: boolean;
@@ -688,6 +772,76 @@ export declare interface GridApi<R extends GridValidRowModel = GridRowModel> {
      * 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;
+}
+
+/** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
+export declare interface GridBatchEditResult {
+    /** Rows whose `processRowUpdate` succeeded and that were stored, in the order they were first touched. */
+    updated: GridRowId[];
+    /** Rows whose `valueSetter` or `processRowUpdate` threw or rejected (also reported to `onProcessRowUpdateError`). */
+    failed: {
+        id: GridRowId;
+        error: unknown;
+    }[];
+    /** Cells that were not written, with the reason. */
+    skipped: {
+        id: GridRowId;
+        field: string;
+        reason: GridEditSkipReason;
+    }[];
+}
+
+/** `onBeforeClipboardPaste` params. @since v3.4 */
+export declare interface GridBeforeClipboardPasteParams {
+    /** The clipboard text (`text/plain`). */
+    text: string;
+    /** The cell the paste starts from (the range's top-left cell, or the focused cell). */
+    anchor: GridCellCoordinates | null;
+}
+
+/** One cell, addressed by its row id and column field. @since v3.3 */
+export declare interface GridCellCoordinates {
+    id: GridRowId;
+    field: string;
 }
 
 export declare interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
@@ -699,6 +853,59 @@ export declare interface GridCellParams<R extends GridValidRowModel = GridRowMod
     colIndex: number;
 }
 
+/**
+ * A rectangle of cells between two corners. `anchor` is the active cell: it keeps focus, is the cell
+ * an edit starts in, and stays put while the range is extended. `head` is the corner that moves with
+ * Shift+arrows or the pointer, and the one scrolled into view. A single cell has `anchor` equal to `head`.
+ * @since v3.3
+ */
+export declare interface GridCellRange {
+    anchor: GridCellCoordinates;
+    head: GridCellCoordinates;
+}
+
+/** Second argument of `onCellSelectionModelChange`. @since v3.3 */
+export declare interface GridCellSelectionChangeDetails {
+    reason: GridCellSelectionReason;
+}
+
+/**
+ * The cell selection: zero or one range in 3.3 (the array form leaves room for several ranges later).
+ * Corners are ids and fields, so the rectangle follows its corner rows through sorting and filtering.
+ * @since v3.3
+ */
+export declare type GridCellSelectionModel = readonly GridCellRange[];
+
+/** What changed the cell selection. @since v3.3 */
+export declare type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+
+/**
+ * Props the grid passes to `slots.cellSelectionStats` (the status bar of `showCellSelectionStats`),
+ * before `slotProps.cellSelectionStats` is merged over them. Rendered only while more than one cell
+ * is selected.
+ * @since v3.3
+ */
+export declare interface GridCellSelectionStatsSlotProps {
+    apiRef: React.MutableRefObject<GridApi>;
+    /** Cells in the rectangle (rows × columns), synthetic rows and span-covered positions included. */
+    cellCount: number;
+    rowCount: number;
+    columnCount: number;
+    /** Non-empty cells of data rows. */
+    count: number;
+    /** Cells holding a number. */
+    numericCount: number;
+    /** Sum of the numeric cells, or `null` when there are none. */
+    sum: number | null;
+    /** Average of the numeric cells, or `null` when there are none. */
+    average: number | null;
+}
+
+/** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
+export declare interface GridClipboardPasteResult extends GridBatchEditResult {
+    text: string;
+}
+
 /**
  * Metadata for a single column.
  * Governs rendering, sorting, filtering, and data transformation.
@@ -737,6 +944,12 @@ export declare interface GridColDef<R extends GridValidRowModel = GridRowModel>
     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. */
@@ -765,6 +978,14 @@ export declare interface GridColDef<R extends GridValidRowModel = GridRowModel>
      * @since v3.0
      */
     valueSetter?(params: GridValueSetterParams<R>): R;
+    /**
+     * Turns pasted text into this column's value (clipboard paste), instead of the default parser for
+     * the column `type` (see `docs/features/clipboard.md`). Use it for locales such as `1.234,5` or for
+     * custom codes. Throw (or return `undefined`) to reject the text: the cell is skipped with reason
+     * `'invalidValue'`. The value then goes through `valueSetter` and `processRowUpdate` like an edit.
+     * @since v3.4
+     */
+    valueParser?(text: string, params: GridValueParserParams<R>): unknown;
     /**
      * Custom ascending comparator for client-side sorting by this column, used instead of the built-in
      * type-aware comparison. `v1` / `v2` are the cell values (`valueGetter` applied) and **include
@@ -823,6 +1044,15 @@ export declare interface GridColDef<R extends GridValidRowModel = GridRowModel>
      * @default true
      */
     exportable?: boolean;
+    /**
+     * Example values for this column, put into the schema from `getGridAiSchema`
+     * (`@opencorestack/opengridx/ai`) to help a language model write filters ("Acme" → `customer`).
+     * **These values are sent to the model.** The grid never reads row data for the schema; only what
+     * you list here leaves the app, so list nothing private. Strings, numbers and booleans are used
+     * (at most 10); other values are ignored. Not used by the grid itself.
+     * @since v3.4
+     */
+    aiExamples?: unknown[];
 }
 
 /**
@@ -921,6 +1151,17 @@ export declare interface GridDetailPanelParams<R extends GridValidRowModel = Gri
     rowIndex: number;
 }
 
+/**
+ * Why a cell of a batch edit (paste, range clear, undo, redo) was not written:
+ * - `'notEditable'`: the column is not `editable`, `isCellEditable` returned false, or the row is a
+ *   synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total);
+ * - `'invalidValue'`: the pasted text does not parse for the column type (or `valueParser` rejected it);
+ * - `'changed'`: undo/redo only, the cell no longer holds the value the history recorded;
+ * - `'missing'`: undo/redo only, the row is gone.
+ * @since v3.4
+ */
+export declare type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+
 /** Describes a group of filters combined with a logical operator. */
 export declare interface GridFilterGroup {
     /** Optional ID for the group. */
@@ -1022,6 +1263,14 @@ export declare interface GridGroupedExportRow {
     row?: GridRowModel;
 }
 
+/** `onHistoryChange` params. @since v3.4 */
+export declare interface GridHistoryChangeParams {
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Number of actions that can be undone. */
+    size: number;
+}
+
 /**
  * The state the grid starts from. Every part is optional, including each column field, so a
  * partial state such as `{ columns: { columnVisibilityModel: { age: false } } }` is valid.
@@ -1046,6 +1295,12 @@ export declare interface GridLocaleText {
     paginationPage?: (page: number, pageCount: number) => string;
     /** Empty-state label. When set, overrides the `noRowsLabel` prop on DataGrid. Default: `"No Data"` */
     noRowsLabel?: string;
+    /**
+     * Screen-reader announcement after the cell range changes (`cellSelection`). Receives (cells, rows,
+     * columns). Default: `` (c, r, col) => `${c} cells selected, ${r} rows by ${col} columns` `` (singular for 1).
+     * @since v3.3
+     */
+    cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
 }
 
 /**
@@ -1132,6 +1387,20 @@ export declare interface GridRenderHeaderParams {
     colIndex: number;
 }
 
+/**
+ * The range flags one row passes to its cells, or `null` for a row outside the range. Rows outside
+ * keep `null`, so a drag only re-renders the rows it enters or leaves. `left` / `right` are data
+ * column indices (`columnIndexMap`).
+ */
+declare interface GridRowCellRange {
+    left: number;
+    right: number;
+    isTop: boolean;
+    isBottom: boolean;
+    /** Rows from this one to the bottom of the range; only set (else 0) when the grid has row spans. */
+    bottomOffset: number;
+}
+
 export declare type GridRowGroupingModel = string[];
 
 /** Unique identifier for a row (string or number). */
@@ -1213,6 +1482,14 @@ export declare interface GridRowScrollEndParams {
 
 export declare type GridRowSelectionModel = GridRowId[];
 
+/** One cell of the selected range, as returned by `apiRef.getSelectedCells()`. @since v3.3 */
+export declare interface GridSelectedCell {
+    id: GridRowId;
+    field: string;
+    /** The cell's value, read through the column's `valueGetter`. */
+    value: unknown;
+}
+
 /** The `slotProps` prop of `DataGrid`: props for each slot, keyed like `GridSlots`. */
 export declare type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
 
@@ -1354,6 +1631,10 @@ export declare interface GridThemeGrid {
     rowSelectedBackground?: string;
     rowSelectedHoverBackground?: string;
     cellFocusBorder?: string;
+    /** Tint over a selected cell range (`--ogx-range-background`). Default: the primary colour at 12%. @since v3.3 */
+    rangeBackground?: string;
+    /** Outline of a selected cell range (`--ogx-range-border`). Default: the primary colour. @since v3.3 */
+    rangeBorder?: string;
     pinnedLeftShadow?: string;
     pinnedRightShadow?: string;
     checkboxBg?: string;
@@ -1545,6 +1826,12 @@ export declare interface GridTreeNode {
     serverChildrenCount?: number;
 }
 
+/** `undoRedo` options. @since v3.4 */
+export declare interface GridUndoRedoOptions {
+    /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
+    limit?: number;
+}
+
 /**
  * The constraint on the row type `R` of the generic grid types (`DataGridProps<R>`, `GridColDef<R>`,
  * `GridRenderCellParams<R>` …): any object type. Your own interfaces and type aliases can be used as `R`
@@ -1574,6 +1861,14 @@ export declare interface GridValueGetterParams<R extends GridValidRowModel = Gri
     value: unknown;
 }
 
+/** Parameters passed to `GridColDef.valueParser`. @since v3.4 */
+export declare 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
@@ -1635,15 +1930,30 @@ export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onManageColumns?: () => void;
     /** Position of each visible data column in render order, for `colIndex` and `aria-colindex`. */
     columnIndexMap?: Map<string, number>;
+    /** Wraps header titles onto several lines; `GridColDef.wrapHeaderText` overrides it per column. */
+    wrapHeaderText?: boolean;
+    /** Header row height in pixels; sets how many lines a wrapped title may take. Defaults to 56. */
+    headerHeight?: number;
 }
 
-export declare const Input: default_2.FC<InputProps>;
+/**
+ * A text field: an `<input>` inside an `.ogx-input-wrapper` that holds the adornments.
+ * `ref` reaches the `<input>` (React 18 and 19).
+ */
+export declare const Input: default_2.ForwardRefExoticComponent<InputProps & default_2.RefAttributes<HTMLInputElement>>;
 
 export declare interface InputProps extends default_2.InputHTMLAttributes<HTMLInputElement> {
     fullWidth?: boolean;
     error?: boolean;
     startAdornment?: default_2.ReactNode;
     endAdornment?: default_2.ReactNode;
+    /** Classes added to the `<input>` itself, next to `ogx-input`. `className` goes to the wrapper. */
+    inputClassName?: string;
+    /**
+     * `'field'` (default): a bordered form field. `'cell'`: fills a grid cell with no border,
+     * background or focus ring, in the cell's font, for use in `renderEditCell`.
+     */
+    variant?: 'field' | 'cell';
 }
 
 export declare interface JsonExportOptions<R extends GridValidRowModel = GridRowModel> {
@@ -1835,7 +2145,10 @@ export declare interface PrintOptions<R extends GridValidRowModel = GridRowModel
 
 export declare const roseTheme: GridTheme;
 
-export declare function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>): JSX.Element;
+/** One grid row. Memoised: rows whose props did not change (for example outside a dragged cell range) do not re-render. */
+export declare const Row: typeof RowImpl;
+
+declare function RowImpl<R extends GridRowModel = GridRowModel>(props: RowProps<R>): JSX.Element;
 
 export declare interface RowProps<R extends GridRowModel = GridRowModel> {
     row: R;
@@ -1901,6 +2214,11 @@ export declare interface RowProps<R extends GridRowModel = GridRowModel> {
     columnIndexMap?: Map<string, number>;
     /** 1-based `aria-rowindex` of this row in the whole grid (header rows included). Defaults to `rowIndex + 2`. */
     ariaRowIndex?: number;
+    /**
+     * The part of the selected cell range (`cellSelection`) in this row, or `null` / absent when the
+     * row is outside it. @since v3.3
+     */
+    cellRange?: GridRowCellRange | null;
 }
 
 declare interface RowSpanningCaches {