@ricsam/react-spreadsheets 0.0.8 → 0.0.10

package/README.md

@@ -134,9 +134,46 @@ 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.
+
+If the same workbook can be mounted in more than one place, give each rendered
+view a stable ID and target that ID when navigating. Selection caches are also
+scoped to the view, so switching sheets or remounting one pane cannot restore a
+selection from its duplicate:
+
+```tsx
+<FormulaWorkbook
+  viewId="left-pane"
+  workbookName="Forecast"
+  engine={engine}
+  selectionManager={workbookSelection}
+/>
+
+workbookSelection.focusRange(referenceAddress, {
+  align: "nearest",
+  viewId: "left-pane",
+});
+```
+
+Omitting `viewId` preserves the single-view API and targets the first matching
+mounted workbook/sheet. Call `cancelPendingFocusRange()` if an app-level sheet
+or pane switch is abandoned before the queued target mounts.
 
 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 +237,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,
@@ -3271,8 +3312,24 @@ var import_formula_engine = require("@ricsam/formula-engine");
 class WorkbookSelectionManager {
   managers = new Map;
   lastFocusedManager = null;
+  lastSelections = [];
+  selectionsByView = new Map;
   listeners = new Set;
   cleanupFunctions = new Map;
+  pendingRangeFocus = null;
+  applyingRangeFocus = new Set;
+  getViewKey(context) {
+    return JSON.stringify([context.workbookName, context.sheetName, context.viewId ?? null]);
+  }
+  cloneSmArea(area) {
+    return {
+      start: { row: area.start.row, col: area.start.col },
+      end: {
+        row: area.end.row.type === "infinity" ? { type: "infinity" } : { type: "number", value: area.end.row.value },
+        col: area.end.col.type === "infinity" ? { type: "infinity" } : { type: "number", value: area.end.col.value }
+      }
+    };
+  }
   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,18 +3344,85 @@ 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))
