@particle-academy/fancy-sheets 0.7.5 → 0.8.0

package/README.md

@@ -1,5 +1,7 @@
 # @particle-academy/fancy-sheets
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 A full-featured spreadsheet component with formulas, formatting, selection, multi-sheet workbooks, clipboard, CSV import/export, and undo/redo. Custom engine — no third-party dependency.
 
 ## Installation
@@ -47,6 +49,26 @@ The component fills its container — wrap it in a sized element (height is requ
 | Full component API (props, sub-components, `useSpreadsheet` hook, data model, keyboard shortcuts) | [docs/Spreadsheet.md](./docs/Spreadsheet.md) |
 | 80+ built-in formula functions + custom function registration | [docs/formulas.md](./docs/formulas.md) |
 | CSV import / export utilities | [docs/csv.md](./docs/csv.md) |
+| **Headless recalculation** (Node / SSR / exports / tests) | [docs/recipes/headless-recalc.md](./docs/recipes/headless-recalc.md) |
+| **External state sync + autosave** (controlled `data`, agent bridge, undo/redo) | [docs/recipes/external-state-sync.md](./docs/recipes/external-state-sync.md) |
+| **Custom formula functions** (`registerFunction` walkthrough) | [docs/recipes/custom-functions.md](./docs/recipes/custom-functions.md) |
+| **CSV round-trip** | [docs/recipes/csv-roundtrip.md](./docs/recipes/csv-roundtrip.md) |
+
+### Headless formula engine (0.8+)
+
+The engine is pure functions — no React, no DOM — so backends, schedulers,
+exporters, and test rigs can use it directly:
+
+```ts
+import {
+  recalculateWorkbook, recalculateSheet,   // recompute computedValues
+  lexFormula, parseFormula, evaluateAST,    // low-level lex → parse → eval
+} from "@particle-academy/fancy-sheets";
+
+const computed = recalculateWorkbook(workbook); // new workbook, formulas evaluated
+```
+
+See [docs/recipes/headless-recalc.md](./docs/recipes/headless-recalc.md).
 
 ## Commands
 
@@ -63,6 +85,7 @@ pnpm --filter @particle-academy/fancy-sheets clean    # Remove dist/
 - **`useSpreadsheet` hook** — full workbook state and actions accessible from any child
 - **80+ built-in formulas** — Math, Text, Logic, Conditional aggregates, Lookup, Date/Time, Info
 - **Multi-sheet workbooks** — cross-sheet references via `Sheet2!A1` syntax
+- **Headless engine (0.8+)** — `recalculateWorkbook` / `lexFormula` / `parseFormula` / `evaluateAST` exported as pure, React-free functions for SSR, exports, and Node tests
 - **Features** — editing, navigation, selection (single, range, multi-range), formatting (bold/italic/align), clipboard (copy/cut/paste with TSV), column resize, freeze rows/cols, undo/redo (50 steps), drag-to-select
 - **Zero third-party dependencies** — custom lexer, parser, evaluator, and dependency graph
 

package/dist/index.cjs

@@ -1255,7 +1255,7 @@ function getRecalculationOrder(graph) {
   return order;
 }
 
-// src/hooks/use-spreadsheet-store.ts
+// src/engine/recalc.ts
 function recalculateWorkbook(workbook) {
   const recalculated = [];
   for (const sheet of workbook.sheets) {
@@ -1267,33 +1267,6 @@ function recalculateWorkbook(workbook) {
   }
   return { ...workbook, sheets: finalSheets };
 }
-function createInitialState(data) {
-  const workbook = data ?? createEmptyWorkbook();
-  return {
-    workbook: recalculateWorkbook(workbook),
-    selection: { activeCell: "A1", ranges: [{ start: "A1", end: "A1" }] },
-    editingCell: null,
-    editValue: "",
-    undoStack: [],
-    redoStack: []
-  };
-}
-function getActiveSheet(state) {
-  return state.workbook.sheets.find((s) => s.id === state.workbook.activeSheetId);
-}
-function updateActiveSheet(state, updater) {
-  return {
-    ...state.workbook,
-    sheets: state.workbook.sheets.map(
-      (s) => s.id === state.workbook.activeSheetId ? updater(s) : s
-    )
-  };
-}
-function pushUndo(state) {
-  const stack = [...state.undoStack, state.workbook];
-  if (stack.length > 50) stack.shift();
-  return { undoStack: stack, redoStack: [] };
-}
 function recalculateSheet(sheet, allSheets) {
   const graph = buildDependencyGraph(sheet.cells);
   if (graph.size === 0) return sheet;
@@ -1350,6 +1323,35 @@ function recalculateSheet(sheet, allSheets) {
   }
   return { ...sheet, cells };
 }
+
+// src/hooks/use-spreadsheet-store.ts
+function createInitialState(data) {
+  const workbook = data ?? createEmptyWorkbook();
+  return {
+    workbook: recalculateWorkbook(workbook),
+    selection: { activeCell: "A1", ranges: [{ start: "A1", end: "A1" }] },
+    editingCell: null,
+    editValue: "",
+    undoStack: [],
+    redoStack: []
+  };
+}
+function getActiveSheet(state) {
+  return state.workbook.sheets.find((s) => s.id === state.workbook.activeSheetId);
+}
+function updateActiveSheet(state, updater) {
+  return {
+    ...state.workbook,
+    sheets: state.workbook.sheets.map(
+      (s) => s.id === state.workbook.activeSheetId ? updater(s) : s
+    )
+  };
+}
+function pushUndo(state) {
+  const stack = [...state.undoStack, state.workbook];
+  if (stack.length > 50) stack.shift();
+  return { undoStack: stack, redoStack: [] };
+}
 function getCellDisplayValue(cell) {
   if (!cell) return "";
   if (cell.computedValue !== void 0) return String(cell.computedValue);
@@ -1561,7 +1563,7 @@ function reducer(state, action) {
       };
     }
     case "SET_WORKBOOK":
-      return { ...state, workbook: action.workbook };
+      return { ...state, workbook: recalculateWorkbook(action.workbook) };
     default:
       return state;
   }
@@ -2260,7 +2262,13 @@ function SpreadsheetGrid({ className }) {
               return /* @__PURE__ */ jsxRuntime.jsxs(
                 "div",
                 {
-                  className: "flex",
+                  className: reactFancy.cn(
+                    "flex",
+                    // Frozen rows need a solid background so scrolling content
+                    // doesn't bleed through any cell-level transparency
+                    // (highlight overlays, alpha format colors, etc.).
+                    isFrozenRow && "bg-white dark:bg-zinc-900"
+                  ),
                   style: isFrozenRow ? {
                     position: "sticky",
                     top: rowHeight + rowIdx * rowHeight,
@@ -2274,6 +2282,12 @@ function SpreadsheetGrid({ className }) {
                       return /* @__PURE__ */ jsxRuntime.jsx(
                         "div",
                         {
+                          className: reactFancy.cn(
+                            // Same solid-background guarantee for frozen
+                            // columns — keeps the column opaque while content
+                            // scrolls horizontally underneath.
+                            isFrozenCol && "bg-white dark:bg-zinc-900"
+                          ),
                           style: isFrozenCol ? {
                             position: "sticky",
                             left: 48 + Array.from({ length: colIdx }, (_3, c) => getColumnWidth(c)).reduce((a, b) => a + b, 0),
@@ -2860,9 +2874,14 @@ exports.columnToLetter = columnToLetter;
 exports.createEmptySheet = createEmptySheet;
 exports.createEmptyWorkbook = createEmptyWorkbook;
 exports.csvToWorkbook = csvToWorkbook;
+exports.evaluateAST = evaluateAST;
 exports.letterToColumn = letterToColumn;
+exports.lexFormula = lexFormula;
 exports.parseAddress = parseAddress;
 exports.parseCSV = parseCSV;
+exports.parseFormula = parseFormula;
+exports.recalculateSheet = recalculateSheet;
+exports.recalculateWorkbook = recalculateWorkbook;
 exports.registerFunction = registerFunction;
 exports.stringifyCSV = stringifyCSV;
 exports.toAddress = toAddress;