@ricsam/react-spreadsheets 0.0.7 → 0.0.9

package/dist/mjs/lib.mjs

@@ -1349,6 +1349,124 @@ 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 (itemEnd - itemStart > viewportSize) {
+    if (itemEnd <= current)
+      return itemEnd - viewportSize;
+    if (itemStart >= current + viewportSize)
+      return itemStart;
+    return current;
+  }
+  if (itemStart < current)
+    return itemStart;
+  if (itemEnd > current + viewportSize)
+    return itemEnd - viewportSize;
+  return current;
+};
+var normalizeScrollRangeAxis = (start, end, finiteCount) => {
+  if (!Number.isFinite(start) || end.type === "number" && !Number.isFinite(end.value)) {
+    return;
+  }
+  const normalizedStart = Math.max(0, Math.floor(start));
+  const normalizedEnd = end.type === "infinity" ? finiteCount === undefined ? normalizedStart : Math.max(0, finiteCount - 1) : Math.max(0, Math.floor(end.value));
+  const lower = Math.min(normalizedStart, normalizedEnd);
+  const upper = Math.max(normalizedStart, normalizedEnd);
+  if (finiteCount === undefined)
+    return { start: lower, end: upper };
+  if (finiteCount === 0)
+    return;
+  const lastIndex = finiteCount - 1;
+  return {
+    start: Math.min(lower, lastIndex),
+    end: Math.min(upper, lastIndex)
+  };
+};
+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 = React2.memo(({
   value,
   row,
@@ -1652,6 +1770,8 @@ var Spreadsheet = forwardRef(({
   cellData: controlledCellData,
   onCellDataChange,
   onCellDataChangeError,
+  rowCount,
+  columnCount,
   columnWidths: controlledColumnWidths,
   onColumnWidthsChange,
   rowHeights: controlledRowHeights,
@@ -1673,14 +1793,35 @@ var Spreadsheet = forwardRef(({
   const [containerDivRef, setContainerDivRef] = useState4(null);
   const colorScheme = useColorScheme(containerDivRef);
   const gridLineProbeRef = useRef3(null);
+  const [internalCellData, setInternalCellData] = useState4(new Map);
+  const [retryingEdit, setRetryingEdit] = useState4(null);
+  const retryingEditVersionRef = useRef3(0);
+  const cellData = controlledCellData ?? internalCellData;
+  const cellDataRef = useRef3(cellData);
+  cellDataRef.current = cellData;
+  const finiteRowCount = normalizeFiniteCount(rowCount);
+  const finiteColumnCount = normalizeFiniteCount(columnCount);
+  const gridCountsRef = useRef3({ rows: finiteRowCount, columns: finiteColumnCount });
+  gridCountsRef.current = { rows: finiteRowCount, columns: finiteColumnCount };
+  const getNumRows = useCallback3(() => countToSelectionBound(gridCountsRef.current.rows), []);
+  const getNumCols = useCallback3(() => countToSelectionBound(gridCountsRef.current.columns), []);
+  const getDefaultUsedRange = useCallback3(() => getSparseUsedRange(cellDataRef.current, gridCountsRef.current.rows, gridCountsRef.current.columns), []);
+  const defaultResolveTarget = useCallback3((request) => resolveSparseNavigationTarget(request, cellDataRef.current), []);
+  const consumerNavigation = selection?.navigation;
+  const navigation = useMemo(() => ({
+    getUsedRange: consumerNavigation?.getUsedRange ?? getDefaultUsedRange,
+    ...consumerNavigation?.getTableAt ? { getTableAt: consumerNavigation.getTableAt } : {},
+    resolveTarget: consumerNavigation?.resolveTarget ?? defaultResolveTarget
+  }), [consumerNavigation, defaultResolveTarget, getDefaultUsedRange]);
   const selectionManager = 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;
@@ -1689,12 +1830,6 @@ var Spreadsheet = forwardRef(({
       return effects(selectionManager);
     }
   }, [selectionManager, effects]);
-  const [internalCellData, setInternalCellData] = useState4(new Map);
-  const [retryingEdit, setRetryingEdit] = useState4(null);
-  const retryingEditVersionRef = useRef3(0);
-  const cellData = controlledCellData ?? internalCellData;
-  const cellDataRef = useRef3(cellData);
-  cellDataRef.current = cellData;
   const isControlled = controlledCellData !== undefined;
   const prevIsControlledRef = useRef3(isControlled);
   selectionManager.getCellsWithData = (area) => {
@@ -1870,7 +2005,7 @@ var Spreadsheet = 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;
@@ -1878,7 +2013,7 @@ var Spreadsheet = 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();
@@ -1892,7 +2027,7 @@ var Spreadsheet = 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;
@@ -1900,7 +2035,7 @@ var Spreadsheet = 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();
@@ -1914,6 +2049,8 @@ var Spreadsheet = forwardRef(({
     }
   }, [
     columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
     gridDims.headerHeight,
     gridDims.headerWidth,
     height,
@@ -1931,7 +2068,7 @@ var Spreadsheet = 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;
@@ -1941,7 +2078,7 @@ var Spreadsheet = 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;
@@ -1951,10 +2088,10 @@ var Spreadsheet = 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}`;
@@ -1975,6 +2112,8 @@ var Spreadsheet = forwardRef(({
   }, [
     cellData,
     columnWidths,
+    finiteColumnCount,
+    finiteRowCount,
     height,
     rowHeights,
     viewport.scrollX,
@@ -2002,6 +2141,79 @@ var Spreadsheet = forwardRef(({
     }
     return { x, y };
   }, [columnWidths, rowHeights]);
+  const clampViewportOffsets = useCallback3((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 revealRange = useCallback3((range, options = {}) => {
+    if (finiteRowCount === 0 || finiteColumnCount === 0)
+      return;
+    const rows = normalizeScrollRangeAxis(range.start.row, range.end.row, finiteRowCount);
+    const columns = normalizeScrollRangeAxis(range.start.col, range.end.col, finiteColumnCount);
+    if (!rows || !columns)
+      return;
+    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(columns.start, columnWidths) * previous.zoom;
+      const right = getColumnEdgePosition(columns.end + 1, columnWidths) * previous.zoom;
+      const top = getRowEdgePosition(rows.start, rowHeights) * previous.zoom;
+      const bottom = getRowEdgePosition(rows.end + 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 revealCell = useCallback3((cell, options = {}) => {
+    revealRange({
+      start: { row: cell.row, col: cell.col },
+      end: {
+        row: { type: "number", value: cell.row },
+        col: { type: "number", value: cell.col }
+      }
+    }, options);
+  }, [revealRange]);
+  const scrollToCell = useCallback3((cell, options = {}) => {
+    const align = options.align ?? "nearest";
+    revealCell(cell, { rowAlign: align, columnAlign: align });
+  }, [revealCell]);
+  const scrollToRange = useCallback3((range, options = {}) => {
+    const align = options.align ?? "nearest";
+    revealRange(range, { rowAlign: align, columnAlign: align });
+  }, [revealRange]);
+  useEffect3(() => selectionManager.listenToViewportRequest((request) => {
+    if (request.type === "reveal-range") {
+      scrollToRange(request.range, { align: request.align });
+      return;
+    }
+    const isVertical = request.direction === "up" || request.direction === "down";
+    revealCell(request.cell, {
+      rowAlign: isVertical ? request.align : "nearest",
+      columnAlign: isVertical ? "nearest" : request.align
+    });
+  }), [revealCell, scrollToRange, selectionManager]);
+  useEffect3(() => {
+    setViewport((previous) => {
+      const next = clampViewportOffsets(previous.scrollX, previous.scrollY, previous.zoom);
+      return next.scrollX === previous.scrollX && next.scrollY === previous.scrollY ? previous : { ...previous, ...next };
+    });
+  }, [clampViewportOffsets]);
   React2.useEffect(() => {
     return selectionManager.listenToUpdateData((updates) => {
       const editingState = selectionManager.isEditing;
@@ -2076,12 +2288,11 @@ var Spreadsheet = forwardRef(({
   const handleWheel = useCallback3((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 = useCallback3((children) => {
     overlayChildrenRef.current = children;
     if (onOverlayChildrenChange) {
@@ -2500,7 +2711,7 @@ var Spreadsheet = 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) {
@@ -2509,7 +2720,7 @@ var Spreadsheet = 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({
@@ -2520,14 +2731,14 @@ var Spreadsheet = forwardRef(({
       startCol++;
     }
     return headers;
-  }, [width, viewport, getColumnWidth]);
+  }, [finiteColumnCount, width, viewport, getColumnWidth]);
   const getVisibleRowHeaders = useCallback3(() => {
     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;
@@ -2535,7 +2746,7 @@ var Spreadsheet = 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,
@@ -2545,7 +2756,7 @@ var Spreadsheet = forwardRef(({
       rowNum++;
     }
     return headers;
-  }, [height, viewport, getRowHeight]);
+  }, [finiteRowCount, height, viewport, getRowHeight]);
   const { visibleOverlays, overlaysToRender } = useMemo(() => {
     if (!width || !height || !overlayChildren) {
       return { visibleOverlays: [], overlaysToRender: [] };
@@ -2593,8 +2804,45 @@ var Spreadsheet = forwardRef(({
   const visibleColumnHeaders = React2.useMemo(() => getVisibleColumnHeaders(), [getVisibleColumnHeaders]);
   const visibleRowHeaders = React2.useMemo(() => getVisibleRowHeaders(), [getVisibleRowHeaders]);
   const hasFocus = useSelectionManager(selectionManager, () => selectionManager.hasFocus);
+  const referenceSelection = useSelectionManager(selectionManager, () => selectionManager.referenceSelection);
+  const referenceSelectionRect = 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
+  ]);
   React2.useEffect(() => {
-    if (!containerDivRef || !hasFocus || !parentSelected) {
+    if (!containerDivRef || !parentSelected) {
       return;
     }
     containerDivRef.addEventListener("wheel", handleWheel, {
@@ -2603,15 +2851,17 @@ var Spreadsheet = forwardRef(({
     return () => {
       containerDivRef.removeEventListener("wheel", handleWheel);
     };
-  }, [containerDivRef, handleWheel, hasFocus, parentSelected]);
+  }, [containerDivRef, handleWheel, parentSelected]);
   useImperativeHandle(ref, () => ({
     focus: () => {
       selectionManager.focus();
     },
     blur: () => {
       selectionManager.blur();
-    }
-  }), [selectionManager]);
+    },
+    scrollToCell,
+    scrollToRange
+  }), [scrollToCell, scrollToRange, selectionManager]);
   return /* @__PURE__ */ jsx3("div", {
     className: cn("rsp-root", className),
     "data-rsp-scheme": colorScheme,
@@ -2715,28 +2965,38 @@ var Spreadsheet = forwardRef(({
               zIndex: 40
             }
           }),
-          /* @__PURE__ */ jsx3("div", {
+          /* @__PURE__ */ jsxs2("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__ */ jsx3(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__ */ jsx3(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__ */ jsx3("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__ */ jsxs2("div", {
             ref: overlayContainerRef,
@@ -2821,7 +3081,7 @@ import {
   parseCellReference as parseCellReference2,
   getCellReference as getCellReference3
 } from "@ricsam/formula-engine";
-import React3, { useCallback as useCallback4, useRef as useRef4, useState as useState6 } from "react";
+import React3, { useCallback as useCallback4, useMemo as useMemo2, useRef as useRef4, useState as useState6 } from "react";
 
 // src/utils/use-scheme-root.ts
 import { useState as useState5 } from "react";
@@ -2949,6 +3209,7 @@ class WorkbookSelectionManager {
   lastFocusedManager = null;
   listeners = new Set;
   cleanupFunctions = new Map;
+  pendingRangeFocus = null;
   smAreaToSpreadsheetRange(area) {
     const rowEnd = area.end.row.type === "infinity" ? { type: "infinity", sign: "positive" } : { type: "number", value: area.end.row.value };
     const colEnd = area.end.col.type === "infinity" ? { type: "infinity", sign: "positive" } : { type: "number", value: area.end.col.value };
@@ -2963,6 +3224,47 @@ class WorkbookSelectionManager {
       }
     };
   }
+  spreadsheetRangeToSmArea(range) {
+    return {
+      start: { row: range.start.row, col: range.start.col },
+      end: {
+        row: range.end.row.type === "infinity" ? { type: "infinity" } : { type: "number", value: range.end.row.value },
+        col: range.end.col.type === "infinity" ? { type: "infinity" } : { type: "number", value: range.end.col.value }
+      }
+    };
+  }
+  cloneRangeAddress(address) {
+    return {
+      workbookName: address.workbookName,
+      sheetName: address.sheetName,
+      range: this.smAreaToSpreadsheetRange(this.spreadsheetRangeToSmArea(address.range))
+    };
+  }
+  matchesContext(address, context) {
+    return address.workbookName === context.workbookName && address.sheetName === context.sheetName;
+  }
+  applyRangeFocus(manager, context, request) {
+    const selection = this.spreadsheetRangeToSmArea(request.address.range);
+    manager.setState({ selections: [selection] });
+    manager.focus();
+    manager.revealRange(selection, request.options);
+    this.lastFocusedManager = { sm: manager, context };
+    this.emitChange();
+  }
+  applyPendingRangeFocusOnMount(manager, context) {
+    const pending = this.pendingRangeFocus;
+    if (!pending || !this.matchesContext(pending.address, context))
+      return;
+    queueMicrotask(() => {
+      if (this.pendingRangeFocus !== pending)
+        return;
+      const mountedContext = this.managers.get(manager);
+      if (!mountedContext || !this.matchesContext(pending.address, mountedContext))
+        return;
+      this.pendingRangeFocus = null;
+      this.applyRangeFocus(manager, mountedContext, pending);
+    });
+  }
   add(manager, context) {
     this.managers.set(manager, context);
     const focusCleanup = manager.observeStateChange((state) => state.hasFocus, (hasFocus) => {
@@ -2988,6 +3290,7 @@ class WorkbookSelectionManager {
       }
     };
     this.cleanupFunctions.set(manager, cleanup);
+    this.applyPendingRangeFocusOnMount(manager, context);
     return cleanup;
   }
   getLastFocusedSelectionManager() {
@@ -3081,22 +3384,31 @@ class WorkbookSelectionManager {
     return false;
   }
   focusCell(workbookName, sheetName, row, col) {
-    for (const [manager, context] of this.managers) {
-      if (context.workbookName === workbookName && context.sheetName === sheetName) {
-        const selection = {
-          start: { row, col },
-          end: {
-            row: { type: "number", value: row },
-            col: { type: "number", value: col }
-          }
-        };
-        manager.setState({ selections: [selection] });
-        manager.focus();
-        this.lastFocusedManager = { sm: manager, context };
-        this.emitChange();
-        return true;
+    return this.focusRange({
+      workbookName,
+      sheetName,
+      range: {
+        start: { row, col },
+        end: {
+          row: { type: "number", value: row },
+          col: { type: "number", value: col }
+        }
       }
+    });
+  }
+  focusRange(address, options = {}) {
+    const request = {
+      address: this.cloneRangeAddress(address),
+      options: { ...options }
+    };
+    for (const [manager, context] of this.managers) {
+      if (!this.matchesContext(request.address, context))
+        continue;
+      this.pendingRangeFocus = null;
+      this.applyRangeFocus(manager, context, request);
+      return true;
     }
+    this.pendingRangeFocus = request;
     return false;
   }
   emitChange() {
@@ -3345,6 +3657,42 @@ function FormulaSheet({
   const clipboardManager = React3.useMemo(() => controlledClipboardManager ?? new WorkbookClipboardManager(engine), [controlledClipboardManager, engine]);
   const state = useEngine(engine);
   const sheet = state.workbooks.get(workbookName)?.sheets.get(sheetName);
+  const getEngineTableAt = useCallback4((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 = useMemo2(() => ({
+    ...selection?.navigation,
+    getTableAt: selection?.navigation?.getTableAt ?? getEngineTableAt
+  }), [getEngineTableAt, selection?.navigation]);
   const onCellDataChange = useCallback4((updatedSpreadsheet) => {
     const data = new Map(updatedSpreadsheet);
     data.forEach((value, key) => {
@@ -3518,6 +3866,7 @@ function FormulaSheet({
           parentSelected: isSelected,
           selection: {
             ...selection,
+            navigation: formulaNavigation,
             effects: selectionManagerEffects
           },
           containerProps: isSelected && selectedArea ? {
@@ -4107,4 +4456,4 @@ export {
   useResizeObserver
 };
 
-//# debugId=F4BFEDA101FB82C464756E2164756E21
+//# debugId=58E97FA1EA7F33CF64756E2164756E21