@opencorestack/opengridx 3.3.0 → 3.5.0

package/lib/hooks/core/useGridCellSelection.ts

@@ -116,6 +116,13 @@ 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 };
+    /** Starts a tracked pointer drag with the range drag's auto-scroll (fill handle). Stable. @since v3.5 */
+    startTrackedDrag: (options: GridTrackedDragOptions) => void;
 }
 
 interface DragState {
@@ -125,7 +132,24 @@ interface DragState {
     y: number;
     frame: number;
     moved: boolean;
-    stop: () => void;
+    /** Ends the drag; `cancelled` unless the button was released normally (tracked drags: Escape cancels). */
+    stop: (cancelled?: boolean, altKey?: boolean) => void;
+    /** A tracked drag (fill handle): told the cell under the pointer each frame instead of moving the range. */
+    onTrack?: (head: GridCellCoordinates, x: number, y: number) => void;
+}
+
+/** A drag that reuses the range drag's hit testing and auto-scroll without selecting (the fill handle, v3.5). */
+export interface GridTrackedDragOptions {
+    /** The cell the drag starts on. */
+    start: GridCellCoordinates;
+    x: number;
+    y: number;
+    /** Pointer events of this pointer are followed (touch included), not mouse events. */
+    pointerId: number;
+    /** Each frame: the cell under the pointer (or nearest it) and the pointer position. */
+    onTrack: (head: GridCellCoordinates, x: number, y: number) => void;
+    /** Once: released (`cancelled: false`, with the Alt key state) or cancelled. */
+    onEnd: (details: { cancelled: boolean; altKey: boolean }) => void;
 }
 
 /** The body cell of `viewport` holding `target`: its row index and field. Not cells of nested grids or detail panels. */
@@ -392,6 +416,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 +455,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)) {
@@ -424,8 +470,10 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
                 latestRef.current.containerRef.current?.classList.add(RANGE_DRAGGING_CLASS);
                 clearTextSelection(viewport.ownerDocument);
             }
-            setRange(drag.anchor, head, 'pointer');
+            if (!drag.onTrack) setRange(drag.anchor, head, 'pointer');
         }
+        // A tracked drag hears every frame: its target can change while the head stays in one cell.
+        if (drag.onTrack) drag.onTrack(drag.head, drag.x, drag.y);
 
         if (!allowScroll) return;
         const outside = drag.y < bodyTop || drag.y > bodyBottom || drag.x < box.left || drag.x > box.left + width;
@@ -443,16 +491,27 @@ 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]);
 
