@particle-academy/fancy-sheets 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -7,11 +7,15 @@ type CellAddress = string;
 type CellValue = string | number | boolean | null;
 /** Text alignment */
 type TextAlign = "left" | "center" | "right";
+/** Display format for cell values */
+type CellDisplayFormat = "auto" | "text" | "number" | "date" | "datetime" | "percentage" | "currency";
 /** Cell formatting */
 interface CellFormat {
     bold?: boolean;
     italic?: boolean;
     textAlign?: TextAlign;
+    /** Display format — controls how the value is rendered */
+    displayFormat?: CellDisplayFormat;
 }
 /** A single cell's complete data */
 interface CellData {
@@ -116,6 +120,8 @@ interface SpreadsheetContextValue {
     renameSheet: (sheetId: string, name: string) => void;
     deleteSheet: (sheetId: string) => void;
     setActiveSheet: (sheetId: string) => void;
+    setFrozenRows: (count: number) => void;
+    setFrozenCols: (count: number) => void;
     undo: () => void;
     redo: () => void;
     canUndo: boolean;

package/dist/index.d.ts

@@ -7,11 +7,15 @@ type CellAddress = string;
 type CellValue = string | number | boolean | null;
 /** Text alignment */
 type TextAlign = "left" | "center" | "right";
+/** Display format for cell values */
+type CellDisplayFormat = "auto" | "text" | "number" | "date" | "datetime" | "percentage" | "currency";
 /** Cell formatting */
 interface CellFormat {
     bold?: boolean;
     italic?: boolean;
     textAlign?: TextAlign;
+    /** Display format — controls how the value is rendered */
+    displayFormat?: CellDisplayFormat;
 }
 /** A single cell's complete data */
 interface CellData {
@@ -116,6 +120,8 @@ interface SpreadsheetContextValue {
     renameSheet: (sheetId: string, name: string) => void;
     deleteSheet: (sheetId: string) => void;
     setActiveSheet: (sheetId: string) => void;
+    setFrozenRows: (count: number) => void;
+    setFrozenCols: (count: number) => void;
     undo: () => void;
     redo: () => void;
     canUndo: boolean;

package/dist/index.js

@@ -121,12 +121,41 @@ function lexFormula(input) {
     if (ch >= "A" && ch <= "Z" || ch >= "a" && ch <= "z" || ch === "_") {
       const pos = i;
       i++;
-      while (i < len && (input[i] >= "A" && input[i] <= "Z" || input[i] >= "a" && input[i] <= "z" || input[i] >= "0" && input[i] <= "9" || input[i] === "_")) i++;
-      const word = input.slice(pos, i);
+      while (i < len && (input[i] >= "A" && input[i] <= "Z" || input[i] >= "a" && input[i] <= "z" || input[i] >= "0" && input[i] <= "9" || input[i] === "_" || input[i] === " ")) {
+        if (input[i] === " ") {
+          let lookAhead = i + 1;
+          while (lookAhead < len && input[lookAhead] === " ") lookAhead++;
+          if (lookAhead < len && (input[lookAhead] >= "A" && input[lookAhead] <= "Z" || input[lookAhead] >= "a" && input[lookAhead] <= "z" || input[lookAhead] >= "0" && input[lookAhead] <= "9" || input[lookAhead] === "!")) {
+            i++;
+            continue;
+          }
+          break;
+        }
+        i++;
+      }
+      let word = input.slice(pos, i).trimEnd();
+      i = pos + word.length;
       if (word.toUpperCase() === "TRUE" || word.toUpperCase() === "FALSE") {
         tokens.push({ type: "boolean", value: word.toUpperCase(), position: pos });
         continue;
       }
+      if (i < len && input[i] === "!") {
+        const sheetName = word;
+        i++;
+        const refStart = i;
+        while (i < len && (input[i] >= "A" && input[i] <= "Z" || input[i] >= "a" && input[i] <= "z" || input[i] >= "0" && input[i] <= "9")) i++;
+        const ref1 = input.slice(refStart, i);
+        if (i < len && input[i] === ":") {
+          i++;
+          const ref2Start = i;
+          while (i < len && (input[i] >= "A" && input[i] <= "Z" || input[i] >= "a" && input[i] <= "z" || input[i] >= "0" && input[i] <= "9")) i++;
+          const ref2 = input.slice(ref2Start, i);
+          tokens.push({ type: "sheetRangeRef", value: sheetName + "!" + ref1 + ":" + ref2, position: pos });
+        } else {
+          tokens.push({ type: "sheetCellRef", value: sheetName + "!" + ref1.toUpperCase(), position: pos });
+        }
+        continue;
+      }
       if (i < len && input[i] === ":") {
         const colonPos = i;
         i++;
@@ -270,6 +299,19 @@ function parseFormula(tokens) {
       const parts = t.value.split(":");
       return { type: "rangeRef", start: parts[0], end: parts[1] };
     }
+    if (t.type === "sheetCellRef") {
+      advance();
+      const bangIdx = t.value.indexOf("!");
+      return { type: "sheetCellRef", sheet: t.value.slice(0, bangIdx), address: t.value.slice(bangIdx + 1).toUpperCase() };
+    }
+    if (t.type === "sheetRangeRef") {
+      advance();
+      const bangIdx = t.value.indexOf("!");
+      const sheetName = t.value.slice(0, bangIdx);
+      const rangePart = t.value.slice(bangIdx + 1);
+      const parts = rangePart.split(":");
+      return { type: "sheetRangeRef", sheet: sheetName, start: parts[0].toUpperCase(), end: parts[1].toUpperCase() };
+    }
     if (t.type === "function") {
       const name = advance().value;
       expect("paren", "(");
@@ -1003,7 +1045,7 @@ registerFunction("TYPE", (args) => {
 });
 
 // src/engine/formula/evaluator.ts
-function evaluateAST(node, getCellValue, getRangeValues) {
+function evaluateAST(node, getCellValue, getRangeValues, ctx) {
   switch (node.type) {
     case "number":
       return node.value;
@@ -1013,9 +1055,19 @@ function evaluateAST(node, getCellValue, getRangeValues) {
       return node.value;
     case "cellRef":
       return getCellValue(node.address);
-    case "rangeRef":
+    case "rangeRef": {
       const vals = getRangeValues(node.start, node.end);
       return vals[0] ?? null;
+    }
+    case "sheetCellRef": {
+      if (!ctx?.getSheetCellValue) return "#REF!";
+      return ctx.getSheetCellValue(node.sheet, node.address);
+    }
+    case "sheetRangeRef": {
+      if (!ctx?.getSheetRangeValues) return "#REF!";
+      const vals = ctx.getSheetRangeValues(node.sheet, node.start, node.end);
+      return vals[0] ?? null;
+    }
     case "functionCall": {
       const entry = getFunction(node.name);
       if (!entry) return `#NAME?`;
@@ -1023,7 +1075,11 @@ function evaluateAST(node, getCellValue, getRangeValues) {
         if (arg.type === "rangeRef") {
           return getRangeValues(arg.start, arg.end);
         }
-        const val = evaluateAST(arg, getCellValue, getRangeValues);
+        if (arg.type === "sheetRangeRef") {
+          if (!ctx?.getSheetRangeValues) return ["#REF!"];
+          return ctx.getSheetRangeValues(arg.sheet, arg.start, arg.end);
+        }
+        const val = evaluateAST(arg, getCellValue, getRangeValues, ctx);
         return [val];
       });
       try {
@@ -1033,8 +1089,8 @@ function evaluateAST(node, getCellValue, getRangeValues) {
       }
     }
     case "binaryOp": {
-      const left = evaluateAST(node.left, getCellValue, getRangeValues);
-      const right = evaluateAST(node.right, getCellValue, getRangeValues);
+      const left = evaluateAST(node.left, getCellValue, getRangeValues, ctx);
+      const right = evaluateAST(node.right, getCellValue, getRangeValues, ctx);
       const lNum = typeof left === "number" ? left : Number(left);
       const rNum = typeof right === "number" ? right : Number(right);
       switch (node.operator) {
@@ -1067,7 +1123,7 @@ function evaluateAST(node, getCellValue, getRangeValues) {
       }
     }
     case "unaryOp": {
-      const operand = evaluateAST(node.operand, getCellValue, getRangeValues);
+      const operand = evaluateAST(node.operand, getCellValue, getRangeValues, ctx);
       const num = typeof operand === "number" ? operand : Number(operand);
       if (isNaN(num)) return "#VALUE!";
       return node.operator === "-" ? -num : num;
@@ -1181,7 +1237,7 @@ function getRecalculationOrder(graph) {
 function recalculateWorkbook(workbook) {
   return {
     ...workbook,
-    sheets: workbook.sheets.map(recalculateSheet)
+    sheets: workbook.sheets.map((s) => recalculateSheet(s, workbook.sheets))
   };
 }
 function createInitialState(data) {
@@ -1211,7 +1267,7 @@ function pushUndo(state) {
   if (stack.length > 50) stack.shift();
   return { undoStack: stack, redoStack: [] };
 }
-function recalculateSheet(sheet) {
+function recalculateSheet(sheet, allSheets) {
   const graph = buildDependencyGraph(sheet.cells);
   if (graph.size === 0) return sheet;
   const circular = detectCircularRefs(graph);
@@ -1227,6 +1283,28 @@ function recalculateSheet(sheet) {
     const addresses = expandRange(startAddr, endAddr);
     return addresses.map(getCellValue);
   };
+  const getSheetCellValue = (sheetName, addr) => {
+    if (!allSheets) return "#REF!";
+    const target = allSheets.find((s) => s.name === sheetName || s.id === sheetName);
+    if (!target) return "#REF!";
+    const c = target.cells[addr];
+    if (!c) return null;
+    if (c.formula && c.computedValue !== void 0) return c.computedValue;
+    return c.value;
+  };
+  const getSheetRangeValues = (sheetName, startAddr, endAddr) => {
+    if (!allSheets) return [];
+    const target = allSheets.find((s) => s.name === sheetName || s.id === sheetName);
+    if (!target) return [];
+    const addresses = expandRange(startAddr, endAddr);
+    return addresses.map((a) => {
+      const c = target.cells[a];
+      if (!c) return null;
+      if (c.formula && c.computedValue !== void 0) return c.computedValue;
+      return c.value;
+    });
+  };
+  const ctx = { getSheetCellValue, getSheetRangeValues };
   for (const addr of order) {
     const cell = cells[addr];
     if (!cell?.formula) continue;
@@ -1237,7 +1315,7 @@ function recalculateSheet(sheet) {
     try {
       const tokens = lexFormula(cell.formula);
       const ast = parseFormula(tokens);
-      const result = evaluateAST(ast, getCellValue, getRangeValues);
+      const result = evaluateAST(ast, getCellValue, getRangeValues, ctx);
       cells[addr] = { ...cell, computedValue: result };
     } catch {
       cells[addr] = { ...cell, computedValue: "#ERROR!" };
@@ -1262,7 +1340,7 @@ function reducer(state, action) {
       if (existing?.format) cellData.format = existing.format;
       const workbook = updateActiveSheet(state, (s) => {
         const updated = { ...s, cells: { ...s.cells, [action.address]: cellData } };
-        return recalculateSheet(updated);
+        return recalculateSheet(updated, state.workbook.sheets);
       });
       return { ...state, workbook, ...history };
     }
@@ -1418,6 +1496,20 @@ function reducer(state, action) {
         selection: { activeCell: "A1", ranges: [{ start: "A1", end: "A1" }] },
         editingCell: null
       };
+    case "SET_FROZEN_ROWS": {
+      const workbook = updateActiveSheet(state, (s) => ({
+        ...s,
+        frozenRows: Math.max(0, action.count)
+      }));
+      return { ...state, workbook };
+    }
+    case "SET_FROZEN_COLS": {
+      const workbook = updateActiveSheet(state, (s) => ({
+        ...s,
+        frozenCols: Math.max(0, action.count)
+      }));
+      return { ...state, workbook };
+    }
     case "UNDO": {
       if (state.undoStack.length === 0) return state;
       const prev = state.undoStack[state.undoStack.length - 1];
@@ -1462,6 +1554,8 @@ function useSpreadsheetStore(initialData) {
     addSheet: () => dispatch({ type: "ADD_SHEET" }),
     renameSheet: (sheetId, name) => dispatch({ type: "RENAME_SHEET", sheetId, name }),
     deleteSheet: (sheetId) => dispatch({ type: "DELETE_SHEET", sheetId }),
+    setFrozenRows: (count) => dispatch({ type: "SET_FROZEN_ROWS", count }),
+    setFrozenCols: (count) => dispatch({ type: "SET_FROZEN_COLS", count }),
     setActiveSheet: (sheetId) => dispatch({ type: "SET_ACTIVE_SHEET", sheetId }),
     undo: () => dispatch({ type: "UNDO" }),
     redo: () => dispatch({ type: "REDO" }),
@@ -1550,11 +1644,49 @@ function RowHeader({ rowIndex }) {
   );
 }
 RowHeader.displayName = "RowHeader";
+var EXCEL_EPOCH2 = new Date(1899, 11, 30).getTime();
+function serialToDateStr(serial) {
+  const d = new Date(EXCEL_EPOCH2 + Math.floor(serial) * 864e5);
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+function serialToDateTimeStr(serial) {
+  const date = serialToDateStr(serial);
+  const fraction = serial % 1;
+  const totalSeconds = Math.round(fraction * 86400);
+  const h = String(Math.floor(totalSeconds / 3600)).padStart(2, "0");
+  const min = String(Math.floor(totalSeconds % 3600 / 60)).padStart(2, "0");
+  const s = String(totalSeconds % 60).padStart(2, "0");
+  return `${date} ${h}:${min}:${s}`;
+}
+function isDateFormula(formula) {
+  if (!formula) return false;
+  const f = formula.toUpperCase();
+  return /^(TODAY|NOW|DATE|EDATE)\b/.test(f) || /\b(TODAY|NOW|DATE|EDATE)\s*\(/.test(f);
+}
+function formatCellValue(val, cell) {
+  if (val === null || val === void 0) return "";
+  const fmt = cell?.format?.displayFormat;
+  if (typeof val === "number") {
+    if (fmt === "date") return serialToDateStr(val);
+    if (fmt === "datetime") return serialToDateTimeStr(val);
+    if (fmt === "percentage") return (val * 100).toFixed(1) + "%";
+    if (fmt === "currency") return "$" + val.toFixed(2);
+    if (fmt === "auto" || !fmt) {
+      if (cell?.formula && isDateFormula(cell.formula)) {
+        return val % 1 === 0 ? serialToDateStr(val) : serialToDateTimeStr(val);
+      }
+    }
+  }
+  if (typeof val === "boolean") return val ? "TRUE" : "FALSE";
+  return String(val);
+}
 function getCellDisplayValue2(cell) {
   if (!cell) return "";
-  if (cell.formula && cell.computedValue !== void 0) return String(cell.computedValue ?? "");
-  if (cell.value === null) return "";
-  return String(cell.value);
+  const val = cell.formula && cell.computedValue !== void 0 ? cell.computedValue : cell.value;
+  return formatCellValue(val, cell);
 }
 var Cell = memo(function Cell2({ address, row, col }) {
   const {
@@ -1850,13 +1982,42 @@ function SpreadsheetGrid({ className }) {
       children: [
         /* @__PURE__ */ jsx("div", { className: "sticky top-0 z-10", children: /* @__PURE__ */ jsx(ColumnHeaders, {}) }),
         /* @__PURE__ */ jsxs("div", { className: "relative", children: [
-          Array.from({ length: rowCount }, (_, rowIdx) => /* @__PURE__ */ jsxs("div", { className: "flex", children: [
-            /* @__PURE__ */ jsx("div", { className: "sticky left-0 z-[5]", children: /* @__PURE__ */ jsx(RowHeader, { rowIndex: rowIdx }) }),
-            Array.from({ length: columnCount }, (_2, colIdx) => {
-              const addr = toAddress(rowIdx, colIdx);
-              return /* @__PURE__ */ jsx(Cell, { address: addr, row: rowIdx, col: colIdx }, addr);
-            })
-          ] }, rowIdx)),
+          Array.from({ length: rowCount }, (_, rowIdx) => {
+            const isFrozenRow = rowIdx < activeSheet.frozenRows;
+            return /* @__PURE__ */ jsxs(
+              "div",
+              {
+                className: "flex",
+                style: isFrozenRow ? {
+                  position: "sticky",
+                  top: rowHeight + rowIdx * rowHeight,
+                  zIndex: 8,
+                  backgroundColor: "inherit"
+                } : void 0,
+                children: [
+                  /* @__PURE__ */ jsx("div", { className: "sticky left-0 z-[5]", children: /* @__PURE__ */ jsx(RowHeader, { rowIndex: rowIdx }) }),
+                  Array.from({ length: columnCount }, (_2, colIdx) => {
+                    const addr = toAddress(rowIdx, colIdx);
+                    const isFrozenCol = colIdx < activeSheet.frozenCols;
+                    return /* @__PURE__ */ jsx(
+                      "div",
+                      {
+                        style: isFrozenCol ? {
+                          position: "sticky",
+                          left: 48 + Array.from({ length: colIdx }, (_3, c) => getColumnWidth(c)).reduce((a, b) => a + b, 0),
+                          zIndex: isFrozenRow ? 9 : 6,
+                          backgroundColor: "inherit"
+                        } : void 0,
+                        children: /* @__PURE__ */ jsx(Cell, { address: addr, row: rowIdx, col: colIdx })
+                      },
+                      addr
+                    );
+                  })
+                ]
+              },
+              rowIdx
+            );
+          }),
           /* @__PURE__ */ jsx(SelectionOverlay, {}),
           editorPosition && /* @__PURE__ */ jsx(
             "div",