@opencorestack/opengridx 3.2.2 → 3.4.0

package/lib/hooks/core/useGridCellSelectionApi.ts

@@ -0,0 +1,97 @@
+import { useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import { isSameCell } from '../../utils/focus';
+import type { FocusedCell } from '../../utils/focus';
+import { isRangeColumnField, isSameCoordinates } from '../../utils/cellSelection';
+import { writeToClipboard } from '../features/useGridClipboard';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+import type { GridApi, GridCellCoordinates, GridCellSelectionModel } from '../../types';
+
+export interface UseGridCellSelectionApiParams {
+    apiRef: MutableRefObject<GridApi>;
+    selection: UseGridCellSelectionReturn;
+    /** The rendered model (controlled or internal). */
+    model: GridCellSelectionModel;
+    getPendingModel: () => GridCellSelectionModel | null;
+    focusedCell: FocusedCell | null;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    /** The grid root: its `ogx--kb` class tells a keyboard focus move from a pointer one. */
+    containerRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Runs after useGridKeyboardNavigation. Keeps the range's anchor and the focused cell together:
+ * a new anchor (pointer, keyboard, API or a controlled model) moves focus there, and focus moved
+ * to another data cell (plain arrows, Tab back in) collapses the range to it. Clears a range whose
+ * corner is no longer displayed (`reason: 'dataChange'`). Installs the cell selection API methods.
+ */
+export function useGridCellSelectionApi(params: UseGridCellSelectionApiParams): void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const previousAnchorRef = useRef<GridCellCoordinates | null>(null);
+    const previousFocusRef = useRef<FocusedCell | null>(null);
+    const reportedDataChangeRef = useRef<GridCellSelectionModel | null>(null);
+
+    const { selection, model, focusedCell, setFocusedCell, containerRef } = params;
+    const anchor = selection.range?.anchor ?? null;
+    const anchorRow = selection.resolved?.anchorRow;
+
+    useLayoutEffect(() => {
+        selection.reportFocus(focusedCell);
+        const anchorChanged = !isSameCoordinates(previousAnchorRef.current, anchor);
+        const focusChanged = !isSameCell(previousFocusRef.current, focusedCell);
+        previousAnchorRef.current = anchor;
+        previousFocusRef.current = focusedCell;
+        if (!selection.enabled) return;
+
+        if (selection.range && !selection.resolved) {
+            // A corner's row or column is no longer displayed. Reported once per model.
+            if (reportedDataChangeRef.current !== model) {
+                reportedDataChangeRef.current = model;
+                selection.setModel([], 'dataChange');
+            }
+            return;
+        }
+        if (anchorChanged && anchor) {
+            if (!focusedCell || focusedCell.id !== anchor.id || focusedCell.field !== anchor.field) {
+                setFocusedCell({ id: anchor.id, field: anchor.field, rowIndex: anchorRow });
+            }
+            return;
+        }
+        if (focusChanged && focusedCell && focusedCell.id !== null && isRangeColumnField(focusedCell.field)
+            && !isSameCoordinates(anchor, { id: focusedCell.id, field: focusedCell.field })) {
+            const cell = { id: focusedCell.id, field: focusedCell.field };
+            const byKeyboard = containerRef.current?.classList.contains('ogx--kb') ?? false;
+            selection.setModel([{ anchor: cell, head: cell }], byKeyboard ? 'keyboard' : 'pointer');
+        }
+    }, [selection, model, anchor, anchorRow, focusedCell, setFocusedCell, containerRef]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        const current = () => latestRef.current;
+        api.getCellSelectionModel = () => {
+            const { selection: s, getPendingModel, model: rendered } = current();
+            return s.enabled ? (getPendingModel() ?? rendered) : [];
+        };
+        api.setCellSelectionModel = (next) => {
+            current().selection.setModel(next, 'api');
+        };
+        api.selectCellRange = (rangeAnchor, head) => {
+            current().selection.setModel([{ anchor: rangeAnchor, head }], 'api');
+        };
+        api.clearCellSelection = () => {
+            current().selection.setModel([], 'clear');
+        };
+        api.getSelectedCells = () => current().selection.getSelectedCells();
+        api.copySelectedCells = async () => {
+            const { selection: s } = current();
+            if (!s.enabled) return;
+            const text = s.getCopyText();
+            if (text !== null) await writeToClipboard(text);
+        };
+    }, [apiRef]);
+}