-    const startDrag = useCallback((anchor: GridCellCoordinates, head: GridCellCoordinates, x: number, y: number, doc: Document) => {
+    const startDrag = useCallback((
+        anchor: GridCellCoordinates,
+        head: GridCellCoordinates,
+        x: number,
+        y: number,
+        doc: Document,
+        tracked?: Pick<GridTrackedDragOptions, 'pointerId' | 'onTrack' | 'onEnd'>,
+    ) => {
         dragRef.current?.stop();
+        // A range drag follows the mouse; a tracked drag (fill handle) follows its pointer, touch included.
+        const moveType = tracked ? 'pointermove' : 'mousemove';
+        const upType = tracked ? 'pointerup' : 'mouseup';
+        const isOwnEvent = (event: MouseEvent) => !tracked || (event as PointerEvent).pointerId === tracked.pointerId;
         const onMove = (event: MouseEvent) => {
             const drag = dragRef.current;
-            if (!drag) return;
+            if (!drag || !isOwnEvent(event)) return;
             if (event.buttons === 0) {
                 // Released outside the window.
                 drag.stop();
@@ -470,12 +529,12 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         };
         const onUp = (event: MouseEvent) => {
             const drag = dragRef.current;
-            if (!drag) return;
+            if (!drag || !isOwnEvent(event)) return;
             drag.x = event.clientX;
             drag.y = event.clientY;
             runDragFrame(false);
             const moved = drag.moved;
-            drag.stop();
+            drag.stop(false, event.altKey);
             if (moved) clearTextSelection(doc);
             if (moved) {
                 // The click that follows lands on the common ancestor of both cells (often the row):
@@ -484,26 +543,57 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
                 setTimeout(() => { suppressClickRef.current = false; }, 0);
             }
         };
+        const onCancel = (event: Event) => {
+            if (isOwnEvent(event as MouseEvent)) dragRef.current?.stop();
+        };
+        // Escape abandons a tracked drag (the fill writes nothing).
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.key !== 'Escape' || !dragRef.current) return;
+            event.preventDefault();
+            event.stopPropagation();
+            dragRef.current.stop();
+        };
         const view = doc.defaultView;
         const onBlur = () => dragRef.current?.stop();
+        let ended = false;
         const drag: DragState = {
             anchor, head, x, y, frame: 0, moved: false,
-            stop: () => {
+            onTrack: tracked?.onTrack,
+            stop: (cancelled = true, altKey = false) => {
                 if (drag.frame) cancelAnimationFrame(drag.frame);
                 drag.frame = 0;
-                doc.removeEventListener('mousemove', onMove, true);
-                doc.removeEventListener('mouseup', onUp, true);
+                doc.removeEventListener(moveType, onMove, true);
+                doc.removeEventListener(upType, onUp, true);
+                if (tracked) {
+                    doc.removeEventListener('pointercancel', onCancel, true);
+                    doc.removeEventListener('keydown', onKeyDown, true);
+                }
                 view?.removeEventListener('blur', onBlur);
                 latestRef.current.containerRef.current?.classList.remove(RANGE_DRAGGING_CLASS);
                 if (dragRef.current === drag) dragRef.current = null;
+                if (!ended) {
+                    ended = true;
+                    if (tracked) tracked.onEnd({ cancelled, altKey });
+                }
             },
         };
         dragRef.current = drag;
-        doc.addEventListener('mousemove', onMove, true);
-        doc.addEventListener('mouseup', onUp, true);
+        doc.addEventListener(moveType, onMove, true);
+        doc.addEventListener(upType, onUp, true);
+        if (tracked) {
+            doc.addEventListener('pointercancel', onCancel, true);
+            doc.addEventListener('keydown', onKeyDown, true);
+        }
         view?.addEventListener('blur', onBlur);
     }, [runDragFrame]);
 
+    const startTrackedDrag = useCallback((options: GridTrackedDragOptions) => {
+        const viewport = latestRef.current.viewportRef.current;
+        if (!viewport || !latestRef.current.enabled) return;
+        const { start, x, y, pointerId, onTrack, onEnd } = options;
+        startDrag(start, start, x, y, viewport.ownerDocument, { pointerId, onTrack, onEnd });
+    }, [startDrag]);
+
     const handleMouseDown = useCallback((event: React.MouseEvent<HTMLElement>) => {
         if (event.button !== 0 || event.defaultPrevented) return;
         const { context: ctx } = latestRef.current;
@@ -511,6 +601,8 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         const viewport = event.currentTarget;
         const hit = cellFromTarget(event.target, viewport);
         if (!hit || !isRangeColumnField(hit.field)) return;
+        // The fill handle starts its own drag (useGridFillHandle).
+        if ((event.target as Element).closest?.('.ogx__cell-fill-handle')) return;
         // Typing targets and open editors keep the pointer to themselves.
         if (hit.element.classList.contains('ogx__cell--editing') || isTextEntryElement(event.target as Element)) return;
         const id = ctx.rowIds[hit.rowIndex];
@@ -598,6 +690,8 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         stats,
         reportFocus,
         setModel,
+        getCurrentRange: currentRange,
+        startTrackedDrag,
     };
 }
 

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/useGridColumnsPanel.ts

@@ -16,26 +16,46 @@ export interface UseGridColumnsPanelResult {
     standalonePanelRef: RefObject<HTMLDivElement | null>;
     /** The column menu's **Manage columns** action. */
     openColumnsPanel: () => void;
+    /** Passed to the toolbar as `forceFiltersOpen`. */
+    toolbarFiltersRequested: boolean;
+    /** Passed to the toolbar as `onFiltersPanelClose`. */
+    closeToolbarFiltersPanel: () => void;
+    /**
+     * Opens the toolbar's filter panel (a header filter cell's "Custom filter"); undefined while no
+     * `GridToolbar` that can show it is rendered.
+     */
+    openFiltersPanel: (() => void) | undefined;
 }
 
 /**
  * Opens the Columns panel for the column menu: in the toolbar when a `GridToolbar` has registered
  * through `GridToolbarHostContext`, otherwise as the standalone panel, which closes on Escape or a
- * mousedown outside it.
+ * mousedown outside it. Also opens the toolbar's filter panel for the header filter row, when a
+ * `GridToolbar` has registered that it can show it.
  */
 export function useGridColumnsPanel(): UseGridColumnsPanelResult {
     const [toolbarPanelRequested, setToolbarPanelRequested] = useState(false);
     const [standalonePanelOpen, setStandalonePanelOpen] = useState(false);
     const standalonePanelRef = useRef<HTMLDivElement>(null);
     const toolbarHostCountRef = useRef(0);
+    // State, not a ref: whether "Custom filter" can open the panel decides how it renders.
+    const [filtersHostCount, setFiltersHostCount] = useState(0);
+    const [toolbarFiltersRequested, setToolbarFiltersRequested] = useState(false);
 
     const toolbarHost = useMemo<GridToolbarHost>(() => ({
         registerColumnsPanel: () => {
             toolbarHostCountRef.current += 1;
             return () => { toolbarHostCountRef.current -= 1; };
         },
+        registerFiltersPanel: () => {
+            setFiltersHostCount(count => count + 1);
+            return () => setFiltersHostCount(count => count - 1);
+        },
     }), []);
 
+    const requestFiltersPanel = useCallback(() => setToolbarFiltersRequested(true), []);
+    const closeToolbarFiltersPanel = useCallback(() => setToolbarFiltersRequested(false), []);
+
     const openColumnsPanel = useCallback(() => {
         if (toolbarHostCountRef.current > 0) {
             setToolbarPanelRequested(true);
@@ -73,5 +93,8 @@ export function useGridColumnsPanel(): UseGridColumnsPanelResult {
         closeStandalonePanel,
         standalonePanelRef,
         openColumnsPanel,
+        toolbarFiltersRequested,
+        closeToolbarFiltersPanel,
+        openFiltersPanel: filtersHostCount > 0 ? requestFiltersPanel : undefined,
     };
 }

package/lib/hooks/core/useGridControlledState.ts

@@ -7,11 +7,13 @@ import type {
     GridPaginationModel,
     GridAggregationModel,
     GridPivotModel,
+    GridRowGroupingModel,
     GridCellSelectionModel,
     GridCellSelectionChangeDetails,
     GridCellSelectionReason,
 } from '../../types';
 import type { GridInitialState, GridDensityState } from '../../state/types';
+import { EMPTY_ROW_GROUPING_MODEL } from '../../utils/gridModes';
 
 export type GridDensity = GridDensityState['density'];
 
@@ -27,6 +29,9 @@ export interface UseGridControlledStateParams {
     aggregationModel?: GridAggregationModel;
     onAggregationModelChange?: (model: GridAggregationModel) => void;
 
+    rowGroupingModel?: GridRowGroupingModel;
+    onRowGroupingModelChange?: (model: GridRowGroupingModel) => void;
+
     columnVisibilityModel?: Record<string, boolean>;
     onColumnVisibilityModelChange?: (model: Record<string, boolean>) => void;
 
@@ -68,6 +73,11 @@ export interface UseGridControlledStateReturn {
     aggregationModel: GridAggregationModel;
     handleAggregationModelChange: (model: GridAggregationModel) => void;
 
+    // row grouping (v3.5: a controlled/uncontrolled pair)
+    rowGroupingModel: GridRowGroupingModel;
+    /** Sets the internal model when uncontrolled and fires onRowGroupingModelChange. */
+    handleRowGroupingModelChange: (model: GridRowGroupingModel) => void;
+
     // column visibility
     columnVisibilityModel: Record<string, boolean>;
     handleColumnVisibilityModelChange: (model: Record<string, boolean>) => void;
@@ -131,6 +141,8 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         onFilterModelChange,
         aggregationModel: propAggregationModel,
         onAggregationModelChange,
+        rowGroupingModel: propRowGroupingModel,
+        onRowGroupingModelChange,
         columnVisibilityModel: propColumnVisibilityModel,
         onColumnVisibilityModelChange,
         pinnedColumns: propPinnedColumns,
@@ -190,6 +202,18 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         onAggregationModelChange?.(model);
     }, [isAggregationControlled, onAggregationModelChange]);
 
+    // ── Row grouping ─────────────────────────────────────────────────────────
+    // A passed rowGroupingModel controls grouping and is used as is (the hierarchy hooks memoise on
+    // it); without one the grid keeps its own model, changed through apiRef and the AI assistant.
+    const isRowGroupingControlled = propRowGroupingModel !== undefined;
+    const [internalRowGroupingModel, setInternalRowGroupingModel] = useState<GridRowGroupingModel>(EMPTY_ROW_GROUPING_MODEL);
+    const rowGroupingModel = (isRowGroupingControlled ? propRowGroupingModel : internalRowGroupingModel) || EMPTY_ROW_GROUPING_MODEL;
+
+    const handleRowGroupingModelChange = useCallback((model: GridRowGroupingModel) => {
+        if (!isRowGroupingControlled) setInternalRowGroupingModel(model);
+        onRowGroupingModelChange?.(model);
+    }, [isRowGroupingControlled, onRowGroupingModelChange]);
+
     // ── Column visibility ────────────────────────────────────────────────────
     const isColumnVisibilityControlled = propColumnVisibilityModel !== undefined;
     const [internalColumnVisibilityModel, setInternalColumnVisibilityModel] = useState<Record<string, boolean>>(
@@ -295,6 +319,9 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         aggregationModel,
         handleAggregationModelChange,
 
+        rowGroupingModel,
+        handleRowGroupingModelChange,
+
         columnVisibilityModel,
         handleColumnVisibilityModelChange,