@opencorestack/opengridx 3.2.2 → 3.4.0

package/lib/hooks/features/useGridEditing.ts

@@ -1,5 +1,15 @@
 import { useState, useCallback, useRef, useEffect, useLayoutEffect, useMemo } from 'react';
 import type { GridColDef, GridRowId, GridRowModel } from '../../types';
+import { attempt } from '../../utils/attempt';
+import { getCellValue } from '../../utils/values';
+import {
+    buildEditedRow,
+    invalidProcessedRowError,
+    isPromiseLike,
+    isSameValue,
+    reportEditError,
+} from '../../utils/editing/commit';
+import type { GridCellChange } from '../../utils/editing/commit';
 
 export interface GridEditingState {
     editingCell: {
@@ -22,6 +32,12 @@ export interface UseGridEditingParams<R extends GridRowModel> {
      * grid resolved with getRowId), not on a field of the returned row.
      */
     onRowChange?: (newRow: R, id: GridRowId) => void;
+    /**
+     * Receives the cell change once `processRowUpdate` succeeded and the row was stored (undo/redo
+     * history): the value before and the stored value, both read through `getCellValue`. Not called
+     * when the stored value equals the previous one.
+     */
+    onCommitted?: (changes: GridCellChange[]) => void;
 }
 
 export interface StopCellEditParams {
@@ -45,18 +61,6 @@ interface PendingCommit {
 
 const RESOLVED: Promise<void> = Promise.resolve();
 
-/** A misuse of the editing contract (e.g. processRowUpdate returned nothing), as opposed to a consumer rejection. */
-class OpenGridXEditError extends Error {}
-
-function isSameValue(a: unknown, b: unknown): boolean {
-    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
-    return Object.is(a, b);
-}
-
-function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
-    return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';
-}
-
 /**
  * Cell edit sessions and their commits.
  *
@@ -95,6 +99,10 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         setEditingCellState(next);
     }, []);
 
+    // The in-flight branch below re-runs the commit through this ref: a callback that refers to
+    // itself is read before its declaration, which React Compiler rejects.
+    const commitRef = useRef<((token: number, cell: EditingCell) => Promise<void>) | null>(null);
+
     const commit = useCallback((token: number, cell: EditingCell): Promise<void> => {
         const inFlight = pendingRef.current.get(token);
         if (inFlight) {
@@ -103,7 +111,7 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             return inFlight.promise.then(() => {
                 const now = editingCellRef.current;
                 if (sessionRef.current !== token || !now || isSameValue(now.value, inFlight.value)) return;
-                return commit(token, now);
+                return commitRef.current?.(token, now);
             });
         }
 
@@ -121,24 +129,21 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             return RESOLVED;
         }
 
-        const report = (error: unknown) => {
-            const onError = latestRef.current.onProcessRowUpdateError;
-            if (onError) {
-                onError(error);
-            } else if (process.env.NODE_ENV !== 'production' && error instanceof OpenGridXEditError) {
-                console.error(error.message);
-            }
-        };
+        const report = (error: unknown) => reportEditError(error, latestRef.current.onProcessRowUpdateError);
+        const colDef = columns?.find(c => c.field === cell.field);
 
         const apply = (processed: unknown) => {
             if (typeof processed !== 'object' || processed === null) {
-                report(new OpenGridXEditError(
-                    `[OpenGridX] processRowUpdate must return the updated row object (or a Promise of it); ` +
-                    `it returned ${processed === null ? 'null' : typeof processed}. The edit was not saved and the editor stays open.`
-                ));
+                report(invalidProcessedRowError(processed, 'The edit was not saved and the editor stays open.'));
                 return;
             }
             latestRef.current.onRowChange?.(processed as R, cell.id);
+            const { onCommitted } = latestRef.current;
+            if (onCommitted) {
+                const before = getCellValue(existingRow, cell.field, colDef);
+                const after = getCellValue(processed as R, cell.field, colDef);
+                if (!isSameValue(before, after)) onCommitted([{ id: cell.id, field: cell.field, before, after }]);
+            }
             const now = editingCellRef.current;
             if (sessionRef.current !== token || !now) return;
             if (isSameValue(now.value, cell.value)) {
@@ -159,18 +164,18 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             if (pendingRef.current.get(token) === entry) pendingRef.current.delete(token);
         };
 
-        let result: unknown;
-        try {
-            const colDef = columns?.find(c => c.field === cell.field);
+        const outcome = attempt<unknown>(() => {
             const newRow = buildEditedRow(existingRow, cell, colDef, warnedFieldsRef.current);
-            result = processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
-        } catch (error) {
+            return processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
+        });
+        if (!outcome.ok) {
             // Consumer code (valueSetter / processRowUpdate) threw: report it, keep the editor open.
             finish();
-            report(error);
+            report(outcome.error);
             settle();
             return promise;
         }
+        const result = outcome.value;
 
         const complete = (processed: unknown) => {
             finish();
@@ -194,6 +199,9 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         }
         return promise;
     }, [setEditingCell]);
+    useLayoutEffect(() => {
+        commitRef.current = commit;
+    }, [commit]);
 
     const startCellEdit = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
         const current = editingCellRef.current;
@@ -237,23 +245,3 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         setEditCellValue
     }), [editingCell, startCellEdit, stopCellEdit, setEditCellValue]);
 }
-
-function buildEditedRow<R extends GridRowModel>(
-    row: R,
-    cell: EditingCell,
-    colDef: GridColDef<R> | undefined,
-    warnedFields: Set<string>
-): R {
-    if (colDef?.valueSetter) {
-        return colDef.valueSetter({ value: cell.value, row, field: cell.field });
-    }
-    if (colDef?.valueGetter && process.env.NODE_ENV !== 'production' && !warnedFields.has(cell.field)) {
-        warnedFields.add(cell.field);
-        console.warn(
-            `[OpenGridX] Column "${cell.field}" is editable and has a valueGetter but no valueSetter. ` +
-            `The edited value was written to row["${cell.field}"], which the valueGetter may ignore, so the cell ` +
-            'can keep showing the old value. Add a valueSetter that maps the value back onto the row.'
-        );
-    }
-    return { ...row, [cell.field]: cell.value };
-}

package/lib/index.ts

@@ -21,6 +21,8 @@ export type { GridToolbarProps, ToolbarButtonRenderProps, ToolbarQuickFilterRend
 export { GridTooltip } from './components/Tooltip/Tooltip';
 export type { GridTooltipProps } from './components/Tooltip/Tooltip';
 export { ColumnVisibilityPanel } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
+export { CellSelectionStats } from './components/CellSelectionStats/CellSelectionStats';
+export type { CellSelectionStatsProps } from './components/CellSelectionStats/CellSelectionStats';
 export type { ColumnVisibilityPanelProps } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
 
 export { useGridApiRef } from './hooks/core/useGridApiRef';
@@ -91,6 +93,7 @@ export type {
     GridValueGetterParams,
     GridSortCellParams,
     GridValueSetterParams,
+    GridValueParserParams,
     GridValueFormatterParams,
     GridRowParams,
     GridCellParams,
@@ -99,6 +102,19 @@ export type {
     GridPinnedPosition,
     GridColumnVisibilityModel,
     GridRowSelectionModel,
+    GridCellCoordinates,
+    GridCellRange,
+    GridCellSelectionModel,
+    GridCellSelectionReason,
+    GridCellSelectionChangeDetails,
+    GridSelectedCell,
+    GridCellSelectionStatsSlotProps,
+    GridEditSkipReason,
+    GridBatchEditResult,
+    GridClipboardPasteResult,
+    GridBeforeClipboardPasteParams,
+    GridHistoryChangeParams,
+    GridUndoRedoOptions,
     GridColumnOrder,
     GridColumnOrderChangeParams,
     GridRowOrderChangeParams,

package/lib/styles/base/variables.css

@@ -93,7 +93,10 @@
   --ogx-grid-row-selected-background: var(--ogx-color-primary-light);
   --ogx-grid-row-selected-hover-background: #dbeafe; 
   --ogx-grid-cell-focus-border: var(--ogx-color-primary);
-  --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.05); 
+  /* Cell range selection (cellSelection, v3.3): tint over the range and its outline. */
+  --ogx-range-background: rgba(59, 130, 246, 0.12);
+  --ogx-range-border: var(--ogx-color-primary);
+  --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.05);
   --ogx-grid-pinned-right-shadow: -4px 0 24px -4px rgba(0, 0, 0, 0.05);
   --ogx-skeleton-base: #f0f0f0;
   --ogx-skeleton-highlight: #f8f8f8;
@@ -142,6 +145,8 @@
     --ogx-grid-row-selected-background: #1e3a5f;
     --ogx-grid-row-selected-hover-background: #1d4ed8;
     --ogx-grid-cell-focus-border: #60a5fa;
+    --ogx-range-background: rgba(96, 165, 250, 0.18);
+    --ogx-range-border: #60a5fa;
     --ogx-checkbox-bg: #1e293b;
     --ogx-checkbox-border: #64748b;
     --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.3);