+    };
+  }
+  areasToRangeAddresses(areas, context) {
+    return areas.map((area) => ({
+      workbookName: context.workbookName,
+      sheetName: context.sheetName,
+      range: this.smAreaToSpreadsheetRange(area)
+    }));
+  }
+  rememberSelections(manager, context, areas = manager.getState().selections) {
+    const cachedAreas = areas.map((area) => this.cloneSmArea(area));
+    this.selectionsByView.set(this.getViewKey(context), cachedAreas);
+    this.lastFocusedManager = { sm: manager, context };
+    this.lastSelections = this.areasToRangeAddresses(cachedAreas, context);
+  }
+  matchesContext(address, context, viewId) {
+    return address.workbookName === context.workbookName && address.sheetName === context.sheetName && (viewId === undefined || context.viewId === viewId);
+  }
+  applyRangeFocus(manager, context, request) {
+    const selection = this.spreadsheetRangeToSmArea(request.address.range);
+    this.applyingRangeFocus.add(manager);
+    try {
+      manager.replaceSelections([selection]);
+      manager.focus();
+    } finally {
+      this.applyingRangeFocus.delete(manager);
+    }
+    manager.revealRange(selection, request.options);
+    this.rememberSelections(manager, context, [selection]);
+    this.emitChange();
+  }
+  applyPendingRangeFocusOnMount(manager, context) {
+    const pending = this.pendingRangeFocus;
+    if (!pending || !this.matchesContext(pending.address, context, pending.options.viewId))
+      return;
+    queueMicrotask(() => {
+      if (this.pendingRangeFocus !== pending)
+        return;
+      const mountedContext = this.managers.get(manager);
+      if (!mountedContext || !this.matchesContext(pending.address, mountedContext, pending.options.viewId)) {
+        return;
+      }
+      this.pendingRangeFocus = null;
+      this.applyRangeFocus(manager, mountedContext, pending);
+    });
+  }
   add(manager, context) {
-    this.managers.set(manager, context);
+    const registeredContext = { ...context };
+    this.managers.set(manager, registeredContext);
+    const cachedSelections = this.selectionsByView.get(this.getViewKey(registeredContext));
+    if (cachedSelections && manager.getState().selections.length === 0) {
+      manager.replaceSelections(cachedSelections);
+    }
     const focusCleanup = manager.observeStateChange((state) => state.hasFocus, (hasFocus) => {
-      if (hasFocus) {
-        this.lastFocusedManager = { sm: manager, context };
+      if (hasFocus && !this.applyingRangeFocus.has(manager)) {
+        this.rememberSelections(manager, registeredContext);
         this.emitChange();
       }
     });
     const selectionCleanup = manager.observeStateChange((state) => JSON.stringify(state.selections), (selectionsJson) => {
+      if (this.applyingRangeFocus.has(manager))
+        return;
       const selections = JSON.parse(selectionsJson);
       if (selections && selections.length > 0) {
-        this.lastFocusedManager = { sm: manager, context };
+        this.rememberSelections(manager, registeredContext, selections);
         this.emitChange();
       }
     });
@@ -3308,26 +3432,19 @@ class WorkbookSelectionManager {
       this.managers.delete(manager);
       this.cleanupFunctions.delete(manager);
       if (this.lastFocusedManager?.sm === manager) {
+        this.rememberSelections(manager, registeredContext);
         this.lastFocusedManager = null;
       }
     };
     this.cleanupFunctions.set(manager, cleanup);
+    this.applyPendingRangeFocusOnMount(manager, registeredContext);
     return cleanup;
   }
   getLastFocusedSelectionManager() {
     return this.lastFocusedManager;
   }
   getSelections() {
-    if (!this.lastFocusedManager) {
-      return [];
-    }
-    const { sm, context } = this.lastFocusedManager;
-    const state = sm.getState();
-    return state.selections.map((area) => ({
-      workbookName: context.workbookName,
-      sheetName: context.sheetName,
-      range: this.smAreaToSpreadsheetRange(area)
-    }));
+    return this.lastSelections.map((selection) => this.cloneRangeAddress(selection));
   }
   getLastSelection() {
     const selections = this.getSelections();
@@ -3376,53 +3493,67 @@ class WorkbookSelectionManager {
     return `[${workbookName}]${sheetRef}!${rangeStr}`;
   }
   blur() {
-    this.managers.forEach((context, manager) => {
+    this.managers.forEach((_context, manager) => {
       manager.clearSelections();
       manager.blur();
     });
+    this.selectionsByView.clear();
     this.lastFocusedManager = null;
+    this.lastSelections = [];
     this.emitChange();
   }
-  focusWorkbook(workbookName) {
+  focusWorkbook(workbookName, viewId) {
     for (const [manager, context] of this.managers) {
-      if (context.workbookName === workbookName) {
+      if (context.workbookName === workbookName && (viewId === undefined || context.viewId === viewId)) {
         manager.focus();
-        this.lastFocusedManager = { sm: manager, context };
+        this.rememberSelections(manager, context);
         this.emitChange();
         return;
       }
     }
   }
-  focusSheet(workbookName, sheetName) {
+  focusSheet(workbookName, sheetName, viewId) {
     for (const [manager, context] of this.managers) {
-      if (context.workbookName === workbookName && context.sheetName === sheetName) {
+      if (context.workbookName === workbookName && context.sheetName === sheetName && (viewId === undefined || context.viewId === viewId)) {
         manager.focus();
-        this.lastFocusedManager = { sm: manager, context };
+        this.rememberSelections(manager, context);
         this.emitChange();
         return true;
       }
     }
     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;
+  focusCell(workbookName, sheetName, row, col, options = {}) {
+    return this.focusRange({
+      workbookName,
+      sheetName,
+      range: {
+        start: { row, col },
+        end: {
+          row: { type: "number", value: row },
+          col: { type: "number", value: col }
+        }
       }
+    }, options);
+  }
+  focusRange(address, options = {}) {
+    const request = {
+      address: this.cloneRangeAddress(address),
+      options: { ...options }
+    };
+    for (const [manager, context] of this.managers) {
+      if (!this.matchesContext(request.address, context, request.options.viewId))
+        continue;
+      this.pendingRangeFocus = null;
+      this.applyRangeFocus(manager, context, request);
+      return true;
     }
+    this.pendingRangeFocus = request;
     return false;
   }
+  cancelPendingFocusRange() {
+    this.pendingRangeFocus = null;
+  }
   emitChange() {
     const currentSelection = this.getLastSelection();
     const selections = currentSelection ? [currentSelection] : [];
@@ -3649,6 +3780,7 @@ function FormulaSheet({
   verboseErrors = false,
   selection,
   selectionManager,
+  viewId,
   customCellStyle,
   customCellRenderer,
   onCellDataChangeError = queueCellEditError,
@@ -3820,7 +3952,8 @@ function FormulaSheet({
     if (selectionManager) {
       const workbookManagerCleanup = selectionManager.add(spreadsheetSelectionManager, {
         workbookName,
-        sheetName
+        sheetName,
+        ...viewId === undefined ? {} : { viewId }
       });
       cleanups.push(workbookManagerCleanup);
     }
@@ -3841,6 +3974,7 @@ function FormulaSheet({
     selectionManager,
     sheetName,
     showFormulas,
+    viewId,
     workbookName
   ]);
   if (!sheet) {
@@ -4074,6 +4208,7 @@ function FormulaWorkbook({
   onActiveSheetChange,
   verboseErrors = false,
   selectionManager,
+  viewId,
   components,
   sheetOverlayChildren,
   sheetSelectedOverlayIds,
@@ -4241,6 +4376,7 @@ function FormulaWorkbook({
             engine,
             verboseErrors,
             selectionManager,
+            viewId,
             ...rest,
             components,
             overlayChildren: activeSheetOverlayChildren,
@@ -4417,4 +4553,4 @@ var useClickAway = (ref, callback) => {
   }, [ref, callback]);
 };
 
-//# debugId=5EB66D4C826F4D2464756E2164756E21
+//# debugId=E584D6343578997564756E2164756E21