@ricsam/react-spreadsheets 0.0.6 → 0.0.8

package/README.md

@@ -86,6 +86,120 @@ export function Demo() {
 `FormulaWorkbook` adds Excel-style sheet tabs, renaming, deletion and zoom on
 top of `FormulaSheet`.
 
+### Formula reference highlights
+
+Keep editor-driven reference highlights separate from the user's spreadsheet
+selection. `FormulaSheet` calls `customCellStyle` with both the cell and its
+engine-provided style, so a host can add a transient range fill and perimeter
+without replacing table or conditional formatting:
+
+```tsx
+type Highlight = {
+  start: { rowIndex: number; colIndex: number };
+  end: { rowIndex: number; colIndex: number };
+};
+
+function ReferenceAwareSheet({ highlight }: { highlight?: Highlight }) {
+  return (
+    <FormulaSheet
+      engine={engine}
+      workbookName="Workbook1"
+      sheetName="Sheet1"
+      style={{ height: 480 }}
+      customCellStyle={(cell, internalStyle) => {
+        if (
+          !highlight ||
+          cell.rowIndex < highlight.start.rowIndex ||
+          cell.rowIndex > highlight.end.rowIndex ||
+          cell.colIndex < highlight.start.colIndex ||
+          cell.colIndex > highlight.end.colIndex
+        ) {
+          return internalStyle;
+        }
+
+        const color = "#7c3aed";
+        return {
+          ...internalStyle,
+          backgroundColor: "rgb(124 58 237 / 14%)",
+          ...(cell.rowIndex === highlight.start.rowIndex && { borderTopColor: color }),
+          ...(cell.rowIndex === highlight.end.rowIndex && { borderBottomColor: color }),
+          ...(cell.colIndex === highlight.start.colIndex && { borderLeftColor: color }),
+          ...(cell.colIndex === highlight.end.colIndex && { borderRightColor: color }),
+        };
+      }}
+    />
+  );
+}
+```
+
+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.
+
+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
@@ -175,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