@ricsam/react-spreadsheets 0.0.7 → 0.0.9

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/react-spreadsheets",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module"
 }

package/dist/styles.css

@@ -150,6 +150,7 @@
   --_rsp-accent-contrast: var(--rsp-accent-contrast, #ffffff);
   --_rsp-selection-bg: var(--rsp-selection-bg, var(--rsp-light, #e8f2fe) var(--rsp-dark, #17304f));
   --_rsp-selection-range-bg: var(--rsp-selection-range-bg, var(--rsp-light, #f1f7fe) var(--rsp-dark, #14263d));
+  --_rsp-reference-accent: var(--rsp-reference-accent, var(--rsp-light, #f97316) var(--rsp-dark, #fb923c));
   --_rsp-hover-bg: var(--rsp-hover-bg, var(--rsp-light, #f5f7fa) var(--rsp-dark, #1c2436));
   --_rsp-focus-ring: var(--rsp-focus-ring, var(--rsp-light, rgba(33, 150, 243, 0.22)) var(--rsp-dark, rgba(88, 166, 255, 0.28)));
 
@@ -276,6 +277,41 @@
   z-index: 2;
 }
 
+/* Formula references are not primary selections. They live in one independent
+   overlay so table fills, conditional styles and the selected-cell perimeter
+   remain untouched. Four animated gradients create Excel-like marching ants. */
+.rsp-reference-selection {
+  position: absolute;
+  z-index: 4;
+  pointer-events: none;
+  background-image:
+    linear-gradient(90deg, var(--_rsp-reference-accent) 50%, transparent 50%),
+    linear-gradient(90deg, var(--_rsp-reference-accent) 50%, transparent 50%),
+    linear-gradient(0deg, var(--_rsp-reference-accent) 50%, transparent 50%),
+    linear-gradient(0deg, var(--_rsp-reference-accent) 50%, transparent 50%);
+  background-position: 0 0, 0 100%, 0 0, 100% 0;
+  background-repeat: repeat-x, repeat-x, repeat-y, repeat-y;
+  background-size: 8px 2px, 8px 2px, 2px 8px, 2px 8px;
+  filter: drop-shadow(0 0 1px var(--_rsp-bg));
+  animation: rsp-reference-marching-ants 480ms linear infinite;
+}
+
+.rsp-reference-selection-selecting {
+  opacity: 0.9;
+}
+
+@keyframes rsp-reference-marching-ants {
+  to {
+    background-position: 8px 0, -8px 100%, 0 -8px, 100% 8px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rsp-reference-selection {
+    animation: none;
+  }
+}
+
 /* The editor surface must win over the selection tint above (equal specificity
    would otherwise leave the selected-cell background showing through), and over
    a consumer background so the text being typed stays legible. */

package/dist/types/lib.d.ts

@@ -8,8 +8,10 @@
  * Remember to import the stylesheet once in your app:
  *   import "@ricsam/react-spreadsheets/styles.css";
  */
-export { Spreadsheet, type SpreadsheetProps, type SpreadsheetRef, type SpreadsheetChild, type SpreadsheetChildInitial, type SpreadsheetChildState, type SpreadsheetComponent, } from "./spreadsheet/spreadsheet";
+export { Spreadsheet, type SpreadsheetProps, type SpreadsheetRef, type SpreadsheetScrollAlignment, type SpreadsheetScrollToCellOptions, type SpreadsheetScrollToRangeOptions, type SpreadsheetChild, type SpreadsheetChildInitial, type SpreadsheetChildState, type SpreadsheetComponent, } from "./spreadsheet/spreadsheet";
+export type { SelectionNavigationModel } from "@ricsam/selection-manager";
 export { FormulaSheet, FormulaWorkbook, WorkbookClipboardManager, WorkbookSelectionManager, } from "./workbook/workbook";
+export type { WorkbookRangeFocusOptions } from "./workbook/workbook-selection-manager";
 export { coerceCellInput, getCellDisplayText, getCellDisplayValue, } from "./workbook/cell-data-type";
 export { normalizeBorderSides, hasAnyBorderSide, type BorderSides, type NormalizedBorderSides, } from "./workbook/border-sides";
 export { onCellEditError, queueCellEditError, type CellEditErrorListener, } from "./workbook/cell-edit-error";

package/dist/types/spreadsheet/spreadsheet.d.ts

@@ -1,4 +1,4 @@
-import { type Format, SelectionManager, type SelectionManagerState } from '@ricsam/selection-manager';
+import { type Format, SelectionManager, type SelectionNavigationModel, type SelectionManagerState, type SMArea, type SMCell } from '@ricsam/selection-manager';
 import React, { type ReactNode } from 'react';
 import type { CellRenderContext, SerializedCellValue, SpreadsheetColumnWidths, SpreadsheetRowHeights } from '../types';
 import { type CellSnapAnchor } from './snapping';
@@ -39,6 +39,10 @@ export interface SpreadsheetProps {
     cellData?: Map<string, SerializedCellValue>;
     onCellDataChange?: (data: Map<string, SerializedCellValue>) => void;
     onCellDataChangeError?: (error: unknown) => void;
+    /** Finite number of rows. Omit for an unbounded sheet. */
+    rowCount?: number;
+    /** Finite number of columns. Omit for an unbounded sheet. */
+    columnCount?: number;
     columnWidths?: SpreadsheetColumnWidths;
     onColumnWidthsChange?: (columnWidths: SpreadsheetColumnWidths) => void;
     rowHeights?: SpreadsheetRowHeights;
@@ -62,6 +66,8 @@ export interface SpreadsheetProps {
         onStateChange?: (state: SelectionManagerState) => void;
         effects?: (selectionManager: SelectionManager) => (() => void) | void;
         formats?: Format[];
+        /** Data- and table-aware keyboard navigation hooks. */
+        navigation?: SelectionNavigationModel;
     };
     components?: Record<string, SpreadsheetComponent>;
     overlayChildren?: SpreadsheetChild[];
@@ -79,9 +85,20 @@ export interface SpreadsheetProps {
     /** Whether the parent component is selected (used to gate overlay selection) */
     parentSelected?: boolean;
 }
+export type SpreadsheetScrollAlignment = 'nearest' | 'start' | 'end';
+export interface SpreadsheetScrollToCellOptions {
+    align?: SpreadsheetScrollAlignment;
+}
+export interface SpreadsheetScrollToRangeOptions {
+    align?: SpreadsheetScrollAlignment;
+}
 export interface SpreadsheetRef {
     focus: () => void;
     blur: () => void;
+    /** Reveal a zero-based cell without changing the selection. */
+    scrollToCell: (cell: SMCell, options?: SpreadsheetScrollToCellOptions) => void;
+    /** Reveal a zero-based range without changing the selection. */
+    scrollToRange: (range: SMArea, options?: SpreadsheetScrollToRangeOptions) => void;
 }
 export declare const Spreadsheet: React.ForwardRefExoticComponent<SpreadsheetProps & {
     disableClipboard?: boolean;

package/dist/types/workbook/workbook-selection-manager.d.ts

@@ -1,15 +1,25 @@
 import type { RangeAddress } from '@ricsam/formula-engine';
-import type { SelectionManager } from '@ricsam/selection-manager';
+import type { SelectionManager, ViewportAlignment } from '@ricsam/selection-manager';
 interface ManagerContext {
     workbookName: string;
     sheetName: string;
 }
+export interface WorkbookRangeFocusOptions {
+    /** How the target range should be positioned in the spreadsheet viewport. */
+    align?: ViewportAlignment;
+}
 export declare class WorkbookSelectionManager {
     private managers;
     private lastFocusedManager;
     private listeners;
     private cleanupFunctions;
+    private pendingRangeFocus;
     private smAreaToSpreadsheetRange;
+    private spreadsheetRangeToSmArea;
+    private cloneRangeAddress;
+    private matchesContext;
+    private applyRangeFocus;
+    private applyPendingRangeFocusOnMount;
     /**
      * Register a SelectionManager with its workbook/sheet context
      * Returns a cleanup function to unregister
@@ -59,10 +69,20 @@ export declare class WorkbookSelectionManager {
      * Finds the matching SelectionManager, sets its selection to the given cell,
      * and focuses it.
      *
-     * @returns true if the cell was successfully focused, false if no matching
-     *          manager was found (e.g. the sheet is not currently rendered).
+     * @returns true when focused immediately, false when queued until the target
+     *          sheet mounts.
      */
     focusCell(workbookName: string, sheetName: string, row: number, col: number): boolean;
+    /**
+     * Focus, select and reveal a range in its workbook/sheet.
+     *
+     * If the sheet is not mounted yet, the latest request is queued and applied
+     * when that sheet registers. This lets controlled workbooks switch their
+     * active sheet before the target grid exists.
+     *
+     * @returns true when applied immediately, false when queued for a future mount.
+     */
+    focusRange(address: RangeAddress, options?: WorkbookRangeFocusOptions): boolean;
     /**
      * Notify all listeners of selection change
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/react-spreadsheets",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Headless-friendly React spreadsheet and workbook components: infinite virtualized grid, zoom, resizing, clipboard, fill handles and formula-engine bindings.",
   "type": "module",
   "module": "./dist/mjs/lib.mjs",
@@ -43,7 +43,7 @@
   },
   "peerDependencies": {
     "@ricsam/formula-engine": ">=0.2.0",
-    "@ricsam/selection-manager": ">=0.0.25",
+    "@ricsam/selection-manager": ">=0.0.31",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
@@ -55,7 +55,7 @@
   "devDependencies": {
     "@happy-dom/global-registrator": "^18.0.1",
     "@ricsam/formula-engine": "^0.2.15",
-    "@ricsam/selection-manager": "^0.0.25",
+    "@ricsam/selection-manager": "^0.0.31",
     "@testing-library/react": "^16.3.0",
     "@types/bun": "latest",
     "@types/react": "^19",