@opencorestack/opengridx 3.4.0 → 3.5.1

package/lib/hooks/core/useGridCellSelection.ts

@@ -121,6 +121,8 @@ export interface UseGridCellSelectionReturn {
      * 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 {
@@ -130,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. */
@@ -451,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;
@@ -475,11 +496,22 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         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();
@@ -497,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):
@@ -511,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;
@@ -538,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];
@@ -626,6 +691,7 @@ export function useGridCellSelection<R extends GridRowModel>(params: UseGridCell
         reportFocus,
         setModel,
         getCurrentRange: currentRange,
+        startTrackedDrag,
     };
 }
 

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,
 

package/lib/hooks/core/useGridDevWarnings.ts

@@ -10,8 +10,16 @@ export interface UseGridDevWarningsParams {
     totalRowCount: number;
     /** `pinnedRows` is set while tree data or row grouping is active, where it has no effect. */
     pinnedRowsIgnored?: boolean;
-    /** Pixel height of the scrollable content. */
+    /** Pixel height of the scrollable content, uncapped. */
     scrollHeight?: number;
+    /**
+     * The tallest element the browser lays out (`getMaxElementHeight`): `undefined` until measured (the warning
+     * waits), `Infinity` where there is no layout engine (the lowest known cap is used).
+     */
+    maxContentHeight?: number;
+    /** Unpinned rows the user can scroll to, and how many unpinned rows there are. */
+    reachableRowCount?: number;
+    unpinnedRowCount?: number;
     /** `listView` is set but `listViewColumn` is not, so the grid view is shown. */
     listViewWithoutColumn?: boolean;
     /** Number of items the list view renders (0 when the list view is not shown). It does not virtualize. */
@@ -31,7 +39,7 @@ export const LIST_VIEW_WARN_THRESHOLD = 2000;
 export const MAX_SCROLLABLE_HEIGHT = 17_800_000;
 
 export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
-    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, maxContentHeight, reachableRowCount, unpinnedRowCount, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
     const warnedPaginationRef = useRef(false);
     const warnedUnboundedRef = useRef(false);
     const warnedPinnedRowsRef = useRef(false);
@@ -67,14 +75,21 @@ export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
     }, [pinnedRowsIgnored]);
 
     useEffect(() => {
-        if (process.env.NODE_ENV === 'production' || warnedHeightRef.current || scrollHeight <= MAX_SCROLLABLE_HEIGHT) return;
+        if (process.env.NODE_ENV === 'production' || warnedHeightRef.current || maxContentHeight === undefined) return;
+        const measured = Number.isFinite(maxContentHeight);
+        // Once the browser's cap is measured, warn only when rows are actually cut off; before that (and
+        // where there is no layout engine) fall back to the lowest known cap.
+        if (measured ? scrollHeight <= maxContentHeight : scrollHeight <= MAX_SCROLLABLE_HEIGHT) return;
         warnedHeightRef.current = true;
+        const reach = measured && reachableRowCount !== undefined && unpinnedRowCount !== undefined
+            ? `Only the first ${reachableRowCount.toLocaleString('en-US')} of ${unpinnedRowCount.toLocaleString('en-US')} rows can be scrolled to in this browser. `
+            : 'The last rows may not be reachable by scrolling. ';
         console.warn(
-            `[OpenGridX] The grid content is ${Math.round(scrollHeight)}px tall. Browsers cap element heights ` +
-            '(about 17.9M px in Firefox, 33.5M px in Chrome and Safari), so the last rows may not be reachable by scrolling. ' +
+            `[OpenGridX] The grid content is ${Math.round(scrollHeight)}px tall, more than this browser lays out ` +
+            '(about 17.9M px in Firefox, 33.5M px in Chrome and Safari). ' + reach +
             'Use pagination, server-side or infinite loading, or a smaller rowHeight. See docs/features/virtualization.md.'
         );
-    }, [scrollHeight]);
+    }, [scrollHeight, maxContentHeight, reachableRowCount, unpinnedRowCount]);
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedPaginationRef.current) return;