package/lib/hooks/core/useGridClipboardApi.ts

@@ -11,15 +11,20 @@ export interface UseGridClipboardApiParams {
     /** The grid root: Ctrl/Cmd+C only copies while focus is inside it. */
     containerRef: RefObject<HTMLDivElement | null>;
     disableKeyboardShortcut: boolean;
+    /**
+     * Cell range selection: the text Ctrl/Cmd+C copies instead of the selected rows (`null`: nothing).
+     * Absent while `cellSelection` is off, so the shortcut copies rows.
+     */
+    getCellRangeCopyText?: () => string | null;
 }
 
 /**
  * Copies the selected rows (every page, collapsed groups, pinned rows) with the on-screen columns
  * in screen order, on Ctrl/Cmd+C while focus is inside this grid, and installs `copySelectedRows`
- * on the API for programmatic use.
+ * on the API for programmatic use. With `cellSelection` on, the shortcut copies the cell range instead.
  */
 export function useGridClipboardApi(params: UseGridClipboardApiParams): void {
-    const { apiRef, columns, getRowId, containerRef, disableKeyboardShortcut } = params;
+    const { apiRef, columns, getRowId, containerRef, disableKeyboardShortcut, getCellRangeCopyText } = params;
 
     const getGridRootElement = useCallback(() => containerRef.current, [containerRef]);
     const { copySelectedRows } = useGridClipboard({
@@ -29,6 +34,7 @@ export function useGridClipboardApi(params: UseGridClipboardApiParams): void {
         getRowId,
         getRootElement: getGridRootElement,
         disableKeyboardShortcut,
+        getShortcutText: getCellRangeCopyText,
     });
 
     // Stable identity.

package/lib/hooks/core/useGridClipboardPaste.ts

@@ -0,0 +1,283 @@
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import type {
+    GridApi,
+    GridBatchEditResult,
+    GridBeforeClipboardPasteParams,
+    GridCellCoordinates,
+    GridCellParams,
+    GridClipboardPasteResult,
+    GridColDef,
+    GridEditSkipReason,
+    GridRowId,
+    GridRowMeta,
+    GridRowModel,
+} from '../../types';
+import { attempt } from '../../utils/attempt';
+import { classifyKeyTarget } from '../../utils/focus';
+import type { FocusedCell } from '../../utils/focus';
+import { isRangeColumnField, rectCellCount } from '../../utils/cellSelection';
+import type { CellRangeRect } from '../../utils/cellSelection';
+import { parseCellText, parseTsv } from '../../utils/parsing';
+import { getCellValue, warnCallbackFailure } from '../../utils/values';
+import {
+    buildEditTargetContext,
+    isEditTargetWritable,
+    isTextColumn,
+    rectCorners,
+} from '../../utils/editing/targets';
+import type { GridEditTargetContext } from '../../utils/editing/targets';
+import type { GridBatchCellEdit, UseGridBatchEditReturn } from '../features/useGridBatchEdit';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+
+/** Above this many cells a paste warns in development. */
+export const LARGE_PASTE_CELLS = 10_000;
+
+const emptyResult = (): GridBatchEditResult => ({ updated: [], failed: [], skipped: [] });
+
+export interface UseGridClipboardPasteParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    /** The grid root: paste and Delete are listened for here. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    selection: UseGridCellSelectionReturn;
+    disableClipboardPaste: boolean;
+    disableRangeClear: boolean;
+    focusedCell: FocusedCell | null;
+    allRenderableRows: R[];
+    getRowId: (row: R) => GridRowId;
+    /** System columns and the rendered data columns, in render order. */
+    navigationColumns: ReadonlyArray<GridColDef<R>>;
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
+    rowMetaMap: Map<GridRowId, GridRowMeta>;
+    getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    /** Whether a cell editor is open: paste and Delete then belong to it. */
+    isEditing: boolean;
+    batchEdit: UseGridBatchEditReturn<R>;
+    onClipboardPaste?: (result: GridClipboardPasteResult) => void;
+    onBeforeClipboardPaste?: (params: GridBeforeClipboardPasteParams) => boolean | string;
+}
+
+function warnLargePaste(cellCount: number): void {
+    if (process.env.NODE_ENV === 'production') return;
+    console.warn(`[OpenGridX] Pasting ${cellCount} cells. Pastes above ${LARGE_PASTE_CELLS} cells can be slow; consider importing the data instead.`);
+}
+
+/**
+ * Clipboard paste and range clear (v3.4). With `cellSelection` on: Ctrl/Cmd+V (the `paste` event,
+ * so no clipboard permission is needed) writes tab-separated text into the editable cells, and
+ * Delete / Backspace on a multi-cell range empties them. Both are one batch edit (`useGridBatchEdit`),
+ * so one undo. Installs `apiRef.pasteText`. Runs after useGridCellSelectionApi.
+ */
+export function useGridClipboardPaste<R extends GridRowModel>(params: UseGridClipboardPasteParams<R>): void {
+    const { apiRef, containerRef, selection, disableClipboardPaste, disableRangeClear } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const getContext = useCallback((): GridEditTargetContext<R> => {
+        const { allRenderableRows, getRowId, navigationColumns } = latestRef.current;
+        return buildEditTargetContext(allRenderableRows, getRowId, navigationColumns);
+    }, []);
+
+    /** The range's rectangle (display indices), or null. */
+    const currentRect = useCallback((): CellRangeRect | null => {
+        const { selection: s } = latestRef.current;
+        if (!s.enabled) return null;
+        return s.getCurrentRange().resolved;
+    }, []);
+
+    /** The cell a paste starts from: the range's top-left cell, else the focused data cell. */
+    const defaultAnchor = useCallback((ctx: GridEditTargetContext<R>): GridCellCoordinates | null => {
+        const rect = currentRect();
+        if (rect && ctx.rowIds[rect.top] !== undefined && ctx.columns[rect.left]) {
+            return { id: ctx.rowIds[rect.top], field: ctx.columns[rect.left].field };
+        }
+        const focus = latestRef.current.focusedCell;
+        if (focus && focus.id !== null && isRangeColumnField(focus.field)) return { id: focus.id, field: focus.field };
+        return null;
+    }, [currentRect]);
+
+    const paste = useCallback(async (clipboardText: string, anchorOverride: GridCellCoordinates | undefined, viaKeyboard: boolean): Promise<GridBatchEditResult> => {
+        const ctx = getContext();
+        const anchor = anchorOverride ?? defaultAnchor(ctx);
+        let text = clipboardText;
+        const { onBeforeClipboardPaste } = latestRef.current;
+        if (onBeforeClipboardPaste) {
+            const verdict = attempt(() => onBeforeClipboardPaste({ text, anchor }));
+            if (!verdict.ok) {
+                warnCallbackFailure('onBeforeClipboardPaste', 'onBeforeClipboardPaste threw; the paste was cancelled', verdict.error);
+                return emptyResult();
+            }
+            if (verdict.value === false) return emptyResult();
+            if (typeof verdict.value === 'string') text = verdict.value;
+        }
+        if (!anchor) return emptyResult();
+        const block = parseTsv(text);
+        const anchorRow = ctx.rowIndexById.get(anchor.id);
+        const anchorCol = ctx.colIndexByField.get(anchor.field);
+        if (block.length === 0 || anchorRow === undefined || anchorCol === undefined) return emptyResult();
+
+        const lastRow = ctx.rowIds.length - 1;
+        const lastCol = ctx.columns.length - 1;
+        // A range of several cells bounds the paste; one value fills all of it.
+        const range = anchorOverride ? null : currentRect();
+        const multiCellRange = range && rectCellCount(range) > 1 ? range : null;
+        const singleValue = block.length === 1 && block[0].length === 1;
+        const blockWidth = block.reduce((max, line) => Math.max(max, line.length), 0);
+        let rect: CellRangeRect;
+        if (singleValue && multiCellRange) {
+            rect = multiCellRange;
+        } else {
+            rect = {
+                top: anchorRow,
+                left: anchorCol,
+                bottom: Math.min(anchorRow + block.length - 1, lastRow, multiCellRange ? multiCellRange.bottom : lastRow),
+                right: Math.min(anchorCol + blockWidth - 1, lastCol, multiCellRange ? multiCellRange.right : lastCol),
+            };
+        }
+        const cellCount = rectCellCount(rect);
+        if (cellCount > LARGE_PASTE_CELLS) warnLargePaste(cellCount);
+
+        const { batchEdit, isCellEditable, rowMetaMap, getSpanOrigin } = latestRef.current;
+        const rules = { isCellEditable, rowMetaMap, getSpanOrigin };
+        const edits: GridBatchCellEdit[] = [];
+        const skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[] = [];
+        for (let r = rect.top; r <= rect.bottom; r++) {
+            const id = ctx.rowIds[r];
+            const row = batchEdit.getRow(id) ?? ctx.rows[r];
+            const line = singleValue ? block[0] : block[r - rect.top];
+            for (let c = rect.left; c <= rect.right; c++) {
+                const cellText = singleValue ? block[0][0] : line?.[c - rect.left];
+                if (cellText === undefined) continue;
+                const colDef = ctx.columns[c];
+                if (!isEditTargetWritable(ctx, rules, row, r, c)) {
+                    skipped.push({ id, field: colDef.field, reason: 'notEditable' });
+                    continue;
+                }
+                const parsed = parseCellText(cellText, colDef, row, { current: getCellValue(row, colDef.field, colDef) });
+                if (!parsed.ok) {
+                    skipped.push({ id, field: colDef.field, reason: 'invalidValue' });
+                    continue;
+                }
+                edits.push({ id, field: colDef.field, value: parsed.value });
+            }
+        }
+
+        // The pasted area becomes the selection, so one look shows what changed.
+        if (latestRef.current.selection.enabled) {
+            const { anchor: from, head: to } = rectCorners(ctx, rect);
+            latestRef.current.selection.setModel([{ anchor: from, head: to }], viaKeyboard ? 'keyboard' : 'api');
+        }
+
+        const outcome = await batchEdit.applyEdits(edits, 'paste');
+        const result: GridBatchEditResult = {
+            updated: outcome.result.updated,
+            failed: outcome.result.failed,
+            skipped: [...skipped, ...outcome.result.skipped],
+        };
+        latestRef.current.onClipboardPaste?.({ ...result, text });
+        return result;
+    }, [getContext, defaultAnchor, currentRect]);
+
+    /** Delete / Backspace: empties the editable cells of a multi-cell range. Returns whether it applied. */
+    const clearRange = useCallback((): boolean => {
+        const rect = currentRect();
+        if (!rect || rectCellCount(rect) <= 1) return false;
+        const ctx = getContext();
+        const { batchEdit, isCellEditable, rowMetaMap, getSpanOrigin } = latestRef.current;
+        const rules = { isCellEditable, rowMetaMap, getSpanOrigin };
+        const edits: GridBatchCellEdit[] = [];
+        for (let r = rect.top; r <= rect.bottom; r++) {
+            const id = ctx.rowIds[r];
+            if (id === undefined) continue;
+            const row = batchEdit.getRow(id) ?? ctx.rows[r];
+            for (let c = rect.left; c <= rect.right; c++) {
+                const colDef = ctx.columns[c];
+                if (!colDef || !isEditTargetWritable(ctx, rules, row, r, c)) continue;
+                edits.push({ id, field: colDef.field, value: isTextColumn(colDef) ? '' : null });
+            }
+        }
+        void batchEdit.applyEdits(edits, 'clear');
+        return true;
+    }, [currentRect, getContext]);
+
+    const pasteEnabled = selection.enabled && !disableClipboardPaste;
+    const clearEnabled = selection.enabled && !disableRangeClear;
+
+    useEffect(() => {
+        const root = containerRef.current;
+        if (!root || (!pasteEnabled && !clearEnabled)) return;
+        /** Only events aimed at this grid's cells (not an editor, a text field or a nested grid). */
+        const ownsTarget = (event: Event) => {
+            const viewport = latestRef.current.viewportRef.current;
+            if (!viewport || event.defaultPrevented || latestRef.current.isEditing) return false;
+            const kind = classifyKeyTarget(event.target, viewport);
+            return kind === 'grid' || kind === 'control';
+        };
+        // Some engines (WebKit on Linux) only fire `paste` on an editable element, never on a focused
+        // cell. On the paste shortcut, focus moves to an off-screen textarea for that one event, so the
+        // browser's paste lands there and bubbles to the root; focus then goes back to the cell.
+        let capture: { textarea: HTMLTextAreaElement; restore: HTMLElement | null; timer: number } | null = null;
+        const endCapture = () => {
+            if (!capture) return;
+            const { textarea, restore, timer } = capture;
+            capture = null;
+            window.clearTimeout(timer);
+            const hadFocus = document.activeElement === textarea;
+            textarea.remove();
+            if (hadFocus && restore && restore.isConnected) restore.focus({ preventScroll: true });
+        };
+        const startCapture = () => {
+            endCapture();
+            const textarea = document.createElement('textarea');
+            textarea.setAttribute('aria-hidden', 'true');
+            textarea.tabIndex = -1;
+            textarea.className = 'ogx__paste-capture';
+            textarea.style.cssText = 'position:fixed;top:0;left:-10000px;width:1px;height:1px;opacity:0;';
+            root.appendChild(textarea);
+            const restore = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+            // No paste event within the timeout (an empty or non-text clipboard): give focus back anyway.
+            capture = { textarea, restore, timer: window.setTimeout(endCapture, 250) };
+            textarea.focus({ preventScroll: true });
+        };
+        const isCaptureTarget = (event: Event) => capture !== null && event.target === capture.textarea;
+        const onPaste = (event: ClipboardEvent) => {
+            if (isCaptureTarget(event)) {
+                const text = event.clipboardData ? event.clipboardData.getData('text/plain') : '';
+                event.preventDefault();
+                endCapture();
+                if (text !== '') void paste(text, undefined, true);
+                return;
+            }
+            if (!pasteEnabled || !ownsTarget(event)) return;
+            if (!latestRef.current.navigationColumns.some(c => c.editable)) return;
+            const text = event.clipboardData ? event.clipboardData.getData('text/plain') : '';
+            if (text === '') return;
+            event.preventDefault();
+            void paste(text, undefined, true);
+        };
+        const onKeyDown = (event: KeyboardEvent) => {
+            if ((event.ctrlKey || event.metaKey) && !event.altKey && !event.shiftKey && (event.key === 'v' || event.key === 'V' || event.code === 'KeyV')) {
+                if (pasteEnabled && ownsTarget(event) && latestRef.current.navigationColumns.some(c => c.editable)) startCapture();
+                return;
+            }
+            if (!clearEnabled || (event.key !== 'Delete' && event.key !== 'Backspace')) return;
+            if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+            if (!ownsTarget(event)) return;
+            if (clearRange()) event.preventDefault();
+        };
+        root.addEventListener('paste', onPaste);
+        root.addEventListener('keydown', onKeyDown);
+        return () => {
+            endCapture();
+            root.removeEventListener('paste', onPaste);
+            root.removeEventListener('keydown', onKeyDown);
+        };
+    }, [containerRef, pasteEnabled, clearEnabled, paste, clearRange]);
+
+    useLayoutEffect(() => {
+        apiRef.current.pasteText = (text, anchor) => paste(text, anchor, false);
+    }, [apiRef, paste]);
+}

package/lib/hooks/core/useGridControlledState.ts

@@ -7,6 +7,9 @@ import type {
     GridPaginationModel,
     GridAggregationModel,
     GridPivotModel,
+    GridCellSelectionModel,
+    GridCellSelectionChangeDetails,
+    GridCellSelectionReason,
 } from '../../types';
 import type { GridInitialState, GridDensityState } from '../../state/types';
 
@@ -42,6 +45,9 @@ export interface UseGridControlledStateParams {
     onRowSelectionModelChange?: (model: GridRowId[]) => void;
 
     density?: GridDensity;
+
+    cellSelectionModel?: GridCellSelectionModel;
+    onCellSelectionModelChange?: (model: GridCellSelectionModel, details: GridCellSelectionChangeDetails) => void;
 }
 
 export interface UseGridControlledStateReturn {
@@ -94,8 +100,17 @@ export interface UseGridControlledStateReturn {
 
     // density (prop, else initialState.density, else 'standard')
     density: GridDensity;
+
+    // cell selection
+    cellSelectionModel: GridCellSelectionModel;
+    /** Sets the internal model when uncontrolled and fires onCellSelectionModelChange. */
+    handleCellSelectionModelChange: (model: GridCellSelectionModel, reason: GridCellSelectionReason) => void;
+    /** Like `getPendingRowSelectionModel`, for the cell selection. Stable identity. */
+    getPendingCellSelectionModel: () => GridCellSelectionModel | null;
 }
 
+const EMPTY_CELL_SELECTION_MODEL: GridCellSelectionModel = [];
+
 const EMPTY_PIVOT_MODEL: GridPivotModel = { rowFields: [], columnFields: [], valueFields: [] };
 const DEFAULT_PAGE_SIZE = 100;
 
@@ -128,6 +143,8 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange,
         density: propDensity,
+        cellSelectionModel: propCellSelectionModel,
+        onCellSelectionModelChange,
     } = params;
 
     // ── Sort ─────────────────────────────────────────────────────────────────
@@ -248,6 +265,23 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     const [initialDensity] = useState<GridDensity>(() => initialState?.density?.density ?? 'standard');
     const density = propDensity ?? initialDensity;
 
+    // ── Cell selection ───────────────────────────────────────────────────────
+    const isCellSelectionControlled = propCellSelectionModel !== undefined;
+    const [internalCellSelectionModel, setInternalCellSelectionModel] = useState<GridCellSelectionModel>(EMPTY_CELL_SELECTION_MODEL);
+    const cellSelectionModel = isCellSelectionControlled ? propCellSelectionModel : internalCellSelectionModel;
+
+    const pendingCellSelectionRef = useRef<GridCellSelectionModel | null>(null);
+    useLayoutEffect(() => {
+        pendingCellSelectionRef.current = null;
+    });
+    const getPendingCellSelectionModel = useCallback(() => pendingCellSelectionRef.current, []);
+
+    const handleCellSelectionModelChange = useCallback((model: GridCellSelectionModel, reason: GridCellSelectionReason) => {
+        pendingCellSelectionRef.current = model;
+        if (!isCellSelectionControlled) setInternalCellSelectionModel(model);
+        onCellSelectionModelChange?.(model, { reason });
+    }, [isCellSelectionControlled, onCellSelectionModelChange]);
+
     return {
         sortModel: sortModel as GridSortItem[],
         isSortControlled,
@@ -281,5 +315,9 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         getPendingRowSelectionModel,
 
         density,
+
+        cellSelectionModel,
+        handleCellSelectionModelChange,
+        getPendingCellSelectionModel,
     };
 }

