@ricsam/react-spreadsheets 0.0.8 → 0.0.9

package/README.md

@@ -134,9 +134,23 @@ function ReferenceAwareSheet({ highlight }: { highlight?: Highlight }) {
 
 Update `highlight` from the formula editor's caret/reference analysis. Clearing
 it removes the decoration, while the selection manager continues to own mouse,
-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.
+keyboard and edit selection state independently. The same `customCellStyle`
+prop is forwarded to a `FormulaWorkbook`'s active sheet.
+
+To focus and reveal the reference itself, share a `WorkbookSelectionManager`
+with the formula sheets and pass the resolved `RangeAddress` to `focusRange`:
+
+```tsx
+const workbookSelection = new WorkbookSelectionManager();
+
+workbookSelection.focusRange(referenceAddress, { align: "nearest" });
+```
+
+The call selects the complete target range, focuses its grid and asks the grid
+to reveal it. It returns `true` when the target sheet is already mounted. If a
+controlled `FormulaWorkbook` still needs to switch `activeSheet`, it returns
+`false` and queues the latest request; mounting that sheet applies the focus and
+reveal automatically.
 
 For the range currently being inserted into a formula, use selection-manager's
 reference-picking mode instead. It preserves the primary/editing selection and
@@ -200,6 +214,11 @@ 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.
 
+`SpreadsheetRef.scrollToRange(range, { align })` does the same for an `SMArea`.
+Finite ranges may be supplied in either direction and are clamped to finite grid
+bounds. An open-ended axis reaches the final row or column of a finite grid; on
+an unbounded grid its finite start is used as the reveal anchor.
+
 ## Theming
 
 All colors, fonts and sizes are CSS custom properties. The package only ever

package/dist/cjs/lib.cjs

@@ -1472,12 +1472,37 @@ var alignScrollOffset = (current, itemStart, itemEnd, viewportSize, align) => {
     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;
@@ -2234,22 +2259,20 @@ var Spreadsheet = import_react4.forwardRef(({
       scrollY: Math.min(Math.max(0, scrollY), maxScrollY)
     };
   }, [columnWidths, finiteColumnCount, finiteRowCount, height, rowHeights, width]);
-  const revealCell = import_react4.useCallback((cell, options = {}) => {
+  const revealRange = import_react4.useCallback((range, options = {}) => {
     if (finiteRowCount === 0 || finiteColumnCount === 0)
       return;
-    if (!Number.isFinite(cell.row) || !Number.isFinite(cell.col))
+    const rows = normalizeScrollRangeAxis(range.start.row, range.end.row, finiteRowCount);
+    const columns = normalizeScrollRangeAxis(range.start.col, range.end.col, finiteColumnCount);
+    if (!rows || !columns)
       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 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;
@@ -2265,17 +2288,34 @@ var Spreadsheet = import_react4.forwardRef(({
     rowHeights,
     width
   ]);
+  const revealCell = import_react4.useCallback((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 = import_react4.useCallback((cell, options = {}) => {
     const align = options.align ?? "nearest";
     revealCell(cell, { rowAlign: align, columnAlign: align });
   }, [revealCell]);
+  const scrollToRange = import_react4.useCallback((range, options = {}) => {
+    const align = options.align ?? "nearest";
+    revealRange(range, { rowAlign: align, columnAlign: align });
+  }, [revealRange]);
   import_react4.useEffect(() => 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, selectionManager]);
+  }), [revealCell, scrollToRange, selectionManager]);
   import_react4.useEffect(() => {
     setViewport((previous) => {
       const next = clampViewportOffsets(previous.scrollX, previous.scrollY, previous.zoom);
@@ -2910,7 +2950,7 @@ var Spreadsheet = import_react4.forwardRef(({
     visibleCells
   ]);
   import_react4.default.useEffect(() => {
-    if (!containerDivRef || !hasFocus || !parentSelected) {
+    if (!containerDivRef || !parentSelected) {
       return;
     }
     containerDivRef.addEventListener("wheel", handleWheel, {
@@ -2919,7 +2959,7 @@ var Spreadsheet = import_react4.forwardRef(({
     return () => {
       containerDivRef.removeEventListener("wheel", handleWheel);
     };
-  }, [containerDivRef, handleWheel, hasFocus, parentSelected]);
+  }, [containerDivRef, handleWheel, parentSelected]);
   import_react4.useImperativeHandle(ref, () => ({
     focus: () => {
       selectionManager.focus();
@@ -2927,8 +2967,9 @@ var Spreadsheet = import_react4.forwardRef(({
     blur: () => {
       selectionManager.blur();
     },
-    scrollToCell
-  }), [scrollToCell, selectionManager]);
+    scrollToCell,
+    scrollToRange
+  }), [scrollToCell, scrollToRange, selectionManager]);
   return /* @__PURE__ */ jsx_runtime3.jsx("div", {
     className: cn("rsp-root", className),
     "data-rsp-scheme": colorScheme,
@@ -3273,6 +3314,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 };
@@ -3287,6 +3329,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) => {
@@ -3312,6 +3395,7 @@ class WorkbookSelectionManager {
       }
     };
     this.cleanupFunctions.set(manager, cleanup);
+    this.applyPendingRangeFocusOnMount(manager, context);
     return cleanup;
   }
   getLastFocusedSelectionManager() {
@@ -3405,22 +3489,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() {
@@ -4417,4 +4510,4 @@ var useClickAway = (ref, callback) => {
   }, [ref, callback]);
 };
 
-//# debugId=5EB66D4C826F4D2464756E2164756E21
+//# debugId=81701030D90BCDFB64756E2164756E21