package/lib/hooks/core/useGridFillHandle.ts

@@ -0,0 +1,323 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { RefObject } from 'react';
+import type {
+    GridCellCoordinates,
+    GridCellParams,
+    GridCellSelectionModel,
+    GridColDef,
+    GridEditSkipReason,
+    GridFillDirection,
+    GridFillResult,
+    GridRowId,
+    GridRowMeta,
+    GridRowModel,
+} from '../../types';
+import { attempt } from '../../utils/attempt';
+import { classifyKeyTarget } from '../../utils/focus';
+import { isRangeColumnField } from '../../utils/cellSelection';
+import type { CellRangeRect, GridFillHandlePosition } from '../../utils/cellSelection';
+import { isSyntheticRowId } from '../../utils/syntheticRows';
+import { getCellValue, warnCallbackFailure } from '../../utils/values';
+import { buildEditTargetContext, isEditTargetWritable } from '../../utils/editing/targets';
+import type { GridEditTargetContext } from '../../utils/editing/targets';
+import {
+    computeFillValues,
+    fillHandleCell,
+    fillLines,
+    fillRangeCorners,
+    fillTargetFromPointer,
+} from '../../utils/editing/fill';
+import type { GridBatchCellEdit, UseGridBatchEditReturn } from '../features/useGridBatchEdit';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+
+/** The class of the fill handle square (public from v3.5). */
+export const FILL_HANDLE_CLASS = 'ogx__cell-fill-handle';
+
+export interface UseGridFillHandleParams<R extends GridRowModel> {
+    /** The grid root: Ctrl/Cmd+D and Ctrl/Cmd+R are listened for here. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    selection: UseGridCellSelectionReturn;
+    disableFillHandle: boolean;
+    /** Whether a cell editor is open: no handle and no shortcuts meanwhile. */
+    isEditing: boolean;
+    allRenderableRows: R[];
+    getRowId: (row: R) => GridRowId;
+    /** System columns and the rendered data columns, in render order. */
+    navigationColumns: ReadonlyArray<GridColDef<R>>;
+    columnIndexMap: Map<string, number>;
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
+    rowMetaMap: Map<GridRowId, GridRowMeta>;
+    getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    batchEdit: UseGridBatchEditReturn<R>;
+    onFill?: (result: GridFillResult) => void;
+}
+
+export interface UseGridFillHandleReturn {
+    /** Where the rows draw the handle, or null. */
+    handle: GridFillHandlePosition | null;
+}
+
+interface FillDragState<R extends GridRowModel> {
+    source: CellRangeRect;
+    /** The source range model, restored when the drag ends where it started or is cancelled. */
+    sourceModel: GridCellSelectionModel;
+    anchor: { row: number; col: number };
+    ctx: GridEditTargetContext<R>;
+    x: number;
+    y: number;
+    scrollLeft: number;
+    scrollTop: number;
+    target: { rect: CellRangeRect; direction: GridFillDirection } | null;
+}
+
+/** 'down', 'right' or null for a keydown: Ctrl/Cmd+D and Ctrl/Cmd+R (also on non-Latin layouts). */
+function fillShortcut(event: KeyboardEvent): 'down' | 'right' | null {
+    if (event.altKey || event.shiftKey || !(event.ctrlKey || event.metaKey)) return null;
+    const key = (event.key ?? '').toLowerCase();
+    const latin = /^[a-z]$/.test(key);
+    if (key === 'd' || (!latin && event.code === 'KeyD')) return 'down';
+    if (key === 'r' || (!latin && event.code === 'KeyR')) return 'right';
+    return null;
+}
+
+/**
+ * The fill handle (v3.5). With `cellSelection` on, the bottom-right cell of the range carries a
+ * square; dragging it extends the range in one direction (the larger pointer offset wins, with the
+ * range drag's auto-scroll) and fills the new cells from the source range on release: numbers or
+ * dates with an equal step continue as a series, anything else repeats, Alt at release copies, and
+ * `GridColDef.fillValue` has the last word. Ctrl/Cmd+D fills down from the range's top row and
+ * Ctrl/Cmd+R right from its left column. Every fill is one batch edit (source `'fill'`), so one undo
+ * step. Runs after useGridUndoRedo.
+ */
+export function useGridFillHandle<R extends GridRowModel>(params: UseGridFillHandleParams<R>): UseGridFillHandleReturn {
+    const {
+        containerRef, viewportRef, selection, disableFillHandle, isEditing, allRenderableRows, getRowId,
+        navigationColumns, columnIndexMap, getSpanOrigin,
+    } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const enabled = selection.enabled && !disableFillHandle;
+    const hasEditableColumn = useMemo(() => navigationColumns.some(c => c.editable), [navigationColumns]);
+
+    // The handle: on the range's bottom-right cell (or the cell whose span covers it).
+    const resolved = selection.resolved;
+    const handle = useMemo<GridFillHandlePosition | null>(() => {
+        if (!enabled || !hasEditableColumn || !resolved) return null;
+        const fields = navigationColumns.filter(c => isRangeColumnField(c.field)).map(c => c.field);
+        const rowIdAt = (r: number) => {
+            const row = allRenderableRows[r];
+            return row === undefined ? undefined : getRowId(row);
+        };
+        const cell = fillHandleCell(resolved, rowIdAt, fields, getSpanOrigin);
+        if (!cell) return null;
+        const col = columnIndexMap.get(cell.field);
+        return col === undefined ? null : { row: cell.row, col };
+    }, [enabled, hasEditableColumn, resolved, allRenderableRows, getRowId, navigationColumns, columnIndexMap, getSpanOrigin]);
+
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => { mountedRef.current = false; };
+    }, []);
+
+    const getContext = useCallback((): GridEditTargetContext<R> => {
+        const p = latestRef.current;
+        return buildEditTargetContext(p.allRenderableRows, p.getRowId, p.navigationColumns);
+    }, []);
+
+    /** Selects `rect` with its corners chosen for the fill. */
+    const selectRect = useCallback((
+        ctx: GridEditTargetContext<R>,
+        rect: CellRangeRect,
+        direction: GridFillDirection,
+        anchor: { row: number; col: number },
+        reason: 'pointer' | 'keyboard',
+    ) => {
+        const corners = fillRangeCorners(rect, direction, anchor);
+        const toCell = (p: { row: number; col: number }): GridCellCoordinates => ({ id: ctx.rowIds[p.row], field: ctx.columns[p.col].field });
+        latestRef.current.selection.setModel([{ anchor: toCell(corners.anchor), head: toCell(corners.head) }], reason);
+    }, []);
+
+    /** Fills `target` from `source` (display indices) and selects `target`. */
+    const fill = useCallback(async (
+        ctx: GridEditTargetContext<R>,
+        source: CellRangeRect,
+        target: CellRangeRect,
+        direction: GridFillDirection,
+        copy: boolean,
+        anchor: { row: number; col: number },
+        reason: 'pointer' | 'keyboard',
+    ): Promise<GridFillResult> => {
+        const { batchEdit, isCellEditable, rowMetaMap, getSpanOrigin: spanOrigin } = latestRef.current;
+        const rules = { isCellEditable, rowMetaMap, getSpanOrigin: spanOrigin };
+        const vertical = direction === 'down' || direction === 'up';
+        const rowAt = (r: number): R | undefined => {
+            const id = ctx.rowIds[r];
+            return id === undefined ? undefined : batchEdit.getRow(id) ?? ctx.rows[r];
+        };
+        const edits: GridBatchCellEdit[] = [];
+        const skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[] = [];
+        for (const line of fillLines(source, target, direction)) {
+            if (line.targets.length === 0) continue;
+            const position = (k: number) => (vertical ? { r: k, c: line.line } : { r: line.line, c: k });
+            // The source values in fill order; synthetic rows hold no data and are left out.
+            const sourceValues: unknown[] = [];
+            for (const k of line.source) {
+                const { r, c } = position(k);
+                const row = rowAt(r);
+                const colDef = ctx.columns[c];
+                if (!row || !colDef || isSyntheticRowId(ctx.rowIds[r], rowMetaMap)) continue;
+                sourceValues.push(getCellValue(row, colDef.field, colDef));
+            }
+            if (sourceValues.length === 0) continue;
+            const values = computeFillValues(sourceValues, line.targets.length, !copy);
+            line.targets.forEach((k, index) => {
+                const { r, c } = position(k);
+                const row = rowAt(r);
+                const colDef = ctx.columns[c];
+                const id = ctx.rowIds[r];
+                if (!row || !colDef || id === undefined) return;
+                if (!isEditTargetWritable(ctx, rules, row, r, c)) {
+                    skipped.push({ id, field: colDef.field, reason: 'notEditable' });
+                    return;
+                }
+                let value = values[index];
+                const fillValue = colDef.fillValue;
+                if (fillValue) {
+                    const decided = attempt(() => fillValue.call(colDef, {
+                        row, id, field: colDef.field, colDef, direction, sourceValues: sourceValues.slice(), index, value, copy,
+                    }));
+                    if (!decided.ok) {
+                        warnCallbackFailure(`fillValue:${colDef.field}`, `fillValue of column "${colDef.field}" threw; the cell was skipped`, decided.error);
+                        skipped.push({ id, field: colDef.field, reason: 'invalidValue' });
+                        return;
+                    }
+                    value = decided.value;
+                }
+                edits.push({ id, field: colDef.field, value });
+            });
+        }
+
+        // The source and the filled cells become the range.
+        selectRect(ctx, target, direction, anchor, reason);
+
+        const outcome = await batchEdit.applyEdits(edits, 'fill');
+        const result: GridFillResult = {
+            updated: outcome.result.updated,
+            failed: outcome.result.failed,
+            skipped: [...skipped, ...outcome.result.skipped],
+            direction,
+        };
+        latestRef.current.onFill?.(result);
+        return result;
+    }, [selectRect]);
+
+    // ── Pointer: drag the handle ────────────────────────────────────────────
+    const dragRef = useRef<FillDragState<R> | null>(null);
+
+    const onTrack = useCallback((head: GridCellCoordinates, x: number, y: number) => {
+        const drag = dragRef.current;
+        const viewport = latestRef.current.viewportRef.current;
+        if (!drag || !viewport) return;
+        const ctx = drag.ctx;
+        const row = ctx.rowIndexById.get(head.id);
+        const col = ctx.colIndexByField.get(head.field);
+        if (row === undefined || col === undefined) return;
+        const dx = x - drag.x + viewport.scrollLeft - drag.scrollLeft;
+        const dy = y - drag.y + viewport.scrollTop - drag.scrollTop;
+        const target = fillTargetFromPointer(drag.source, { row, col }, dx, dy);
+        drag.target = target;
+        if (target) selectRect(ctx, target.rect, target.direction, drag.anchor, 'pointer');
+        else latestRef.current.selection.setModel(drag.sourceModel, 'pointer');
+    }, [selectRect]);
+
+    const onEnd = useCallback(({ cancelled, altKey }: { cancelled: boolean; altKey: boolean }) => {
+        const drag = dragRef.current;
+        dragRef.current = null;
+        if (!drag || !mountedRef.current) return;
+        const ctx = drag.ctx;
+        if (cancelled || !drag.target) {
+            latestRef.current.selection.setModel(drag.sourceModel, 'pointer');
+            return;
+        }
+        void fill(ctx, drag.source, drag.target.rect, drag.target.direction, altKey, drag.anchor, 'pointer');
+    }, [fill]);
+
+    const dragEnabled = enabled && hasEditableColumn;
+    useEffect(() => {
+        const viewport = viewportRef.current;
+        if (!viewport || !dragEnabled) return;
+        const onPointerDown = (event: PointerEvent) => {
+            if (event.button !== 0 || !(event.target instanceof Element)) return;
+            const handleEl = event.target.closest(`.${FILL_HANDLE_CLASS}`);
+            if (!handleEl || handleEl.closest('.ogx__viewport') !== viewport || latestRef.current.isEditing) return;
+            const { selection: s } = latestRef.current;
+            const { range, resolved: current } = s.getCurrentRange();
+            if (!range || !current) return;
+            const ctx = getContext();
+            const startId = ctx.rowIds[current.bottom];
+            const startCol = ctx.columns[current.right];
+            if (startId === undefined || !startCol) return;
+            // No mousedown follows, so the range drag does not start and focus does not move.
+            event.preventDefault();
+            const doc = viewport.ownerDocument;
+            if (!viewport.contains(doc.activeElement)) viewport.focus({ preventScroll: true });
+            // Pointer events keep reaching the grid even after the handle moves to another cell.
+            attempt(() => viewport.setPointerCapture(event.pointerId));
+            dragRef.current = {
+                source: { top: current.top, bottom: current.bottom, left: current.left, right: current.right },
+                sourceModel: [range],
+                anchor: { row: current.anchorRow, col: current.anchorCol },
+                ctx,
+                x: event.clientX,
+                y: event.clientY,
+                scrollLeft: viewport.scrollLeft,
+                scrollTop: viewport.scrollTop,
+                target: null,
+            };
+            s.startTrackedDrag({
+                start: { id: startId, field: startCol.field },
+                x: event.clientX,
+                y: event.clientY,
+                pointerId: event.pointerId,
+                onTrack,
+                onEnd,
+            });
+        };
+        viewport.addEventListener('pointerdown', onPointerDown);
+        return () => viewport.removeEventListener('pointerdown', onPointerDown);
+    }, [viewportRef, dragEnabled, getContext, onTrack, onEnd]);
+
+    // ── Keyboard: Ctrl/Cmd+D and Ctrl/Cmd+R ────────────────────────────────
+    useEffect(() => {
+        const root = containerRef.current;
+        if (!root || !enabled) return;
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.defaultPrevented) return;
+            const shortcut = fillShortcut(event);
+            if (!shortcut) return;
+            const viewport = latestRef.current.viewportRef.current;
+            if (!viewport || latestRef.current.isEditing) return;
+            const kind = classifyKeyTarget(event.target, viewport);
+            if (kind !== 'grid' && kind !== 'control') return;
+            const { range, resolved: current } = latestRef.current.selection.getCurrentRange();
+            if (!range || !current) return;
+            // The browser's bookmark (Ctrl+D) and reload (Ctrl/Cmd+R) never fire inside the grid.
+            event.preventDefault();
+            const rect = { top: current.top, bottom: current.bottom, left: current.left, right: current.right };
+            const source = shortcut === 'down' ? { ...rect, bottom: rect.top } : { ...rect, right: rect.left };
+            if (shortcut === 'down' ? rect.bottom === rect.top : rect.right === rect.left) return;
+            void fill(getContext(), source, rect, shortcut, true, { row: current.anchorRow, col: current.anchorCol }, 'keyboard');
+        };
+        root.addEventListener('keydown', onKeyDown);
+        return () => root.removeEventListener('keydown', onKeyDown);
+    }, [containerRef, enabled, fill, getContext]);
+
+    return { handle: isEditing ? null : handle };
+}
+
+export type { GridFillHandlePosition };