@particle-academy/fancy-sheets 0.7.6 → 0.8.0

package/dist/index.d.cts

@@ -308,6 +308,52 @@ declare namespace SheetWorkbook {
     var displayName: string;
 }
 
+type FormulaTokenType = "number" | "string" | "cellRef" | "rangeRef" | "sheetCellRef" | "sheetRangeRef" | "function" | "operator" | "paren" | "comma" | "boolean";
+interface FormulaToken {
+    type: FormulaTokenType;
+    value: string;
+    position: number;
+}
+type FormulaASTNode = {
+    type: "number";
+    value: number;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "boolean";
+    value: boolean;
+} | {
+    type: "cellRef";
+    address: string;
+} | {
+    type: "rangeRef";
+    start: string;
+    end: string;
+} | {
+    type: "sheetCellRef";
+    sheet: string;
+    address: string;
+} | {
+    type: "sheetRangeRef";
+    sheet: string;
+    start: string;
+    end: string;
+} | {
+    type: "functionCall";
+    name: string;
+    args: FormulaASTNode[];
+} | {
+    type: "binaryOp";
+    operator: string;
+    left: FormulaASTNode;
+    right: FormulaASTNode;
+} | {
+    type: "unaryOp";
+    operator: string;
+    operand: FormulaASTNode;
+};
+
 /** Convert 0-based column index to letter(s): 0="A", 25="Z", 26="AA" */
 declare function columnToLetter(col: number): string;
 /** Convert column letter(s) to 0-based index: "A"=0, "Z"=25, "AA"=26 */
@@ -332,4 +378,47 @@ declare function workbookToCSV(workbook: WorkbookData, sheetId?: string): string
 type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
 declare function registerFunction(name: string, fn: FormulaRangeFunction): void;
 
-export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, type CellMap, type CellRange, type CellValue, type ColumnWidths, type FormulaRangeFunction, type MergedRegion, type SelectionState, Sheet, type SheetData, type SheetProps, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+/**
+ * Recalculate every formula cell in a workbook, resolving cross-sheet
+ * references. Pure — no React, no DOM — so it runs headless in Node for SSR,
+ * snapshots, export pipelines, and tests. Returns a new workbook with each
+ * formula cell's `computedValue` populated.
+ */
+declare function recalculateWorkbook(workbook: WorkbookData): WorkbookData;
+/**
+ * Recalculate all formula cells in a single sheet, with optional cross-sheet
+ * reference support when `allSheets` is supplied. Pure.
+ */
+declare function recalculateSheet(sheet: SheetData, allSheets?: SheetData[]): SheetData;
+
+declare function lexFormula(input: string): FormulaToken[];
+
+/**
+ * Recursive descent parser for spreadsheet formulas.
+ * Operator precedence (low to high):
+ *   1. Comparison: =, <>, <, >, <=, >=
+ *   2. String concatenation: &
+ *   3. Addition/subtraction: +, -
+ *   4. Multiplication/division: *, /
+ *   5. Exponentiation: ^
+ *   6. Unary: -, +
+ *   7. Atoms: number, string, boolean, cellRef, rangeRef, function call, (expr)
+ */
+declare function parseFormula(tokens: FormulaToken[]): FormulaASTNode;
+
+type CellValueGetter = (address: string) => CellValue;
+type RangeValueGetter = (start: string, end: string) => CellValue[];
+type SheetCellValueGetter = (sheetName: string, address: string) => CellValue;
+type SheetRangeValueGetter = (sheetName: string, start: string, end: string) => CellValue[];
+interface EvaluatorContext {
+    getCellValue: CellValueGetter;
+    getRangeValues: RangeValueGetter;
+    getSheetCellValue?: SheetCellValueGetter;
+    getSheetRangeValues?: SheetRangeValueGetter;
+}
+declare function evaluateAST(node: FormulaASTNode, getCellValue: CellValueGetter, getRangeValues: RangeValueGetter, ctx?: {
+    getSheetCellValue?: SheetCellValueGetter;
+    getSheetRangeValues?: SheetRangeValueGetter;
+}): CellValue;
+
+export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, type CellMap, type CellRange, type CellValue, type CellValueGetter, type ColumnWidths, type EvaluatorContext, type FormulaASTNode, type FormulaRangeFunction, type FormulaToken, type FormulaTokenType, type MergedRegion, type RangeValueGetter, type SelectionState, Sheet, type SheetCellValueGetter, type SheetData, type SheetProps, type SheetRangeValueGetter, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, evaluateAST, letterToColumn, lexFormula, parseAddress, parseCSV, parseFormula, recalculateSheet, recalculateWorkbook, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.d.ts

@@ -308,6 +308,52 @@ declare namespace SheetWorkbook {
     var displayName: string;
 }
 
