@ricsam/react-spreadsheets 0.0.7 → 0.0.8

package/README.md

@@ -138,6 +138,68 @@ keyboard and edit selection state independently. For `FormulaWorkbook`, pass a
 controlled `activeSheet` if the editor should reveal a reference on another
 sheet; the same `customCellStyle` prop is forwarded to its active sheet.
 
+For the range currently being inserted into a formula, use selection-manager's
+reference-picking mode instead. It preserves the primary/editing selection and
+the grid renders the picked range with an independent animated border:
+
+```tsx
+<Spreadsheet
+  rowCount={1_000}
+  columnCount={50}
+  selection={{
+    effects(manager) {
+      const stop = manager.listenToReferenceSelection((event) => {
+        if (event.phase === "start" || event.phase === "change") {
+          updateFormulaReference(event.range);
+        }
+      });
+
+      manager.beginReferenceSelection({
+        editedRange: {
+          start: { row: 1, col: 3 },
+          end: {
+            row: { type: "number", value: 1 },
+            col: { type: "number", value: 3 },
+          },
+        },
+      });
+      return () => {
+        stop();
+        manager.endReferenceSelection();
+      };
+    },
+  }}
+/>
+```
+
+### Data-aware keyboard navigation
+
+`Cmd/Ctrl + Arrow` jumps through populated cells and reveals the destination;
+adding Shift extends the primary selection. Plain `Spreadsheet` derives its
+used range and jump targets from non-empty `cellData`. `FormulaSheet` also
+supplies table bounds from the formula engine, so navigation inside a table
+respects its data body.
+
+Override any part of that behavior through `selection.navigation`:
+
+```tsx
+<Spreadsheet
+  rowCount={100_000}
+  columnCount={200}
+  selection={{
+    navigation: {
+      getUsedRange: () => model.usedRange,
+      getTableAt: (cell) => model.tableAt(cell),
+      resolveTarget: (request) => model.resolveJump(request),
+    },
+  }}
+/>
+```
+
+The imperative `SpreadsheetRef.scrollToCell({ row, col }, { align })` reveals a
+cell without changing selection. Alignment is `"nearest"` by default, with
+`"start"` and `"end"` available for explicit positioning.
+
 ## Theming
 
 All colors, fonts and sizes are CSS custom properties. The package only ever
@@ -227,11 +289,12 @@ Per-cell styling is done in JS:
 | --- | --- |
 | `cellData` | `Map<string, SerializedCellValue>` keyed by A1 reference. Omit for uncontrolled mode. |
 | `onCellDataChange` | Called with the next map after an edit, paste or fill. |
+| `rowCount` / `columnCount` | Finite grid dimensions. Omit either dimension for an unbounded axis. |
 | `columnWidths` / `rowHeights` | Controlled sizing, keyed by column letter / 1-based row. |
 | `customCellStyle` | Per-cell `CSSProperties`. |
 | `customCellRenderer` | Per-cell React node. |
 | `parseValue` | Coerce raw editor strings (e.g. text → number) before storing. |
-| `selection` | Selection state, callbacks and `effects(selectionManager)` for copy/paste/fill hooks. |
+| `selection` | Selection state, navigation model, and `effects(selectionManager)` for copy/paste/fill/reference hooks. |
 | `components` + `overlayChildren` | Floating overlays anchored to the grid, optionally snapped to cell edges. |
 
 ## Development

package/dist/cjs/lib.cjs

@@ -1457,6 +1457,99 @@ var withReadableTextColor = (style) => {
   return { ...style, color };
 };
 var hasBorderStyle = (style) => Boolean(style?.borderColor || style?.borderTopColor || style?.borderRightColor || style?.borderBottomColor || style?.borderLeftColor);
