@opencorestack/opengridx 3.3.0 → 3.4.0

package/lib/components/Toolbar/GlobalSearch.tsx

@@ -1,4 +1,5 @@
 import React, { useState, useEffect, useRef, useCallback, useLayoutEffect } from 'react';
+import { Input } from '../ui/Input';
 
 
 interface GlobalSearchProps {
@@ -143,9 +144,9 @@ export function GlobalSearch({ value = '', onChange, placeholder = 'Search...',
             <div className="ogx-global-search__icon-wrapper">
                 <SearchIcon />
             </div>
-            <input
+            <Input
                 ref={inputRef}
-                className="ogx-global-search__input"
+                inputClassName="ogx-global-search__input"
                 value={localValue}
                 onChange={(e) => setLocalValue(e.target.value)}
                 onFocus={handleFocus}

package/lib/components/ui/Checkbox.tsx

@@ -4,7 +4,10 @@ import React from 'react';
 export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
     indeterminate?: boolean;
     label?: string;
+    /** A ref to the `<input>`; the forwarded `ref` reaches it as well. */
     inputRef?: React.Ref<HTMLInputElement>;
+    /** Classes added to the `<input>` itself, next to `ogx-checkbox__input`. `className` goes to the wrapper `<label>`. */
+    inputClassName?: string;
 }
 
 /** Points a callback or object ref at `element`. Outside the component, so it does not mutate a prop in render scope. */
@@ -16,13 +19,18 @@ function assignRef(ref: React.Ref<HTMLInputElement> | undefined, element: HTMLIn
     }
 }
 
-export const Checkbox: React.FC<CheckboxProps> = ({
+/**
+ * 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 const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox({
     indeterminate = false,
     label,
     className = '',
+    inputClassName = '',
     inputRef,
     ...props
-}) => {
+}, forwardedRef) {
     const internalRef = React.useRef<HTMLInputElement>(null);
 
     // Combine refs
@@ -30,7 +38,8 @@ export const Checkbox: React.FC<CheckboxProps> = ({
         internalRef.current = element;
 
         assignRef(inputRef, element);
-    }, [inputRef]);
+        assignRef(forwardedRef, element);
+    }, [inputRef, forwardedRef]);
 
     React.useEffect(() => {
         if (internalRef.current) {
@@ -51,7 +60,7 @@ export const Checkbox: React.FC<CheckboxProps> = ({
             <input
                 ref={setRef}
                 type="checkbox"
-                className="ogx-checkbox__input"
+                className={['ogx-checkbox__input', inputClassName].filter(Boolean).join(' ')}
                 {...props}
             />
             <span className="ogx-checkbox__box">
@@ -69,4 +78,6 @@ export const Checkbox: React.FC<CheckboxProps> = ({
             {label && <span className="ogx-checkbox__label">{label}</span>}
         </label>
     );
-};
+});
+
+Checkbox.displayName = 'Checkbox';

package/lib/components/ui/Input.css

@@ -57,3 +57,46 @@
 .ogx-input-wrapper--disabled .ogx-input {
   cursor: not-allowed;
 }
+
+/* ── Cell variant: an editor that fills a grid cell ───────────────────── */
+.ogx-input-wrapper--cell {
+  /* Not positioned: the editing cell's focus outline must stay painted over the editor. */
+  position: static;
+  display: flex;
+  width: 100%;
+  height: 100%;
+  border: none;
+  border-radius: 0;
+  background: transparent;
+  box-shadow: none;
+  transition: none;
+}
+.ogx-input-wrapper--cell:hover:not(.ogx-input-wrapper--disabled),
+.ogx-input-wrapper--cell:focus-within:not(.ogx-input-wrapper--disabled) {
+  box-shadow: none;
+}
+.ogx-input-wrapper--cell .ogx-input {
+  width: 100%;
+  min-width: 0;
+  height: 100%;
+  padding: 0 10px;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: normal;
+  color: inherit;
+}
+.ogx-input-wrapper--cell .ogx-input__adornment--start {
+  padding-left: 10px;
+}
+.ogx-input-wrapper--cell .ogx-input__adornment--start + .ogx-input {
+  padding-left: 4px;
+}
+.ogx-input-wrapper--cell .ogx-input__adornment--end {
+  padding-right: 10px;
+}
+.ogx-input-wrapper--cell.ogx-input-wrapper--error,
+.ogx-input-wrapper--cell.ogx-input-wrapper--error:focus-within:not(.ogx-input-wrapper--disabled) {
+  /* Positioned, so the error edge is painted over the cell's focus outline. */
+  position: relative;
+  box-shadow: inset 0 0 0 2px var(--ogx-color-error);
+}

package/lib/components/ui/Input.tsx

@@ -1,4 +1,3 @@
-
 import React from 'react';
 
 export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
@@ -6,24 +5,40 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
     error?: boolean;
     startAdornment?: React.ReactNode;
     endAdornment?: React.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 const Input: React.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 const Input = React.forwardRef<HTMLInputElement, InputProps>(function Input({
     fullWidth = false,
     error = false,
     startAdornment,
     endAdornment,
     className = '',
+    inputClassName = '',
+    variant = 'field',
     ...props
-}) => {
+}, ref) {
     const wrapperClassNames = [
         'ogx-input-wrapper',
+        variant === 'cell' && 'ogx-input-wrapper--cell',
         fullWidth && 'ogx-input-wrapper--full-width',
         error && 'ogx-input-wrapper--error',
         props.disabled && 'ogx-input-wrapper--disabled',
         className
     ].filter(Boolean).join(' ');
 
+    const inputClassNames = ['ogx-input', inputClassName].filter(Boolean).join(' ');
+
     return (
         <div className={wrapperClassNames}>
             {startAdornment && (
@@ -32,7 +47,9 @@ export const Input: React.FC<InputProps> = ({
                 </div>
             )}
             <input
-                className="ogx-input"
+                ref={ref}
+                className={inputClassNames}
+                aria-invalid={error ? true : undefined}
                 {...props}
             />
             {endAdornment && (
@@ -42,4 +59,6 @@ export const Input: React.FC<InputProps> = ({
             )}
         </div>
     );
-};
+});
+
+Input.displayName = 'Input';

package/lib/hooks/core/gridApiPlaceholder.ts

@@ -1,6 +1,7 @@
-import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
+import type { GridApi, GridBatchEditResult, GridRowModel, GridValidRowModel } from '../../types';
 
 const noop = () => {};
+const emptyEditResult = (): Promise<GridBatchEditResult> => Promise.resolve({ updated: [], failed: [], skipped: [] });
 
 /**
  * A complete GridApi whose methods are safe no-ops. `useGridApiRef()` starts with one so
@@ -38,5 +39,11 @@ export function createGridApiPlaceholder<R extends GridValidRowModel = GridRowMo
         clearCellSelection: noop,
         getSelectedCells: () => [],
         copySelectedCells: () => Promise.resolve(),
+        pasteText: emptyEditResult,
+        undo: emptyEditResult,
+        redo: emptyEditResult,
+        canUndo: () => false,
+        canRedo: () => false,
+        clearHistory: noop,
     };
 }

package/lib/hooks/core/useDataGrid.ts

@@ -18,6 +18,7 @@ type GetRowId = (row: GridRowModel) => GridRowId;
 type GridAction =
   | { type: 'SET_ROWS'; payload: GridRowModel[] | ((prev: GridRowModel[]) => GridRowModel[]); getRowId: GetRowId }
   | { type: 'REPLACE_ROW'; id: GridRowId; row: GridRowModel }
+  | { type: 'REPLACE_ROWS'; rows: ReadonlyMap<GridRowId, GridRowModel> }
   | { type: 'SET_COLUMNS'; payload: GridColDef[] }
   | { type: 'SET_DIMENSIONS'; payload: { viewportWidth: number; viewportHeight: number } }
   | { type: 'SET_DATASOURCE_LOADING'; payload: boolean }
@@ -134,6 +135,26 @@ function gridReducer(state: GridState, action: GridAction): GridState {
       };
     }
 
+    case 'REPLACE_ROWS': {
+      // A batch edit (paste, range clear, undo, redo): every stored row in one update.
+      let changed = false;
+      const idRowsLookup = new Map(state.rows.idRowsLookup);
+      const idByRow = new Map(state.rows.idByRow);
+      for (const [id, row] of action.rows) {
+        const previous = idRowsLookup.get(id);
+        if (previous === undefined) continue;
+        changed = true;
+        idRowsLookup.set(id, row);
+        idByRow.delete(previous);
+        idByRow.set(row, id);
+      }
+      if (!changed) return state;
+      return {
+        ...state,
+        rows: { ...state.rows, idRowsLookup, idByRow },
+      };
+    }
+
     case 'SET_COLUMNS': {
       const columnLookup = new Map<string, GridColDef>();
       const orderedFields: string[] = [];
@@ -270,6 +291,11 @@ export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDa
     dispatch({ type: 'REPLACE_ROW', id, row });
   }, []);
 
+  /** Replaces several stored rows in one update (a batch edit); ids no longer stored are ignored. */
+  const replaceRows = useCallback((rowsById: ReadonlyMap<GridRowId, GridRowModel>) => {
+    if (rowsById.size > 0) dispatch({ type: 'REPLACE_ROWS', rows: rowsById });
+  }, []);
+
   const setColumns = useCallback((newColumns: GridColDef[]) => {
     dispatch({ type: 'SET_COLUMNS', payload: newColumns });
   }, []);
@@ -307,6 +333,7 @@ export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDa
     apiRef,
     setRows,
     replaceRow,
+    replaceRows,
     setColumns,
     setDimensions,
     setDataSourceLoading,

package/lib/hooks/core/useGridCellSelection.ts

@@ -116,6 +116,11 @@ export interface UseGridCellSelectionReturn {
     reportFocus: (cell: FocusedCell | null) => void;
     /** Sets the model, keeping only the first range, unless it is unchanged. */
     setModel: (model: GridCellSelectionModel, reason: GridCellSelectionReason) => void;
+    /**
+     * The current range (a pending model included) and where it lies, read at call time. Its indices
+     * address the renderable rows and the range columns of `navigationColumns` (`isRangeColumnField`).
+     */
+    getCurrentRange: () => { range: GridCellSelectionModel[number] | null; resolved: ResolvedCellRange | null };
 }
 
 interface DragState {
@@ -392,6 +397,21 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         return field === undefined ? null : { id, field };
     }, []);
 
+    /** The row whose band holds `centerY` (px from the top of the unpinned rows), with `field`. */
+    const headRowAtOffset = useCallback((centerY: number, field: string): GridCellCoordinates | null => {
+        const { context: ctx, layout, pinnedTopRowCount } = latestRef.current;
+        const heights = layout.cumulativeHeights;
+        if (!ctx || heights.length === 0 || centerY < 0) return null;
+        let lo = 0;
+        let hi = heights.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (heights[mid] > centerY) hi = mid; else lo = mid + 1;
+        }
+        const id = ctx.rowIds[lo + pinnedTopRowCount];
+        return id === undefined ? null : { id, field };
+    }, []);
+
     // The auto-scroll loop schedules the next frame through this ref: a callback cannot name itself.
     const runDragFrameRef = useRef<(allowScroll: boolean) => void>(() => {});
     const runDragFrame = useCallback((allowScroll: boolean) => {
@@ -416,7 +436,14 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         const x = clamp(drag.x, box.left + 1, box.left + width - 2);
         let y = drag.y;
         if (y < box.top || y > box.top + height || y < headerBottom) y = clamp(y, bodyTop + 1, Math.max(bodyTop + 1, bodyBottom - 2));
-        const head = headAtPoint(viewport, x, y);
+        // During fast auto-scroll the rows under the pointer may not be rendered yet (virtualization
+        // lags a frame or more on a slow machine), so the hit test finds no cell. Work out the row from
+        // the scroll position and the row heights instead, keeping the column the head already has.
+        const canHitTest = typeof viewport.ownerDocument.elementFromPoint === 'function';
+        const hit = headAtPoint(viewport, x, y);
+        const head = hit ?? (canHitTest && drag.moved
+            ? headRowAtOffset(y - box.top - (stickyTop ? stickyTop.getBoundingClientRect().height : 0) + viewport.scrollTop, drag.head.field)
+            : null);
         if (head && !isSameCoordinates(head, drag.head)) {
             drag.head = head;
             if (!drag.moved && !isSameCoordinates(head, drag.anchor)) {
@@ -443,7 +470,7 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         if (canScrollX) viewport.scrollLeft += dx;
         // Keep going while the pointer rests in the edge zone; the next frame picks the new head.
         drag.frame = requestAnimationFrame(() => runDragFrameRef.current(true));
-    }, [headAtPoint, setRange]);
+    }, [headAtPoint, headRowAtOffset, setRange]);
     useLayoutEffect(() => {
         runDragFrameRef.current = runDragFrame;
     }, [runDragFrame]);
@@ -598,6 +625,7 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         stats,
         reportFocus,
         setModel,
+        getCurrentRange: currentRange,
     };
 }
 

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]);
+}