@rowsncolumns/spreadsheet 10.3.0 → 10.4.0

package/dist/esm/hooks/use-selection.js

@@ -1,10 +1,11 @@
 import { findLastContentfulCell, isNull } from "@rowsncolumns/grid";
 import { cellToArea } from "@rowsncolumns/grid";
-import { useIsomorphicLayoutEffect } from "@rowsncolumns/grid";
+import { getOwnerDocument, useIsomorphicLayoutEffect } from "@rowsncolumns/grid";
 import { Align, cellIdentifier, cellRangeToBounds, clampCellCoords, clampIndex, Direction, findNextCellInDataRegion, findNextCellWithinBounds, getBoundedCells, isAreasEqual, isEqualCells, MouseButtonCodes, newSelectionFromDrag, selectionSpansCells, } from "@rowsncolumns/grid";
 import { useCallback, useReducer, useRef, useState } from "react";
 import { scheduleImmediatePriorityCallback, scheduleNormalPriorityCallback, } from "../api/scheduler";
 import { MOVE_OVERWRITE_PROMPT, needsOverwritePrompt } from "../api/move-overwrite";
+import { findActiveTableWithinCell, getNextCellInTable, getTableColumnSelectRange, getTableRowSelectRange, getTableSelectAllRange, } from "../api/table";
 import { DEFAULT_ARRAY } from "../config";
 import { isMac } from "../helpers";
 import { useCallbackRef } from "./use-callback-ref";