+type FormulaTokenType = "number" | "string" | "cellRef" | "rangeRef" | "sheetCellRef" | "sheetRangeRef" | "function" | "operator" | "paren" | "comma" | "boolean";
+interface FormulaToken {
+    type: FormulaTokenType;
+    value: string;
+    position: number;
+}
+type FormulaASTNode = {
+    type: "number";
+    value: number;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "boolean";
+    value: boolean;
+} | {
+    type: "cellRef";
+    address: string;
+} | {
+    type: "rangeRef";
+    start: string;
+    end: string;
+} | {
+    type: "sheetCellRef";
+    sheet: string;
+    address: string;
+} | {
+    type: "sheetRangeRef";
+    sheet: string;
+    start: string;
+    end: string;
+} | {
+    type: "functionCall";
+    name: string;
+    args: FormulaASTNode[];
+} | {
+    type: "binaryOp";
+    operator: string;
+    left: FormulaASTNode;
+    right: FormulaASTNode;
+} | {
+    type: "unaryOp";
+    operator: string;
+    operand: FormulaASTNode;
+};
+
 /** Convert 0-based column index to letter(s): 0="A", 25="Z", 26="AA" */
 declare function columnToLetter(col: number): string;
 /** Convert column letter(s) to 0-based index: "A"=0, "Z"=25, "AA"=26 */
@@ -332,4 +378,47 @@ declare function workbookToCSV(workbook: WorkbookData, sheetId?: string): string
 type FormulaRangeFunction = (args: CellValue[][]) => CellValue;
 declare function registerFunction(name: string, fn: FormulaRangeFunction): void;
 
-export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, type CellMap, type CellRange, type CellValue, type ColumnWidths, type FormulaRangeFunction, type MergedRegion, type SelectionState, Sheet, type SheetData, type SheetProps, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+/**
+ * Recalculate every formula cell in a workbook, resolving cross-sheet
+ * references. Pure — no React, no DOM — so it runs headless in Node for SSR,
+ * snapshots, export pipelines, and tests. Returns a new workbook with each
+ * formula cell's `computedValue` populated.
+ */
+declare function recalculateWorkbook(workbook: WorkbookData): WorkbookData;
+/**
+ * Recalculate all formula cells in a single sheet, with optional cross-sheet
+ * reference support when `allSheets` is supplied. Pure.
+ */
+declare function recalculateSheet(sheet: SheetData, allSheets?: SheetData[]): SheetData;
+
+declare function lexFormula(input: string): FormulaToken[];
+
+/**
+ * Recursive descent parser for spreadsheet formulas.
+ * Operator precedence (low to high):
+ *   1. Comparison: =, <>, <, >, <=, >=
+ *   2. String concatenation: &
+ *   3. Addition/subtraction: +, -
+ *   4. Multiplication/division: *, /
+ *   5. Exponentiation: ^
+ *   6. Unary: -, +
+ *   7. Atoms: number, string, boolean, cellRef, rangeRef, function call, (expr)
+ */
+declare function parseFormula(tokens: FormulaToken[]): FormulaASTNode;
+
+type CellValueGetter = (address: string) => CellValue;
+type RangeValueGetter = (start: string, end: string) => CellValue[];
+type SheetCellValueGetter = (sheetName: string, address: string) => CellValue;
+type SheetRangeValueGetter = (sheetName: string, start: string, end: string) => CellValue[];
+interface EvaluatorContext {
+    getCellValue: CellValueGetter;
+    getRangeValues: RangeValueGetter;
+    getSheetCellValue?: SheetCellValueGetter;
+    getSheetRangeValues?: SheetRangeValueGetter;
+}
+declare function evaluateAST(node: FormulaASTNode, getCellValue: CellValueGetter, getRangeValues: RangeValueGetter, ctx?: {
+    getSheetCellValue?: SheetCellValueGetter;
+    getSheetRangeValues?: SheetRangeValueGetter;
+}): CellValue;
+
+export { type CellAddress, type CellComment, type CellData, type CellFormat, type CellHighlight, type CellHighlightMap, type CellMap, type CellRange, type CellValue, type CellValueGetter, type ColumnWidths, type EvaluatorContext, type FormulaASTNode, type FormulaRangeFunction, type FormulaToken, type FormulaTokenType, type MergedRegion, type RangeValueGetter, type SelectionState, Sheet, type SheetCellValueGetter, type SheetData, type SheetProps, type SheetRangeValueGetter, SheetWorkbook, type SheetWorkbookProps, Spreadsheet, type SpreadsheetContextMenuItem, type SpreadsheetContextValue, type SpreadsheetProps, type TextAlign, type ToolbarButton, type WorkbookData, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, evaluateAST, letterToColumn, lexFormula, parseAddress, parseCSV, parseFormula, recalculateSheet, recalculateWorkbook, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };

package/dist/index.js

@@ -1249,7 +1249,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) {
@@ -1261,33 +1261,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;
@@ -1344,6 +1317,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);
@@ -2859,6 +2861,6 @@ function workbookToCSV(workbook, sheetId) {
   return stringifyCSV(data);
 }
 
-export { Sheet, SheetWorkbook, Spreadsheet, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, letterToColumn, parseAddress, parseCSV, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
+export { Sheet, SheetWorkbook, Spreadsheet, columnToLetter, createEmptySheet, createEmptyWorkbook, csvToWorkbook, evaluateAST, letterToColumn, lexFormula, parseAddress, parseCSV, parseFormula, recalculateSheet, recalculateWorkbook, registerFunction, stringifyCSV, toAddress, useSpreadsheet, workbookToCSV };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map