package/lib/hooks/core/useGridKeyboardNavigation.ts

@@ -14,6 +14,7 @@ import {
     isSystemField,
 } from '../../utils/focus';
 import type { FocusedCell } from '../../utils/focus';
+import { isRangeColumnField } from '../../utils/cellSelection';
 import type { GridRowModel, GridRowId, GridColDef, GridCellParams, GridSortItem, GridSortDirection, GridRowParams, GridRowMeta } from '../../types';
 import type { GridEditingState } from '../features/useGridEditing';
 
@@ -93,6 +94,21 @@ export interface UseGridKeyboardNavigationParams<R extends GridRowModel> {
      * Navigation skips the cells of the focused span and lands on span origins.
      */
     getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    /**
+     * Cell range selection (`cellSelection`), absent while it is off. Shift+navigation keys on a
+     * data cell move the range's head (focus stays on the anchor), Escape collapses the range and
+     * Ctrl/Cmd+A selects every data cell instead of every row.
+     */
+    cellSelection?: GridKeyboardCellSelection;
+}
+
+export interface GridKeyboardCellSelection {
+    /** Returns whether the key was used. */
+    extendSelection: (key: string, withModifier: boolean, pageSize: number, from: FocusedCell) => boolean;
+    /** Returns whether a multi-cell range was collapsed. */
+    collapseSelection: () => boolean;
+    /** Returns whether anything was selected. */
+    selectAllCells: () => boolean;
 }
 
 export interface UseGridKeyboardNavigationReturn {
@@ -170,6 +186,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         pinExpandColumn = true,
         rowHeight,
         getSpanOrigin,
+        cellSelection,
     } = params;
 
     const [storedFocus, setFocusedCell] = useState<FocusedCell | null>(null);