@@ -85,7 +86,7 @@ const fillShrinkFor = (selection, coords) => {
 const defaultConfirmMoveOverwrite = (message) => typeof window === "undefined" || typeof window.confirm !== "function"
     ? true
     : window.confirm(message);
-export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selections, onChangeSelections, columnCount = 0, rowCount = 0, selectionPolicy = "multiple", newSelectionMode = "clear", allowDeselectSelection = true, onFill, onFillHandleRelease, onFillShrink, onInsertCutCells, confirmMoveOverwrite = defaultConfirmMoveOverwrite, isHiddenRow = defaultIsHidden, isHiddenColumn = defaultIsHidden, alwaysScrollToActiveCell = true, selectionTopBound = 0, selectionBottomBound = rowCount, selectionLeftBound = 0, selectionRightBound = columnCount, mouseDownInterceptor, mouseMoveInterceptor, mergedCells = DEFAULT_ARRAY, canSelectionSpanMergedCells = defaultSelectionSpan, getValue, onMoveSelection, getCellCoordsFromOffset, getCellBounds, getViewPort, focus, scrollToCell, isMergedCell, enableSelectOnEnterKey, formulaMode, isTouchDevice, getDataRowCount, isRowHeader, isColumnHeader, enableDataBoundaryNavigation = false, }) => {
+export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selections, onChangeSelections, columnCount = 0, rowCount = 0, selectionPolicy = "multiple", newSelectionMode = "clear", allowDeselectSelection = true, onFill, onFillHandleRelease, onFillShrink, onInsertCutCells, confirmMoveOverwrite = defaultConfirmMoveOverwrite, isHiddenRow = defaultIsHidden, isHiddenColumn = defaultIsHidden, alwaysScrollToActiveCell = true, selectionTopBound = 0, selectionBottomBound = rowCount, selectionLeftBound = 0, selectionRightBound = columnCount, mouseDownInterceptor, mouseMoveInterceptor, mergedCells = DEFAULT_ARRAY, canSelectionSpanMergedCells = defaultSelectionSpan, getValue, onMoveSelection, getCellCoordsFromOffset, getCellBounds, getViewPort, focus, scrollToCell, isMergedCell, enableSelectOnEnterKey, formulaMode, isTouchDevice, getDataRowCount, isRowHeader, isColumnHeader, enableDataBoundaryNavigation = false, tables, onInsertTableRow, }) => {
     const [fillSelection, setFillSelection] = useState();
     const [fillShrink, setFillShrink] = useState();
     const fillShrinkRef = useRef(undefined);
@@ -105,24 +106,35 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
      * release always fires `contextmenu`; neither may reach the grid's cell
      * context menu while the user is dragging the fill handle.
      */
+    /**
+     * Documents the in-flight gestures listen on. The grid may render into a
+     * popout window, whose document is not the bundle's global `document`; a
+     * gesture binds its move/up listeners to the document of the element it
+     * started on and unbinds from that same document.
+     */
+    const selectionDocumentRef = useRef(null);
+    const fillDocumentRef = useRef(null);
+    const dragSelectionDocumentRef = useRef(null);
+    const tapDocumentRef = useRef(null);
     const contextMenuSuppressorRef = useRef(null);
     const releaseContextMenuSuppressor = useCallback(() => {
-        const handler = contextMenuSuppressorRef.current;
-        if (!handler)
+        const suppressor = contextMenuSuppressorRef.current;
+        if (!suppressor)
             return;
         contextMenuSuppressorRef.current = null;
-        document.removeEventListener("contextmenu", handler, true);
+        suppressor.ownerDocument.removeEventListener("contextmenu", suppressor.handler, true);
     }, []);
     const suppressNextContextMenu = useCallback(() => {
         if (contextMenuSuppressorRef.current)
             return;
+        const ownerDocument = fillDocumentRef.current ?? document;
         const handler = (e) => {
             e.preventDefault();
             e.stopPropagation();
             releaseContextMenuSuppressor();
         };
-        contextMenuSuppressorRef.current = handler;
-        document.addEventListener("contextmenu", handler, true);
+        contextMenuSuppressorRef.current = { handler, ownerDocument };
+        ownerDocument.addEventListener("contextmenu", handler, true);
     }, [releaseContextMenuSuppressor]);
     const selectionsRef = useRef([]);
     const fillSelectionRef = useRef(undefined);
@@ -349,9 +361,11 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
     const handleMouseUp = useCallback(() => {
         /* Reset selection mode */
         isSelecting.current = false;
-        /* Remove listener */
-        document.removeEventListener("mousemove", handleMouseMove);
-        document.removeEventListener("mouseup", handleMouseUp);
+        /* Remove listener from the document the gesture started on */
+        const ownerDocument = selectionDocumentRef.current ?? document;
+        selectionDocumentRef.current = null;
+        ownerDocument.removeEventListener("mousemove", handleMouseMove);
+        ownerDocument.removeEventListener("mouseup", handleMouseUp);
         /* Update last selection */
         const curSelections = selectionsRef.current;
         const len = curSelections.length;
@@ -572,12 +586,62 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         selectionLeftBound,
         selectionRightBound,
     ]);
+    // Select all
+    const selectAll = useCallback(() => {
+        selectionStart.current = {
+            rowIndex: selectionTopBound,
+            columnIndex: selectionLeftBound,
+        };
+        modifySelection({
+            rowIndex: selectionBottomBound,
+            columnIndex: selectionRightBound,
+        });
+    }, [
+        selectionTopBound,
+        selectionLeftBound,
+        selectionRightBound,
+        selectionBottomBound,
+        modifySelection,
+    ]);
+    /**
+     * Inside a table Ctrl+A / Ctrl+Space / Shift+Space walk Excel's table
+     * cycle before falling back to the sheet-wide behaviour. Applies `range`
+     * (keeping the active cell) and reports whether a table handled the key;
+     * a `null` cycle step means "the sheet-wide step" and returns false.
+     */
+    const currentSingleArea = () => selections.length === 1 ? selections[0].range : undefined;
+    const applyTableRange = useCallback((range) => {
+        if (!range) {
+            return false;
+        }
+        selectionStart.current = {
+            rowIndex: range.startRowIndex,
+            columnIndex: range.startColumnIndex,
+        };
+        modifySelection({
+            rowIndex: range.endRowIndex,
+            columnIndex: range.endColumnIndex,
+        });
+        return true;
+    }, [modifySelection]);
+    const activeTable = activeCell
+        ? findActiveTableWithinCell(sheetId, activeCell, tables)
+        : undefined;
     // ⌘A or ⌘+Shift+Space
     // Select all cells in bounding area
     const selectAllBoundedCells = useCallback(() => {
         if (!selectionEnd.current || !selectionStart.current) {
             return;
         }
+        if (activeTable) {
+            const step = getTableSelectAllRange(activeTable, currentSingleArea());
+            if (step === null) {
+                selectAll();
+                return;
+            }
+            applyTableRange(step);
+            return;
+        }
         let topBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Up);
         let bottomBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Down);
         let leftBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Left);
