@particle-academy/fancy-sheets 0.7.6 → 0.8.0

package/docs/recipes/csv-roundtrip.md

@@ -0,0 +1,53 @@
+# Recipe: CSV round-trip
+
+The CSV utilities are a complete, dependency-free library — usable headless (Node
+import pipelines, exports) or in the browser.
+
+```ts
+import {
+  csvToWorkbook,
+  workbookToCSV,
+  parseCSV,
+  stringifyCSV,
+} from "@particle-academy/fancy-sheets";
+```
+
+## Workbook ⇄ CSV
+
+```ts
+// CSV string → WorkbookData (one sheet)
+const wb = csvToWorkbook("Name,Score\nAda,90\nGrace,95", "Results");
+
+// WorkbookData → CSV string. Omitting sheetId uses the active sheet.
+const csv = workbookToCSV(wb);
+const csv2 = workbookToCSV(wb, "sheet-id-2"); // a specific sheet
+```
+
+`workbookToCSV` emits **computed** values for formula cells — run
+`recalculateWorkbook(wb)` first if the workbook was assembled by hand so the
+export carries final numbers, not blanks:
+
+```ts
+import { recalculateWorkbook } from "@particle-academy/fancy-sheets";
+const csv = workbookToCSV(recalculateWorkbook(wb));
+```
+
+## Raw grid ⇄ CSV
+
+When you just want the 2-D array (no workbook wrapper):
+
+```ts
+const rows = parseCSV("a,b\n1,2");   // [["a","b"], ["1","2"]]
+const text = stringifyCSV(rows);     // 'a,b\n1,2'
+```
+
+## Gotchas
+
+- **Quoting & escaping** are handled — fields containing commas, quotes, or
+  newlines are round-tripped via standard `"…"` quoting with `""` escaping.
+- **Everything is a string on import.** `csvToWorkbook` does not infer numeric
+  types; cells hold the raw text. Coerce in your own adapter if you need numbers
+  (or let formulas referencing them do the coercion).
+- **One sheet per CSV.** CSV has no notion of multiple sheets — `csvToWorkbook`
+  produces a single-sheet workbook, and `workbookToCSV` serializes one sheet at a
+  time. Loop over `wb.sheets` and concatenate if you need a multi-tab export.

package/docs/recipes/custom-functions.md

@@ -0,0 +1,56 @@
+# Recipe: custom formula functions
+
+Register your own functions with `registerFunction`. They're available in every
+workbook (the registry is module-global) and callable from any cell formula.
+
+```ts
+import { registerFunction } from "@particle-academy/fancy-sheets";
+import type { FormulaRangeFunction } from "@particle-academy/fancy-sheets";
+```
+
+## The signature
+
+```ts
+type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
+```
+
+Each argument arrives as an **array of cell values** — because any argument can be
+a range. A scalar argument is a one-element array; a range like `A1:A10` is the
+full list of values. Return any `CellValue` (`number | string | boolean | null`).
+Throwing is allowed — the cell shows `#ERROR!`.
+
+## Scalar example
+
+```ts
+registerFunction("GREET", (args) => {
+  const name = args[0]?.[0] ?? "world";
+  return `Hello, ${name}`;
+});
+// =GREET("Ada")  →  "Hello, Ada"
+```
+
+## Range example — `=NPV(rate, cashflows…)`
+
+```ts
+registerFunction("NPV", (args) => {
+  const rate = Number(args[0]?.[0] ?? 0);
+  const flows = args.slice(1).flat().map(Number);   // flatten all range args
+  return flows.reduce((acc, cf, i) => acc + cf / (1 + rate) ** (i + 1), 0);
+});
+// =NPV(0.1, B2:B6)
+```
+
+## Register early
+
+Call `registerFunction` once at module load, before the grid renders (or before
+`recalculateWorkbook` runs headlessly), so the evaluator can find it:
+
+```ts
+// formulas.ts — imported once from your app entry
+registerFunction("TAXED", (args) => Number(args[0]?.[0] ?? 0) * 1.2);
+```
+
+> Names are case-insensitive and upper-cased internally; `=taxed(A1)` and
+> `=TAXED(A1)` resolve to the same function. Re-registering a name overrides it.
+
+See [docs/formulas.md](../formulas.md) for the 80+ built-ins.

package/docs/recipes/external-state-sync.md