package/lib/styles/opengridx.css

@@ -1,5 +1,7 @@
 @import './base/variables.css';
 @import './base/reset.css';
+/* Shared primitives first, so component styles that restyle them win on equal specificity. */
+@import '../components/ui/Input.css';
 @import '../components/DataGrid/DataGrid.css';
 @import '../components/Header/Header.css';
 @import '../components/Row/Row.css';
@@ -16,7 +18,6 @@
 @import '../components/ui/Checkbox.css';
 @import '../components/ui/DragHandleIcon.css';
 @import '../components/ui/ExpandIcon.css';
-@import '../components/ui/Input.css';
 @import '../components/Toolbar/GridToolbar.css';
 @import '../components/Toolbar/PivotPanel.css';
 @import '../components/FilterPanel/FilterPanel.css';
@@ -25,3 +26,4 @@
 @import '../components/ListView/ListView.css';
 @import '../components/ColumnGroupHeader/ColumnGroupHeader.css';
 @import '../components/Tooltip/Tooltip.css';
+@import '../components/CellSelectionStats/CellSelectionStats.css';

package/lib/theme/DataGridThemeProvider.tsx

@@ -9,6 +9,8 @@ const primaryDerived: Record<string, string> = {
     '--ogx-grid-row-selected-background': 'var(--ogx-color-primary-light)',
     '--ogx-grid-row-selected-hover-background': 'color-mix(in srgb, var(--ogx-color-primary) 14%, var(--ogx-color-primary-light))',
     '--ogx-grid-cell-focus-border': 'var(--ogx-color-primary)',
+    '--ogx-range-background': 'color-mix(in srgb, var(--ogx-color-primary) 12%, transparent)',
+    '--ogx-range-border': 'var(--ogx-color-primary)',
     '--ogx-toolbar-btn-primary-bg': 'var(--ogx-color-primary)',
     '--ogx-toolbar-btn-primary-hover': 'var(--ogx-color-primary-dark)',
     '--ogx-toolbar-input-focus-border': 'var(--ogx-color-primary)',
@@ -281,6 +283,8 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-row-selected-background', g.rowSelectedBackground);
         set('--ogx-grid-row-selected-hover-background', g.rowSelectedHoverBackground);
         set('--ogx-grid-cell-focus-border', g.cellFocusBorder);
+        set('--ogx-range-background', g.rangeBackground);
+        set('--ogx-range-border', g.rangeBorder);
         set('--ogx-grid-pinned-left-shadow', g.pinnedLeftShadow);
         set('--ogx-grid-pinned-right-shadow', g.pinnedRightShadow);
         set('--ogx-checkbox-bg', g.checkboxBg);

package/lib/theme/presets.ts

@@ -21,6 +21,8 @@ export const darkTheme: GridTheme = {
     rowSelectedBackground: '#1e3a5f',  
     rowSelectedHoverBackground: '#1d4ed8', 
     cellFocusBorder: '#60a5fa',
+    rangeBackground: 'rgba(96, 165, 250, 0.18)',
+    rangeBorder: '#60a5fa',
     checkboxBg: '#1e293b',            
     checkboxBorder: '#64748b',         
   },
@@ -92,6 +94,8 @@ export const roseTheme: GridTheme = {
     rowSelectedBackground: '#ffe4e6',
     rowSelectedHoverBackground: '#fecdd3',
     cellFocusBorder: '#e11d48',
+    rangeBackground: 'rgba(225, 29, 72, 0.10)',
+    rangeBorder: '#e11d48',
   },
 };
 