@@ -608,30 +672,44 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         selectionTopBound,
         selectionLeftBound,
         selectionRightBound,
+        activeTable,
+        selections,
+        applyTableRange,
+        selectAll,
     ]);
-    // Select all
-    const selectAll = useCallback(() => {
+    // Select entire column
+    const selectEntireColumn = useCallback((columnIndex) => {
+        if (!selectionEnd.current ||
+            !selectionStart.current ||
+            columnIndex === void 0)
+            return;
         selectionStart.current = {
+            ...selectionStart.current,
             rowIndex: selectionTopBound,
-            columnIndex: selectionLeftBound,
         };
         modifySelection({
+            ...selectionEnd.current,
             rowIndex: selectionBottomBound,
-            columnIndex: selectionRightBound,
         });
-    }, [
-        selectionTopBound,
-        selectionLeftBound,
-        selectionRightBound,
-        selectionBottomBound,
-        modifySelection,
-    ]);
+    }, [modifySelection, selectionBottomBound, selectionTopBound]);
     // Ctrl+Space
     const selectColumn = useCallback((columnIndex) => {
         if (!selectionEnd.current ||
             !selectionStart.current ||
             columnIndex === void 0)
             return;
+        if (activeTable) {
+            const step = getTableColumnSelectRange(activeTable, {
+                start: selectionStart.current.columnIndex,
+                end: selectionEnd.current.columnIndex,
+            }, currentSingleArea());
+            if (step === null) {
+                selectEntireColumn(columnIndex);
+                return;
+            }
+            applyTableRange(step);
+            return;
+        }
         let topBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Up);
         let bottomBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Down);
         const isSameVerticalBounds = topBound === bottomBound;
@@ -653,22 +731,11 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         sheetId,
         selectionTopBound,
         selectionBottomBound,
+        activeTable,
+        selections,
+        applyTableRange,
+        selectEntireColumn,
     ]);
-    // Select entire column
-    const selectEntireColumn = useCallback((columnIndex) => {
-        if (!selectionEnd.current ||
-            !selectionStart.current ||
-            columnIndex === void 0)
-            return;
-        selectionStart.current = {
-            ...selectionStart.current,
-            rowIndex: selectionTopBound,
-        };
-        modifySelection({
-            ...selectionEnd.current,
-            rowIndex: selectionBottomBound,
-        });
-    }, [modifySelection, selectionBottomBound, selectionTopBound]);
     // Shift+Space
     const selectRow = useCallback((rowIndex) => {
         if (!selectionEnd.current ||
@@ -676,6 +743,25 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
             rowIndex === void 0) {
             return;
         }
+        if (activeTable) {
+            const step = getTableRowSelectRange(activeTable, {
+                start: selectionStart.current.rowIndex,
+                end: selectionEnd.current.rowIndex,
+            }, currentSingleArea());
+            if (step !== null) {
+                applyTableRange(step);
+                return;
+            }
+            selectionStart.current = {
+                ...selectionStart.current,
+                columnIndex: selectionLeftBound,
+            };
+            modifySelection({
+                ...selectionEnd.current,
+                columnIndex: selectionRightBound,
+            });
+            return;
+        }
         let leftBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Left);
         let rightBound = findLastContentfulCellInDirection(sheetId, selectionStart.current, selectionEnd.current, Direction.Right);
         const isSameHorizontalBounds = leftBound === rightBound;
@@ -695,6 +781,9 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         findLastContentfulCellInDirection,
         modifySelection,
         sheetId,
+        activeTable,
+        selections,
+        applyTableRange,
         selectionRightBound,
         selectionLeftBound,
     ]);