+var normalizeFiniteCount = (count) => {
+  if (count === undefined || count === Infinity)
+    return;
+  if (!Number.isFinite(count))
+    return 0;
+  return Math.max(0, Math.floor(count));
+};
+var countToSelectionBound = (count) => count === undefined ? { type: "infinity" } : { type: "number", value: count };
+var alignScrollOffset = (current, itemStart, itemEnd, viewportSize, align) => {
+  if (viewportSize <= 0)
+    return current;
+  if (align === "start")
+    return itemStart;
+  if (align === "end")
+    return itemEnd - viewportSize;
+  if (itemStart < current)
+    return itemStart;
+  if (itemEnd > current + viewportSize)
+    return itemEnd - viewportSize;
+  return current;
+};
+var hasCellData = (value) => value !== undefined && value !== "";
+var getSparseUsedRange = (cellData, rowCount, columnCount) => {
+  let minRow = Infinity;
+  let maxRow = -1;
+  let minCol = Infinity;
+  let maxCol = -1;
+  for (const [reference, value] of cellData) {
+    if (!hasCellData(value))
+      continue;
+    let rowIndex;
+    let columnIndex;
+    try {
+      ({ rowIndex, columnIndex } = parseCellReference(reference));
+    } catch {
+      continue;
+    }
+    if (rowIndex < 0 || columnIndex < 0 || rowCount !== undefined && rowIndex >= rowCount || columnCount !== undefined && columnIndex >= columnCount) {
+      continue;
+    }
+    minRow = Math.min(minRow, rowIndex);
+    maxRow = Math.max(maxRow, rowIndex);
+    minCol = Math.min(minCol, columnIndex);
+    maxCol = Math.max(maxCol, columnIndex);
+  }
+  if (maxRow < 0 || maxCol < 0)
+    return;
+  return {
+    start: { row: minRow, col: minCol },
+    end: {
+      row: { type: "number", value: maxRow },
+      col: { type: "number", value: maxCol }
+    }
+  };
+};
+var resolveSparseNavigationTarget = (request, cellData) => {
+  if (request.kind !== "jump" || request.table)
+    return;
+  const isVertical = request.direction === "up" || request.direction === "down";
+  const movingForward = request.direction === "down" || request.direction === "right";
+  const originAxis = isVertical ? request.origin.row : request.origin.col;
+  const fixedAxis = isVertical ? request.origin.col : request.origin.row;
+  const occupied = new Set;
+  for (const [reference, value] of cellData) {
+    if (!hasCellData(value))
+      continue;
+    let rowIndex;
+    let columnIndex;
+    try {
+      ({ rowIndex, columnIndex } = parseCellReference(reference));
+    } catch {
+      continue;
+    }
+    if ((isVertical ? columnIndex : rowIndex) === fixedAxis) {
+      occupied.add(isVertical ? rowIndex : columnIndex);
+    }
+  }
+  const step = movingForward ? 1 : -1;
+  let targetAxis;
+  if (occupied.has(originAxis + step)) {
+    targetAxis = originAxis + step;
+    while (occupied.has(targetAxis + step))
+      targetAxis += step;
+  } else {
+    const candidates = [...occupied].filter((index) => movingForward ? index > originAxis : index < originAxis);
+    if (candidates.length > 0) {
+      targetAxis = movingForward ? Math.min(...candidates) : Math.max(...candidates);
+    }
+  }
+  if (targetAxis === undefined)
+    return;
+  return isVertical ? { row: targetAxis, col: request.origin.col } : { row: request.origin.row, col: targetAxis };
+};
 var CellComponent = import_react4.default.memo(({
   value,
   row,
@@ -1760,6 +1853,8 @@ var Spreadsheet = import_react4.forwardRef(({
   cellData: controlledCellData,
   onCellDataChange,
   onCellDataChangeError,
+  rowCount,
+  columnCount,
   columnWidths: controlledColumnWidths,
   onColumnWidthsChange,
   rowHeights: controlledRowHeights,
@@ -1781,14 +1876,35 @@ var Spreadsheet = import_react4.forwardRef(({
   const [containerDivRef, setContainerDivRef] = import_react4.useState(null);
   const colorScheme = useColorScheme(containerDivRef);
   const gridLineProbeRef = import_react4.useRef(null);
+  const [internalCellData, setInternalCellData] = import_react4.useState(new Map);
+  const [retryingEdit, setRetryingEdit] = import_react4.useState(null);
+  const retryingEditVersionRef = import_react4.useRef(0);
+  const cellData = controlledCellData ?? internalCellData;
+  const cellDataRef = import_react4.useRef(cellData);
+  cellDataRef.current = cellData;
+  const finiteRowCount = normalizeFiniteCount(rowCount);
+  const finiteColumnCount = normalizeFiniteCount(columnCount);
+  const gridCountsRef = import_react4.useRef({ rows: finiteRowCount, columns: finiteColumnCount });
+  gridCountsRef.current = { rows: finiteRowCount, columns: finiteColumnCount };
+  const getNumRows = import_react4.useCallback(() => countToSelectionBound(gridCountsRef.current.rows), []);
+  const getNumCols = import_react4.useCallback(() => countToSelectionBound(gridCountsRef.current.columns), []);
+  const getDefaultUsedRange = import_react4.useCallback(() => getSparseUsedRange(cellDataRef.current, gridCountsRef.current.rows, gridCountsRef.current.columns), []);
+  const defaultResolveTarget = import_react4.useCallback((request) => resolveSparseNavigationTarget(request, cellDataRef.current), []);
+  const consumerNavigation = selection?.navigation;
+  const navigation = import_react4.useMemo(() => ({
+    getUsedRange: consumerNavigation?.getUsedRange ?? getDefaultUsedRange,
+    ...consumerNavigation?.getTableAt ? { getTableAt: consumerNavigation.getTableAt } : {},
+    resolveTarget: consumerNavigation?.resolveTarget ?? defaultResolveTarget
+  }), [consumerNavigation, defaultResolveTarget, getDefaultUsedRange]);
   const selectionManager = import_selection_manager.useInitializeSelectionManager({
-    getNumCols: () => ({ type: "infinity" }),
-    getNumRows: () => ({ type: "infinity" }),
+    getNumCols,
+    getNumRows,
     initialState: selection?.initialState,
     state: selection?.state,
     onStateChange: selection?.onStateChange,
     containerElement: containerDivRef,
     formats: selection?.formats,
+    navigation,
     disableAutoClipboard: true
   });
   const effects = selection?.effects;
@@ -1797,12 +1913,6 @@ var Spreadsheet = import_react4.forwardRef(({
       return effects(selectionManager);
     }
   }, [selectionManager, effects]);
-  const [internalCellData, setInternalCellData] = import_react4.useState(new Map);
-  const [retryingEdit, setRetryingEdit] = import_react4.useState(null);
-  const retryingEditVersionRef = import_react4.useRef(0);
-  const cellData = controlledCellData ?? internalCellData;
-  const cellDataRef = import_react4.useRef(cellData);
-  cellDataRef.current = cellData;
   const isControlled = controlledCellData !== undefined;
   const prevIsControlledRef = import_react4.useRef(isControlled);
   selectionManager.getCellsWithData = (area) => {
@@ -1978,7 +2088,7 @@ var Spreadsheet = import_react4.forwardRef(({
     ctx.lineWidth = 1;
     let x = gridDims.headerWidth;
     let colIndex = 0;
-    while (x < viewport.scrollX + gridDims.headerWidth) {
+    while (x < viewport.scrollX + gridDims.headerWidth && (finiteColumnCount === undefined || colIndex < finiteColumnCount)) {
       const colWidth = (columnWidths.get(indexToColumn(colIndex)) || DEFAULT_CELL_WIDTH) * viewport.zoom;
       if (x + colWidth > viewport.scrollX + gridDims.headerWidth) {
         break;
@@ -1986,7 +2096,7 @@ var Spreadsheet = import_react4.forwardRef(({
       x += colWidth;
       colIndex++;
     }
-    while (x - viewport.scrollX < width) {
+    while (x - viewport.scrollX < width && (finiteColumnCount === undefined || colIndex < finiteColumnCount)) {
       const drawX = x - viewport.scrollX;
       if (drawX >= gridDims.headerWidth && drawX <= width) {
         ctx.beginPath();
@@ -2000,7 +2110,7 @@ var Spreadsheet = import_react4.forwardRef(({
     }
     let y = gridDims.headerHeight;
     let rowNum = 1;
-    while (y < viewport.scrollY + gridDims.headerHeight) {
+    while (y < viewport.scrollY + gridDims.headerHeight && (finiteRowCount === undefined || rowNum <= finiteRowCount)) {
       const rowHeight = (rowHeights.get(rowNum) || DEFAULT_CELL_HEIGHT) * viewport.zoom;
       if (y + rowHeight > viewport.scrollY + gridDims.headerHeight) {
         break;
@@ -2008,7 +2118,7 @@ var Spreadsheet = import_react4.forwardRef(({
       y += rowHeight;
       rowNum++;
     }
-    while (y - viewport.scrollY < height) {
+    while (y - viewport.scrollY < height && (finiteRowCount === undefined || rowNum <= finiteRowCount)) {
       const drawY = y - viewport.scrollY;
       if (drawY >= gridDims.headerHeight && drawY <= height) {
         ctx.beginPath();
@@ -2022,6 +2132,8 @@ var Spreadsheet = import_react4.forwardRef(({
     }
   }, [
     columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
     gridDims.headerHeight,
     gridDims.headerWidth,
     height,
@@ -2039,7 +2151,7 @@ var Spreadsheet = import_react4.forwardRef(({
     const cells = [];
     let x = 0;
     let startCol = 0;
-    while (x < viewport.scrollX) {
+    while (x < viewport.scrollX && (finiteColumnCount === undefined || startCol < finiteColumnCount)) {
       const colWidth = (columnWidths.get(indexToColumn(startCol)) || DEFAULT_CELL_WIDTH) * viewport.zoom;
       if (x + colWidth > viewport.scrollX) {
         break;
@@ -2049,7 +2161,7 @@ var Spreadsheet = import_react4.forwardRef(({
     }
     let y = 0;
     let startRow = 0;
-    while (y < viewport.scrollY) {
+    while (y < viewport.scrollY && (finiteRowCount === undefined || startRow < finiteRowCount)) {
       const rowHeight = (rowHeights.get(startRow + 1) || DEFAULT_CELL_HEIGHT) * viewport.zoom;
       if (y + rowHeight > viewport.scrollY) {
         break;
@@ -2059,10 +2171,10 @@ var Spreadsheet = import_react4.forwardRef(({
     }
     let rowY = y;
     let row = startRow;
-    while (rowY < viewport.scrollY + height) {
+    while (rowY < viewport.scrollY + height && (finiteRowCount === undefined || row < finiteRowCount)) {
       let colX = x;
       let col = startCol;
-      while (colX < viewport.scrollX + width) {
+      while (colX < viewport.scrollX + width && (finiteColumnCount === undefined || col < finiteColumnCount)) {
         const colKey = indexToColumn(col);
         const rowNum = getRowNumber(row);
         const cellKey = `${colKey}${rowNum}`;
@@ -2083,6 +2195,8 @@ var Spreadsheet = import_react4.forwardRef(({
   }, [
     cellData,
     columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
     height,
     rowHeights,
     viewport.scrollX,
@@ -2110,6 +2224,64 @@ var Spreadsheet = import_react4.forwardRef(({
     }
     return { x, y };
   }, [columnWidths, rowHeights]);
+  const clampViewportOffsets = import_react4.useCallback((scrollX, scrollY, zoom) => {
+    const bodyWidth = Math.max(0, width - HEADER_WIDTH * zoom);
+    const bodyHeight = Math.max(0, height - HEADER_HEIGHT * zoom);
+    const maxScrollX = finiteColumnCount === undefined ? Infinity : Math.max(0, getColumnEdgePosition(finiteColumnCount, columnWidths) * zoom - bodyWidth);
+    const maxScrollY = finiteRowCount === undefined ? Infinity : Math.max(0, getRowEdgePosition(finiteRowCount, rowHeights) * zoom - bodyHeight);
+    return {
+      scrollX: Math.min(Math.max(0, scrollX), maxScrollX),
+      scrollY: Math.min(Math.max(0, scrollY), maxScrollY)
+    };
+  }, [columnWidths, finiteColumnCount, finiteRowCount, height, rowHeights, width]);
+  const revealCell = import_react4.useCallback((cell, options = {}) => {
+    if (finiteRowCount === 0 || finiteColumnCount === 0)
+      return;
+    if (!Number.isFinite(cell.row) || !Number.isFinite(cell.col))
+      return;
+    const requestedRow = Math.max(0, Math.floor(cell.row));
+    const requestedCol = Math.max(0, Math.floor(cell.col));
+    const row = finiteRowCount === undefined ? requestedRow : Math.min(requestedRow, finiteRowCount - 1);
+    const col = finiteColumnCount === undefined ? requestedCol : Math.min(requestedCol, finiteColumnCount - 1);
+    setViewport((previous) => {
+      const bodyWidth = Math.max(0, width - HEADER_WIDTH * previous.zoom);
+      const bodyHeight = Math.max(0, height - HEADER_HEIGHT * previous.zoom);
+      const left = getColumnEdgePosition(col, columnWidths) * previous.zoom;
+      const right = getColumnEdgePosition(col + 1, columnWidths) * previous.zoom;
+      const top = getRowEdgePosition(row, rowHeights) * previous.zoom;
+      const bottom = getRowEdgePosition(row + 1, rowHeights) * previous.zoom;
+      const desired = clampViewportOffsets(alignScrollOffset(previous.scrollX, left, right, bodyWidth, options.columnAlign ?? "nearest"), alignScrollOffset(previous.scrollY, top, bottom, bodyHeight, options.rowAlign ?? "nearest"), previous.zoom);
+      if (desired.scrollX === previous.scrollX && desired.scrollY === previous.scrollY) {
+        return previous;
+      }
+      return { ...previous, ...desired };
+    });
+  }, [
+    clampViewportOffsets,
+    columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
+    height,
+    rowHeights,
+    width
+  ]);
+  const scrollToCell = import_react4.useCallback((cell, options = {}) => {
+    const align = options.align ?? "nearest";
+    revealCell(cell, { rowAlign: align, columnAlign: align });
+  }, [revealCell]);
+  import_react4.useEffect(() => selectionManager.listenToViewportRequest((request) => {
+    const isVertical = request.direction === "up" || request.direction === "down";
+    revealCell(request.cell, {
+      rowAlign: isVertical ? request.align : "nearest",
+      columnAlign: isVertical ? "nearest" : request.align
+    });
+  }), [revealCell, selectionManager]);
+  import_react4.useEffect(() => {
+    setViewport((previous) => {
+      const next = clampViewportOffsets(previous.scrollX, previous.scrollY, previous.zoom);
+      return next.scrollX === previous.scrollX && next.scrollY === previous.scrollY ? previous : { ...previous, ...next };
+    });
+  }, [clampViewportOffsets]);
   import_react4.default.useEffect(() => {
     return selectionManager.listenToUpdateData((updates) => {
       const editingState = selectionManager.isEditing;
@@ -2184,12 +2356,11 @@ var Spreadsheet = import_react4.forwardRef(({
   const handleWheel = import_react4.useCallback((e) => {
     e.preventDefault();
     e.stopPropagation();
-    setViewport((prev) => ({
-      ...prev,
-      scrollX: Math.max(0, prev.scrollX + e.deltaX),
-      scrollY: Math.max(0, prev.scrollY + e.deltaY)
+    setViewport((previous) => ({
+      ...previous,
+      ...clampViewportOffsets(previous.scrollX + e.deltaX, previous.scrollY + e.deltaY, previous.zoom)
     }));
-  }, []);
+  }, [clampViewportOffsets]);
   const commitOverlayChildren = import_react4.useCallback((children) => {
     overlayChildrenRef.current = children;
     if (onOverlayChildrenChange) {
@@ -2608,7 +2779,7 @@ var Spreadsheet = import_react4.forwardRef(({
     const headers = [];
     let x = 0;
     let startCol = 0;
-    while (x < viewport.scrollX) {
+    while (x < viewport.scrollX && (finiteColumnCount === undefined || startCol < finiteColumnCount)) {
       const col = indexToColumn(startCol);
       const colWidth = getColumnWidth(col) * viewport.zoom;
       if (x + colWidth > viewport.scrollX) {
@@ -2617,7 +2788,7 @@ var Spreadsheet = import_react4.forwardRef(({
       x += colWidth;
       startCol++;
     }
-    while (x < viewport.scrollX + width) {
+    while (x < viewport.scrollX + width && (finiteColumnCount === undefined || startCol < finiteColumnCount)) {
       const col = indexToColumn(startCol);
       const colWidth = getColumnWidth(col) * viewport.zoom;
       headers.push({
@@ -2628,14 +2799,14 @@ var Spreadsheet = import_react4.forwardRef(({
       startCol++;
     }
     return headers;
-  }, [width, viewport, getColumnWidth]);
+  }, [finiteColumnCount, width, viewport, getColumnWidth]);
   const getVisibleRowHeaders = import_react4.useCallback(() => {
     if (!height)
       return [];
     const headers = [];
     let y = 0;
     let rowNum = 1;
-    while (y < viewport.scrollY) {
+    while (y < viewport.scrollY && (finiteRowCount === undefined || rowNum <= finiteRowCount)) {
       const rowHeight = getRowHeight(rowNum) * viewport.zoom;
       if (y + rowHeight > viewport.scrollY) {
         break;
@@ -2643,7 +2814,7 @@ var Spreadsheet = import_react4.forwardRef(({
       y += rowHeight;
       rowNum++;
     }
-    while (y < viewport.scrollY + height) {
+    while (y < viewport.scrollY + height && (finiteRowCount === undefined || rowNum <= finiteRowCount)) {
       const rowHeight = getRowHeight(rowNum) * viewport.zoom;
       headers.push({
         row: rowNum,
@@ -2653,7 +2824,7 @@ var Spreadsheet = import_react4.forwardRef(({
       rowNum++;
     }
     return headers;
-  }, [height, viewport, getRowHeight]);
+  }, [finiteRowCount, height, viewport, getRowHeight]);
   const { visibleOverlays, overlaysToRender } = import_react4.useMemo(() => {
     if (!width || !height || !overlayChildren) {
       return { visibleOverlays: [], overlaysToRender: [] };
@@ -2701,6 +2872,43 @@ var Spreadsheet = import_react4.forwardRef(({
   const visibleColumnHeaders = import_react4.default.useMemo(() => getVisibleColumnHeaders(), [getVisibleColumnHeaders]);
   const visibleRowHeaders = import_react4.default.useMemo(() => getVisibleRowHeaders(), [getVisibleRowHeaders]);
   const hasFocus = import_selection_manager.useSelectionManager(selectionManager, () => selectionManager.hasFocus);
+  const referenceSelection = import_selection_manager.useSelectionManager(selectionManager, () => selectionManager.referenceSelection);
+  const referenceSelectionRect = import_react4.useMemo(() => {
+    if (referenceSelection.type === "none")
+      return;
+    if (finiteRowCount === 0 || finiteColumnCount === 0)
+      return;
+    const range = referenceSelection.range;
+    const lastVisibleRow = visibleCells.reduce((maximum, cell) => Math.max(maximum, cell.row - 1), range.start.row);
+    const lastVisibleCol = visibleCells.reduce((maximum, cell) => Math.max(maximum, columnToIndex(cell.col)), range.start.col);
+    const rawEndRow = range.end.row.type === "number" ? range.end.row.value : finiteRowCount === undefined ? lastVisibleRow : finiteRowCount - 1;
+    const rawEndCol = range.end.col.type === "number" ? range.end.col.value : finiteColumnCount === undefined ? lastVisibleCol : finiteColumnCount - 1;
+    const maxRow = finiteRowCount === undefined ? Infinity : finiteRowCount - 1;
+    const maxCol = finiteColumnCount === undefined ? Infinity : finiteColumnCount - 1;
+    const startRow = Math.min(Math.max(0, Math.min(range.start.row, rawEndRow)), maxRow);
+    const endRow = Math.min(Math.max(0, Math.max(range.start.row, rawEndRow)), maxRow);
+    const startCol = Math.min(Math.max(0, Math.min(range.start.col, rawEndCol)), maxCol);
+    const endCol = Math.min(Math.max(0, Math.max(range.start.col, rawEndCol)), maxCol);
+    const rect = getRectFromCellSnapAnchor({
+      startCol,
+      startRow,
+      endCol: endCol + 1,
+      endRow: endRow + 1
+    }, columnWidths, rowHeights);
+    return {
+      left: HEADER_WIDTH + rect.x,
+      top: HEADER_HEIGHT + rect.y,
+      width: rect.width,
+      height: rect.height
+    };
+  }, [
+    columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
+    referenceSelection,
+    rowHeights,
+    visibleCells
+  ]);
   import_react4.default.useEffect(() => {
     if (!containerDivRef || !hasFocus || !parentSelected) {
       return;
@@ -2718,8 +2926,9 @@ var Spreadsheet = import_react4.forwardRef(({
     },
     blur: () => {
       selectionManager.blur();
-    }
-  }), [selectionManager]);
+    },
+    scrollToCell
+  }), [scrollToCell, selectionManager]);
   return /* @__PURE__ */ jsx_runtime3.jsx("div", {
     className: cn("rsp-root", className),
     "data-rsp-scheme": colorScheme,
@@ -2823,28 +3032,38 @@ var Spreadsheet = import_react4.forwardRef(({
               zIndex: 40
             }
           }),
-          /* @__PURE__ */ jsx_runtime3.jsx("div", {
+          /* @__PURE__ */ jsx_runtime3.jsxs("div", {
             className: "rsp-cells",
             "data-testid": "spreadsheet-cells",
             style: {
               transform: `translate(${-viewport.scrollX}px, ${-viewport.scrollY}px) scale(${viewport.zoom})`,
               transformOrigin: "0 0"
             },
-            children: visibleCells.map((cell) => /* @__PURE__ */ jsx_runtime3.jsx(CellComponent, {
-              value: cellData.get(`${cell.col}${cell.row}`) ?? "",
-              row: cell.row,
-              col: cell.col,
-              selectionManager,
-              cellToPixelBase,
-              getColumnWidth,
-              getRowHeight,
-              customCellStyle,
-              customCellRenderer,
-              inputValue: cellData.get(`${cell.col}${cell.row}`) ?? "",
-              editInputVersion: retryingEdit?.rowIndex === cell.row - 1 && retryingEdit?.colIndex === columnToIndex(cell.col) ? retryingEdit.version : 0,
-              width,
-              height
-            }, `${cell.col}${cell.row}`))
+            children: [
+              visibleCells.map((cell) => /* @__PURE__ */ jsx_runtime3.jsx(CellComponent, {
+                value: cellData.get(`${cell.col}${cell.row}`) ?? "",
+                row: cell.row,
+                col: cell.col,
+                selectionManager,
+                cellToPixelBase,
+                getColumnWidth,
+                getRowHeight,
+                customCellStyle,
+                customCellRenderer,
+                inputValue: cellData.get(`${cell.col}${cell.row}`) ?? "",
+                editInputVersion: retryingEdit?.rowIndex === cell.row - 1 && retryingEdit?.colIndex === columnToIndex(cell.col) ? retryingEdit.version : 0,
+                width,
+                height
+              }, `${cell.col}${cell.row}`)),
+              referenceSelectionRect && referenceSelection.type !== "none" && /* @__PURE__ */ jsx_runtime3.jsx("div", {
+                "aria-hidden": "true",
+                className: cn("rsp-reference-selection", `rsp-reference-selection-${referenceSelection.type}`),
+                "data-testid": "spreadsheet-reference-selection",
+                "data-reference-id": referenceSelection.id,
+                "data-reference-phase": referenceSelection.type,
+                style: referenceSelectionRect
+              })
+            ]
           }),
           components && overlayChildren && overlayChildren.length > 0 && /* @__PURE__ */ jsx_runtime3.jsxs("div", {
             ref: overlayContainerRef,
@@ -3450,6 +3669,42 @@ function FormulaSheet({
   const clipboardManager = import_react6.default.useMemo(() => controlledClipboardManager ?? new WorkbookClipboardManager(engine), [controlledClipboardManager, engine]);
   const state = useEngine(engine);
   const sheet = state.workbooks.get(workbookName)?.sheets.get(sheetName);
+  const getEngineTableAt = import_react6.useCallback((cell) => {
+    const table = engine.isCellInTable({
+      workbookName,
+      sheetName,
+      rowIndex: cell.row,
+      colIndex: cell.col
+    });
+    if (!table)
+      return;
+    const endRow = table.endRow.type === "number" ? { type: "number", value: table.endRow.value } : { type: "infinity" };
+    const endCol = {
+      type: "number",
+      value: table.start.colIndex + table.headers.size - 1
+    };
+    const hasDataRows = endRow.type === "infinity" || endRow.value > table.start.rowIndex;
+    return {
+      id: `${table.workbookName}/${table.name}`,
+      bounds: {
+        start: { row: table.start.rowIndex, col: table.start.colIndex },
+        end: { row: endRow, col: endCol }
+      },
+      ...hasDataRows ? {
+        dataBounds: {
+          start: {
+            row: table.start.rowIndex + 1,
+            col: table.start.colIndex
+          },
+          end: { row: endRow, col: endCol }
+        }
+      } : {}
+    };
+  }, [engine, sheetName, workbookName]);
+  const formulaNavigation = import_react6.useMemo(() => ({
+    ...selection?.navigation,
+    getTableAt: selection?.navigation?.getTableAt ?? getEngineTableAt
+  }), [getEngineTableAt, selection?.navigation]);
   const onCellDataChange = import_react6.useCallback((updatedSpreadsheet) => {
     const data = new Map(updatedSpreadsheet);
     data.forEach((value, key) => {
@@ -3623,6 +3878,7 @@ function FormulaSheet({
           parentSelected: isSelected,
           selection: {
             ...selection,
+            navigation: formulaNavigation,
             effects: selectionManagerEffects
           },
           containerProps: isSelected && selectedArea ? {
@@ -4161,4 +4417,4 @@ var useClickAway = (ref, callback) => {
   }, [ref, callback]);
 };
 
-//# debugId=4874F9DF8699906864756E2164756E21
+//# debugId=5EB66D4C826F4D2464756E2164756E21