@@ -110,6 +114,8 @@ export const emeraldTheme: GridTheme = {
     rowSelectedBackground: '#d1fae5',
     rowSelectedHoverBackground: '#a7f3d0',
     cellFocusBorder: '#059669',
+    rangeBackground: 'rgba(5, 150, 105, 0.12)',
+    rangeBorder: '#059669',
   },
 };
 
@@ -128,6 +134,8 @@ export const amberTheme: GridTheme = {
     rowSelectedBackground: '#fef3c7',
     rowSelectedHoverBackground: '#fde68a',
     cellFocusBorder: '#d97706',
+    rangeBackground: 'rgba(217, 119, 6, 0.12)',
+    rangeBorder: '#d97706',
   },
 };
 

package/lib/theme/types.ts

@@ -159,6 +159,10 @@ export 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;

package/lib/types/index.ts

@@ -144,6 +144,12 @@ export 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. */
@@ -172,6 +178,14 @@ export 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
@@ -234,6 +248,16 @@ export 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[];
 }
 
 /** Column definition used exclusively in List View mode. */
@@ -294,6 +318,14 @@ export interface GridValueGetterParams<R extends GridValidRowModel = GridRowMode
   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
@@ -658,6 +690,68 @@ export interface GridPaginationModel {
 
 export type GridRowSelectionModel = GridRowId[];
 
+/** One cell, addressed by its row id and column field. @since v3.3 */
+export interface GridCellCoordinates {
+  id: GridRowId;
+  field: string;
+}
+
+/**
+ * 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 interface GridCellRange {
+  anchor: GridCellCoordinates;
+  head: GridCellCoordinates;
+}
+
+/**
+ * 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 type GridCellSelectionModel = readonly GridCellRange[];
+
+/** What changed the cell selection. @since v3.3 */
+export type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+
+/** Second argument of `onCellSelectionModelChange`. @since v3.3 */
+export interface GridCellSelectionChangeDetails {
+  reason: GridCellSelectionReason;
+}
+
+/** One cell of the selected range, as returned by `apiRef.getSelectedCells()`. @since v3.3 */
+export interface GridSelectedCell {
+  id: GridRowId;
+  field: string;
+  /** The cell's value, read through the column's `valueGetter`. */
+  value: unknown;
+}
+
+/**
+ * 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 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;
+}
+
 export interface GridPinnedColumns {
   left?: string[];
   right?: string[];
@@ -735,6 +829,54 @@ export interface GridRowScrollEndParams {
   viewportHeight: 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 type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+
+/** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
+export 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 }[];
+}
+
+/** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
+export interface GridClipboardPasteResult extends GridBatchEditResult {
+  text: string;
+}
+
+/** `onBeforeClipboardPaste` params. @since v3.4 */
+export 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;
+}
+
+/** `onHistoryChange` params. @since v3.4 */
+export interface GridHistoryChangeParams {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Number of actions that can be undone. */
+  size: number;
+}
+
+/** `undoRedo` options. @since v3.4 */
+export interface GridUndoRedoOptions {
+  /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
+  limit?: number;
+}
+
 /** Overrideable user-visible strings for internationalisation. All fields are optional; defaults match the built-in English strings. */
 export interface GridLocaleText {
     /** Label before the rows-per-page select. Default: `"Rows per page:"` */
@@ -745,6 +887,12 @@ export 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;
 }
 
 /**
@@ -763,6 +911,13 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   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;
   /**
@@ -840,6 +995,57 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    */
   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. */
@@ -992,6 +1198,11 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
      * 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?: {
@@ -1007,6 +1218,8 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
     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. */
@@ -1198,4 +1411,45 @@ export 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;
 }

package/lib/utils/attempt.ts

@@ -0,0 +1,14 @@
+export type AttemptResult<T> = { ok: true; value: T } | { ok: false; error: unknown };
+
+/**
+ * Calls `fn` and contains a throw. Components and hooks use it instead of an inline `try` / `catch`
+ * around expressions with `?.`, `??`, `||` or `? :`: React Compiler cannot compile a function that has
+ * those inside a `try` statement yet and skips the whole component or hook.
+ */
+export function attempt<T>(fn: () => T): AttemptResult<T> {
+    try {
+        return { ok: true, value: fn() };
+    } catch (error) {
+        return { ok: false, error };
+    }
+}