@@ -881,8 +970,10 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         const hasSelections = selectionsRef.current.length > 0;
         const isDeselecting = isMetaKey && allowDeselect;
         if (!isContextMenuClick && selectionPolicy !== "single") {
-            document.addEventListener("mouseup", handleMouseUp);
-            document.addEventListener("mousemove", handleMouseMove);
+            const ownerDocument = getOwnerDocument(e.currentTarget ?? e.target) ?? document;
+            selectionDocumentRef.current = ownerDocument;
+            ownerDocument.addEventListener("mouseup", handleMouseUp);
+            ownerDocument.addEventListener("mousemove", handleMouseMove);
         }
         /* Activate selection mode */
         // Disable flag for context menu
@@ -1096,11 +1187,22 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
                     }
                 }
                 else {
-                    if (isShiftKey) {
-                        keyNavigate(Direction.Left);
+                    const direction = isShiftKey ? Direction.Left : Direction.Right;
+                    const table = activeCell
+                        ? findActiveTableWithinCell(sheetId, activeCell, tables)
+                        : undefined;
+                    const tableTarget = table
+                        ? getNextCellInTable(table, activeCell, direction, isHiddenRow, isHiddenColumn)
+                        : null;
+                    if (table && tableTarget) {
+                        if (tableTarget.insertRow) {
+                            onInsertTableRow?.(table);
+                        }
+                        newSelection(tableTarget.cell);
+                        scrollToCell(tableTarget.cell);
                     }
                     else {
-                        keyNavigate(Direction.Right);
+                        keyNavigate(direction);
                     }
                 }
                 e.preventDefault();
@@ -1147,6 +1249,11 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         selectFirstCellInSheet,
         selectLastCellInSheet,
         enableSelectOnEnterKey,
+        newSelection,
+        isHiddenRow,
+        isHiddenColumn,
+        tables,
+        onInsertTableRow,
     ]);
     /**
      * TODO
@@ -1245,9 +1352,10 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         isFilling.current = false;
         const toggle = isFillToggleModifier(e);
         const button = fillButtonRef.current;
-        /* Remove listener */
-        document.removeEventListener("mousemove", handleFillMouseMove);
-        document.removeEventListener("mouseup", handleFillMouseUp);
+        /* Remove listener from the document the gesture started on */
+        const ownerDocument = fillDocumentRef.current ?? document;
+        ownerDocument.removeEventListener("mousemove", handleFillMouseMove);
+        ownerDocument.removeEventListener("mouseup", handleFillMouseUp);
         // The right-button (or macOS Ctrl+click) `contextmenu` event follows this
         // mouseup; keep swallowing it for one tick, then drop the suppressor so a
         // later, unrelated right-click still opens the cell context menu.
@@ -1341,6 +1449,8 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
     const handleFillMouseDown = useCallback((e) => {
         e.stopPropagation();
         e.preventDefault();
+        const ownerDocument = getOwnerDocument(e.currentTarget) ?? document;
+        fillDocumentRef.current = ownerDocument;
         const isRightButton = e.button === MouseButtonCodes.right;
         fillButtonRef.current = isRightButton ? "right" : "left";
         // Ctrl+drag on the handle must never become the macOS Ctrl+click
@@ -1350,8 +1460,8 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
             suppressNextContextMenu();
         }
         isFilling.current = true;
-        document.addEventListener("mousemove", handleFillMouseMove);
-        document.addEventListener("mouseup", handleFillMouseUp);
+        ownerDocument.addEventListener("mousemove", handleFillMouseMove);
+        ownerDocument.addEventListener("mouseup", handleFillMouseUp);
     }, [handleFillMouseMove, handleFillMouseUp, suppressNextContextMenu]);
     /**
      * Remove the last selection from state
@@ -1478,9 +1588,11 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         draggedSelection.current = void 0;
         draggedSelectionIndex.current = void 0;
         hasUserMovedSelection.current = false;
-        /* Remove event handlers */
-        document.removeEventListener("mouseup", handleSelectionMouseUp);
-        document.removeEventListener("mousemove", handleSelectionMouseMove);
+        /* Remove event handlers from the document the gesture started on */
+        const ownerDocument = dragSelectionDocumentRef.current ?? document;
+        dragSelectionDocumentRef.current = null;
+        ownerDocument.removeEventListener("mouseup", handleSelectionMouseUp);
+        ownerDocument.removeEventListener("mousemove", handleSelectionMouseMove);
         /* Force render */
         forceRender();
     }, [
@@ -1528,9 +1640,11 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
         }
         /* Set dragging flag */
         isDragging.current = true;