@@ -419,11 +436,19 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
 
         // Tab is not captured outside edit mode: the grid is a single tab stop and Tab leaves it
         // (or reaches focusable content inside cells and detail panels).
+        if (key === 'Escape' && cellSelection?.collapseSelection()) {
+            event.preventDefault();
+            return;
+        }
         if (key === 'Tab' || key === 'Escape') return;
         // Enter and Space activate a control rendered inside a cell.
         if (targetKind === 'control' && (key === 'Enter' || isSpace)) return;
 
         if ((event.ctrlKey || event.metaKey) && (key === 'a' || key === 'A')) {
+            if (cellSelection) {
+                if (cellSelection.selectAllCells()) event.preventDefault();
+                return;
+            }
             if (!rowSelectionEnabled || !multipleRowSelectionEnabled || !handleSelectAll) return;
             event.preventDefault();
             handleSelectAll(true);
@@ -496,6 +521,12 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         const withModifier = event.ctrlKey || event.metaKey;
         const page = pagination ? pageSize : 10;
 
+        // Shift+navigation on a data cell extends the cell range; focus stays on its anchor.
+        if (cellSelection && event.shiftKey && id !== null && isRangeColumnField(field)
+            && cellSelection.extendSelection(key, withModifier, page, focusedCell)) {
+            return;
+        }
+
         const step = (r: number, c: number): { r: number; c: number } => {
             switch (key) {
                 case 'ArrowRight': return c + 1 > lastCol ? { r: r + 1, c: 0 } : { r, c: c + 1 };
@@ -558,6 +589,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         scrollCellIntoView,
         getSpanOrigin,
         getRowId,
+        cellSelection,
     ]);
 
     return {

package/lib/hooks/core/useGridRowInteractions.ts

@@ -51,6 +51,10 @@ export function useGridRowInteractions<R extends GridRowModel>(
         selectableRowIds,
     });
 
+    // Depend on the selection callbacks, not the object around them (a new one each render), so the
+    // handlers keep their identity and memoised rows do not re-render.
+    const { clickRow, toggleRow } = rowSelection;
+
     const handleRowClick = useCallback((rowParams: GridRowParams<R>) => {
         const { id } = rowParams;
 
@@ -66,16 +70,16 @@ export function useGridRowInteractions<R extends GridRowModel>(
 
         // The pivot Grand Total is clickable (onRowClick) but, like any synthetic row, not selectable.
         if (!disableRowSelectionOnClick && !isSyntheticRowId(id, rowMetaMap)) {
-            rowSelection.clickRow(id);
+            clickRow(id);
         }
-    }, [isHierarchyEnabled, activeHierarchyHandlers, onRowClick, rowMetaMap, disableRowSelectionOnClick, rowSelection]);
+    }, [isHierarchyEnabled, activeHierarchyHandlers, onRowClick, rowMetaMap, disableRowSelectionOnClick, clickRow]);
 
     // Honors disableMultipleRowSelection like a row click does. Synthetic group / subtotal rows
     // and the pivot Grand Total are not data: their ids never enter the selection model.
     const handleSelectionChange = useCallback((rowId: GridRowId, isSelected: boolean) => {
         if (isSyntheticRowId(rowId, rowMetaMap)) return;
-        rowSelection.toggleRow(rowId, isSelected);
-    }, [rowMetaMap, rowSelection]);
+        toggleRow(rowId, isSelected);
+    }, [rowMetaMap, toggleRow]);
 
     return { rowSelection, handleRowClick, handleSelectionChange };
 }