@@ -0,0 +1,71 @@
+# Recipe: external state sync + autosave
+
+Drive `<SheetWorkbook>` from a controlled `data` prop that changes from *outside*
+the component — a server round-trip, an agent bridge, undo/redo, a websocket. As
+of **0.7.6** an externally-replaced `data` prop recalculates correctly (formulas
+re-evaluate against the new cells), so this pattern is solid.
+
+## Controlled component
+
+`data` + `onChange` make `<SheetWorkbook>` fully controlled. Hold the workbook in
+your own state and feed it back:
+
+```tsx
+import { SheetWorkbook } from "@particle-academy/fancy-sheets";
+import type { WorkbookData } from "@particle-academy/fancy-sheets";
+import { useState } from "react";
+
+function Editor({ initial }: { initial: WorkbookData }) {
+  const [wb, setWb] = useState(initial);
+  return <SheetWorkbook data={wb} onChange={setWb} />;
+}
+```
+
+Because it's controlled, *anything* can set `wb` — the grid reflects it on the
+next render and re-runs formulas.
+
+## Autosave (debounced)
+
+`onChange` fires on every mutation. Debounce it to persist:
+
+```tsx
+function AutosaveEditor({ initial, save }: { initial: WorkbookData; save: (w: WorkbookData) => Promise<void> }) {
+  const [wb, setWb] = useState(initial);
+  const timer = useRef<ReturnType<typeof setTimeout>>();
+
+  const onChange = (next: WorkbookData) => {
+    setWb(next);
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => void save(next), 600);
+  };
+
+  return <SheetWorkbook data={wb} onChange={onChange} />;
+}
+```
+
+## Agent bridge / collaborative edits
+
+Apply remote patches by replacing `data`. Run `recalculateWorkbook` first if the
+patch source didn't compute values (e.g. a raw agent edit):
+
+```tsx
+import { recalculateWorkbook } from "@particle-academy/fancy-sheets";
+
+socket.on("workbook:patch", (incoming: WorkbookData) => {
+  setWb(recalculateWorkbook(incoming)); // ensure computedValues before paint
+});
+```
+
+## Undo/redo from outside
+
+The component has its own internal undo stack, but if you manage history yourself
+(to coordinate with non-grid state), just push/pop full `WorkbookData` snapshots
+and set them as `data`:
+
+```tsx
+const undo = () => { const prev = history.pop(); if (prev) setWb(prev); };
+```
+
+> Tip: keep one source of truth. Either let the component own state (`defaultData`,
+> read via `onChange`) **or** control it (`data` + `onChange`) — don't mix
+> `defaultData` and `data` on the same instance.

package/docs/recipes/headless-recalc.md

@@ -0,0 +1,67 @@
+# Recipe: headless recalculation (Node, SSR, exports, tests)
+
+The formula engine is pure — no React, no DOM. You can compute formula
+`computedValue`s on a server, in a worker, or in a test, without booting a
+component.
+
+```ts
+import { recalculateWorkbook, createEmptyWorkbook } from "@particle-academy/fancy-sheets";
+import type { WorkbookData } from "@particle-academy/fancy-sheets";
+
+const wb = createEmptyWorkbook();
+wb.sheets[0].cells = {
+  A1: { value: 10 },
+  A2: { value: 20 },
+  A3: { value: null, formula: "SUM(A1:A2)" },   // note: no leading "="
+  B1: { value: null, formula: "A3*2" },
+};
+
+const computed = recalculateWorkbook(wb);
+computed.sheets[0].cells.A3.computedValue; // 30
+computed.sheets[0].cells.B1.computedValue; // 60
+```
+
+`recalculateWorkbook` returns a **new** workbook (inputs are not mutated), runs a
+two-pass sweep so cross-sheet references resolve in any order, topologically
+orders dependent cells, and marks circular references `#CIRC!` / runtime failures
+`#ERROR!`.
+
+## Single sheet
+
+```ts
+import { recalculateSheet } from "@particle-academy/fancy-sheets";
+
+const sheet = recalculateSheet(mySheet);              // intra-sheet only
+const sheet2 = recalculateSheet(mySheet, allSheets);  // pass siblings for cross-sheet refs
+```
+
+## Server-rendered preview (no recalc flash)
+
+Compute on the server so the initial HTML already carries final values:
+
+```ts
+// Laravel/Inertia controller, Next.js loader, etc.
+const props = { workbook: recalculateWorkbook(snapshot) };
+// → <SheetWorkbook data={props.workbook} /> renders final values on first paint
+```
+
+## Low-level lex / parse / evaluate
+
+For custom pipelines (linting, transforms, your own grid), the three stages are
+exported too. The formula string is the body **without** the leading `=`:
+
+```ts
+import { lexFormula, parseFormula, evaluateAST } from "@particle-academy/fancy-sheets";
+
+const ast = parseFormula(lexFormula("2 + 3 * 4"));
+const value = evaluateAST(
+  ast,
+  (address) => cellValues[address] ?? null,           // getCellValue
+  (start, end) => rangeValues(start, end),            // getRangeValues
+  /* ctx */ { getSheetCellValue, getSheetRangeValues } // optional, for Sheet!A1 refs
+);
+// value === 14
+```
+
+`evaluateAST` is provider-agnostic: you supply the cell/range getters, so it can
+read from any backing store (a plain object, a DB row, an agent's snapshot).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-sheets",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Spreadsheet editor with formula engine, multi-sheet tabs, and full cell editing",
   "repository": {
     "type": "git",