-        /* Listen to mousemove and mousedown events */
-        document.addEventListener("mouseup", handleSelectionMouseUp);
-        document.addEventListener("mousemove", handleSelectionMouseMove);
+        /* Listen on the document the gesture started on */
+        const ownerDocument = getOwnerDocument(e.currentTarget) ?? document;
+        dragSelectionDocumentRef.current = ownerDocument;
+        ownerDocument.addEventListener("mouseup", handleSelectionMouseUp);
+        ownerDocument.addEventListener("mousemove", handleSelectionMouseMove);
         /* Force a re-render */
         forceRender();
     }, [
@@ -1619,12 +1733,16 @@ export const useSelection = ({ sheetId, activeCell, onChangeActiveCell, selectio
             handleMouseDown(event);
             handleMouseUp();
         }
-        document.removeEventListener("pointerup", onPointerUp);
+        const ownerDocument = tapDocumentRef.current ?? document;
+        tapDocumentRef.current = null;
+        ownerDocument.removeEventListener("pointerup", onPointerUp);
     }, [handleMouseDown, handleMouseUp]);
     const onPointerDown = useCallback((event) => {
         startTimeRef.current = Date.now();
         startPosRef.current = { x: event.clientX, y: event.clientY };
-        document.addEventListener("pointerup", onPointerUp);
+        const ownerDocument = getOwnerDocument(event.currentTarget) ?? document;
+        tapDocumentRef.current = ownerDocument;
+        ownerDocument.addEventListener("pointerup", onPointerUp);
     }, [onPointerUp]);
     // Add a ref. makeEditable renders way too often
     const handleKeyDownRef = useCallbackRef(handleKeyDown);

package/dist/esm/hooks/use-structured-reference-selection.d.ts

@@ -11,12 +11,12 @@ export declare const useOnStructuredReferenceSelection: ({ tables, getSheetName,
         endColumnIndex: number;
         startRowIndex: number;
         endRowIndex: number;
-        sheetId: number;
     } | {
         startColumnIndex: number;
         endColumnIndex: number;
         startRowIndex: number;
         endRowIndex: number;
+        sheetId: number;
     };
     sheetName: string | undefined;
 } | undefined;

package/dist/esm/hooks/use-structured-reference-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-structured-reference-selection.d.ts","sourceRoot":"","sources":["../../../hooks/use-structured-reference-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,iCAAiC,GAAI,2BAG/C;IACD,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,YAAY,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;CAC/C,eAGc,MAAM,QACT,aAAa,GAAG,SAAS,aACpB,MAAM,GAAG,SAAS,eAChB,MAAM,EAAE,GAAG,SAAS,WACxB,OAAO,GAAG,SAAS,gBACd,WAAW,CAAC,aAAa,CAAC;;;;;;;;;;;;;;aA6H7C,CAAC"}
+{"version":3,"file":"use-structured-reference-selection.d.ts","sourceRoot":"","sources":["../../../hooks/use-structured-reference-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,iCAAiC,GAAI,2BAG/C;IACD,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,YAAY,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;CAC/C,eAGc,MAAM,QACT,aAAa,GAAG,SAAS,aACpB,MAAM,GAAG,SAAS,eAChB,MAAM,EAAE,GAAG,SAAS,WACxB,OAAO,GAAG,SAAS,gBACd,WAAW,CAAC,aAAa,CAAC;;;;;;;;;;;;;;aA8I7C,CAAC"}

package/dist/esm/hooks/use-structured-reference-selection.js

@@ -51,6 +51,22 @@ export const useOnStructuredReferenceSelection = ({ tables, getSheetName, }) =>
                     sheetName,
                 };
             }
+            // Totals row only (the table's last row); nothing to highlight while it is off.
+            if (specialItem === "#Totals") {
+                if (!totalRow) {
+                    return undefined;
+                }
+                return {
+                    range: {
+                        ...range,
+                        startColumnIndex,
+                        endColumnIndex,
+                        startRowIndex: range.endRowIndex,
+                        endRowIndex: range.endRowIndex,
+                    },
+                    sheetName,
+                };
+            }
             // All
             if (specialItem === "#All") {
                 return {

package/dist/esm/hooks/use-table-hit-zones.d.ts

@@ -0,0 +1,61 @@
+import type { CellInterface, CellPosition, GridRange, PosXYRequired, ScrollCoords, SelectionArea } from "@rowsncolumns/grid";
+import type React from "react";
+import type { CanvasGridProps } from "../components/canvas-grid/typings";
+import type { TableView } from "../types";
+/** Width of the edge bands (px, in grid coordinates) that count as a table hit zone. */
+export declare const TABLE_HIT_BAND = 4;
+export type TableHitZone = {
+    /**
+     * `column`: the top edge of a header cell (selects the column data, then
+     * the entire table column). `corner`: the header's top-left corner (selects
+     * the data body, then the whole table). `row`: the left edge of the first
+     * column (selects the table row).
+     */
+    kind: "column" | "corner" | "row";
+    table: TableView;
+    cell: CellInterface;
+};
+/** Excel's black selection arrows: down on a header edge, right on a row edge, diagonal on the corner. */
+export declare const TABLE_HIT_CURSORS: Record<TableHitZone["kind"], string>;
+/**
+ * Classify a pointer position inside `cell` against the table it belongs to.
+ * `offset` is the pointer's position relative to the cell's top-left corner.
+ */
+export declare const getTableHitZone: (table: TableView | undefined, cell: CellInterface, offset: {
+    x: number;
+    y: number;
+}, band?: number) => TableHitZone | undefined;
+/**
+ * The range a click on `zone` selects, given the single selected area (if
+ * any): a header edge selects the column data first and the entire table
+ * column on the next click; the corner toggles data body ↔ whole table; a row
+ * edge selects the table row.
+ */
+export declare const getTableHitZoneRange: (zone: TableHitZone, current: GridRange | undefined) => GridRange;
+export type UseTableHitZonesOptions = {
+    sheetId: number;
+    tables: CanvasGridProps["tables"];
+    selections: SelectionArea[];
+    frozenRows: number;
+    frozenColumns: number;
+    getCellCoordsFromOffset: (x: number, y: number) => CellInterface | undefined;
+    getRelativePositionFromOffset: (x: number, y: number) => PosXYRequired | null | undefined;
+    getCellOffsetFromCoords: (cell: CellInterface) => CellPosition | undefined;
+    getScrollPosition: () => ScrollCoords | undefined;
+    /** Replaces the selection with `range`, active cell at its top-left. */
+    onSelectRange: (sheetId: number, range: GridRange) => void;
+};
+/**
+ * Excel's table hit zones: hovering the top edge of a header cell, the
+ * header's top-left corner or the left edge of a row shows the black
+ * selection arrow; a click there selects the table column data / body / row
+ * instead of starting a cell selection.
+ */
+export declare const useTableHitZones: ({ sheetId, tables, selections, frozenRows, frozenColumns, getCellCoordsFromOffset, getRelativePositionFromOffset, getCellOffsetFromCoords, getScrollPosition, onSelectRange, }: UseTableHitZonesOptions) => {
+    hitZone: TableHitZone | undefined;
+    cursor: string | undefined;
+    onMouseMove: (e: React.MouseEvent<HTMLElement>) => void;
+    onMouseDown: (e: React.MouseEvent<HTMLElement>) => boolean;
+    clearHitZone: () => void;
+};
+//# sourceMappingURL=use-table-hit-zones.d.ts.map

package/dist/esm/hooks/use-table-hit-zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-table-hit-zones.d.ts","sourceRoot":"","sources":["../../../hooks/use-table-hit-zones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EACT,aAAa,EACb,YAAY,EACZ,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAS/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,wFAAwF;AACxF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC;CACrB,CAAC;AAOF,0GAA0G;AAC1G,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,CAIlE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,SAAS,GAAG,SAAS,EAC5B,MAAM,aAAa,EACnB,QAAQ;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAChC,aAAqB,KACpB,YAAY,GAAG,SA0BjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,YAAY,EAClB,SAAS,SAAS,GAAG,SAAS,KAC7B,SA+BF,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAClC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;IAC7E,6BAA6B,EAAE,CAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,KACN,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,uBAAuB,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,YAAY,GAAG,SAAS,CAAC;IAC3E,iBAAiB,EAAE,MAAM,YAAY,GAAG,SAAS,CAAC;IAClD,wEAAwE;IACxE,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC5D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,gLAW9B,uBAAuB;;;qBAyClB,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC;qBAqB7B,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC;;CA4BpC,CAAC"}

package/dist/esm/hooks/use-table-hit-zones.js

@@ -0,0 +1,146 @@
+import { useCallback, useState } from "react";
+import { findActiveTableWithinCell, getTableBodyRange, getTableColumnSelectRange, getTableRowSelectRange, } from "../api/table";
+/** Width of the edge bands (px, in grid coordinates) that count as a table hit zone. */
+export const TABLE_HIT_BAND = 4;
+const arrowCursor = (rotate, fallback) => `url("data:image/svg+xml;utf8,${encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16'><g transform='rotate(${rotate} 8 8)'><path d='M8 1v10.5M4 8l4 4 4-4' fill='none' stroke='#fff' stroke-width='4' stroke-linecap='round' stroke-linejoin='round'/><path d='M8 1v10.5M4 8l4 4 4-4' fill='none' stroke='#000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/></g></svg>`)}") 8 8, ${fallback}`;
+/** Excel's black selection arrows: down on a header edge, right on a row edge, diagonal on the corner. */
+export const TABLE_HIT_CURSORS = {
+    column: arrowCursor(0, "default"),
+    row: arrowCursor(-90, "default"),
+    corner: arrowCursor(-45, "default"),
+};
+/**
+ * Classify a pointer position inside `cell` against the table it belongs to.
+ * `offset` is the pointer's position relative to the cell's top-left corner.
+ */
+export const getTableHitZone = (table, cell, offset, band = TABLE_HIT_BAND) => {
+    if (!table) {
+        return undefined;
+    }
+    const { range } = table;
+    const isFirstRow = cell.rowIndex === range.startRowIndex;
+    const isFirstColumn = cell.columnIndex === range.startColumnIndex;
+    const nearTop = offset.y >= 0 && offset.y < band;
+    const nearLeft = offset.x >= 0 && offset.x < band;
+    if (isFirstRow &&
+        isFirstColumn &&
+        offset.x >= 0 &&
+        offset.y >= 0 &&
+        offset.x < band * 2 &&
+        offset.y < band * 2) {
+        return { kind: "corner", table, cell };
+    }
+    if (isFirstRow && nearTop) {
+        return { kind: "column", table, cell };
+    }
+    if (isFirstColumn && nearLeft) {
+        return { kind: "row", table, cell };
+    }
+    return undefined;
+};
+/**
+ * The range a click on `zone` selects, given the single selected area (if
+ * any): a header edge selects the column data first and the entire table
+ * column on the next click; the corner toggles data body ↔ whole table; a row
+ * edge selects the table row.
+ */
+export const getTableHitZoneRange = (zone, current) => {
+    const { table, cell } = zone;
+    const columns = { start: cell.columnIndex, end: cell.columnIndex };
+    switch (zone.kind) {
+        case "column":
+            return (getTableColumnSelectRange(table, columns, current) ?? {
+                ...table.range,
+                startColumnIndex: cell.columnIndex,
+                endColumnIndex: cell.columnIndex,
+            });
+        case "corner": {
+            const body = getTableBodyRange(table);
+            const isBody = !!current &&
+                current.startRowIndex === body.startRowIndex &&
+                current.endRowIndex === body.endRowIndex &&
+                current.startColumnIndex === body.startColumnIndex &&
+                current.endColumnIndex === body.endColumnIndex;
+            return isBody ? { ...table.range } : body;
+        }
+        case "row":
+            return (getTableRowSelectRange(table, { start: cell.rowIndex, end: cell.rowIndex }, undefined) ?? { ...table.range });
+    }
+};
+/**
+ * Excel's table hit zones: hovering the top edge of a header cell, the
+ * header's top-left corner or the left edge of a row shows the black
+ * selection arrow; a click there selects the table column data / body / row
+ * instead of starting a cell selection.
+ */
+export const useTableHitZones = ({ sheetId, tables, selections, frozenRows, frozenColumns, getCellCoordsFromOffset, getRelativePositionFromOffset, getCellOffsetFromCoords, getScrollPosition, onSelectRange, }) => {
+    const [hitZone, setHitZone] = useState();
+    const hitZoneAt = useCallback((clientX, clientY) => {
+        const cell = getCellCoordsFromOffset(clientX, clientY);
+        if (!cell) {
+            return undefined;
+        }
+        const table = findActiveTableWithinCell(sheetId, cell, tables);
+        if (!table) {
+            return undefined;
+        }
+        const position = getRelativePositionFromOffset(clientX, clientY);
+        const cellPosition = getCellOffsetFromCoords(cell);
+        if (!position || !cellPosition) {
+            return undefined;
+        }
+        const { scrollLeft = 0, scrollTop = 0 } = getScrollPosition() ?? {};
+        // Frozen rows / columns do not scroll.
+        const x = position.x +
+            (cell.columnIndex < frozenColumns ? 0 : scrollLeft) -
+            cellPosition.x;
+        const y = position.y + (cell.rowIndex < frozenRows ? 0 : scrollTop) - cellPosition.y;
+        return getTableHitZone(table, cell, { x, y });
+    }, [
+        sheetId,
+        tables,
+        frozenRows,
+        frozenColumns,
+        getCellCoordsFromOffset,
+        getRelativePositionFromOffset,
+        getCellOffsetFromCoords,
+        getScrollPosition,
+    ]);
+    const onMouseMove = useCallback((e) => {
+        const next = tables?.length ? hitZoneAt(e.clientX, e.clientY) : undefined;
+        setHitZone((prev) => prev?.kind === next?.kind &&
+            prev?.table.id === next?.table.id &&
+            prev?.cell.rowIndex === next?.cell.rowIndex &&
+            prev?.cell.columnIndex === next?.cell.columnIndex
+            ? prev
+            : next);
+    }, [tables, hitZoneAt]);
+    const clearHitZone = useCallback(() => setHitZone(undefined), []);
+    /**
+     * Returns true when the mousedown landed on a hit zone and selected the
+     * table part — the caller then skips the regular cell selection.
+     */
+    const onMouseDown = useCallback((e) => {
+        if (!tables?.length ||
+            e.button !== 0 ||
+            e.shiftKey ||
+            e.ctrlKey ||
+            e.metaKey) {
+            return false;
+        }
+        const zone = hitZoneAt(e.clientX, e.clientY);
+        if (!zone) {
+            return false;
+        }
+        const current = selections.length === 1 ? selections[0].range : undefined;
+        onSelectRange(sheetId, getTableHitZoneRange(zone, current));
+        return true;
+    }, [tables, hitZoneAt, selections, onSelectRange, sheetId]);
+    return {
+        hitZone,
+        cursor: hitZone ? TABLE_HIT_CURSORS[hitZone.kind] : undefined,
+        onMouseMove,
+        onMouseDown,
+        clearHitZone,
+    };
+};

package/dist/esm/hooks/use-table-resizer.d.ts

@@ -14,6 +14,13 @@ type UseTableResizerProps = {
     scrollToCell: (cell: OptionalCellInterface, align?: Align | undefined) => void | undefined;
     focusSheet(): void;
 };
+/**
+ * The smallest table Excel's resize handle allows: the header row (when shown) plus one data row
+ * plus the totals row (when shown), and one column. The pointer may travel above / left of that
+ * while dragging, so the drop point is clamped the same way the drag preview is — releasing above
+ * the header must not produce a headerless or inverted range.
+ */
+export declare const clampTableCornerCell: (cell: CellInterface, table: Pick<TableView, "range" | "headerRow" | "totalRow">) => CellInterface;
 export declare const useTableResizer: ({ sheetId, tables, theme, newSelection, modifySelection, clearSelections, onResizeTable, getCellCoordsFromOffset, scrollToCell, focusSheet, }: UseTableResizerProps) => {
     tableResizers: React.JSX.Element[] | undefined;
     isResizingTable: boolean;