@pixerate/editor 0.3.0 → 0.4.0

package/dist/index.js

@@ -1212,23 +1212,1275 @@ var EditorController = class {
 function createEditor(options = {}) {
   return new EditorController(options);
 }
+
+// src/spreadsheet/formula/lexer.ts
+function tokenizeFormula(formula) {
+  const tokens = [];
+  let input = formula.trim();
+  let offset = 0;
+  if (input.startsWith("=")) {
+    input = input.slice(1);
+    offset = 1;
+  }
+  let i = 0;
+  while (i < input.length) {
+    const char = input[i];
+    if (/\s/.test(char)) {
+      i++;
+      continue;
+    }
+    if (/\d/.test(char) || char === "." && i + 1 < input.length && /\d/.test(input[i + 1])) {
+      const start = i;
+      let hasDot = char === ".";
+      i++;
+      while (i < input.length && (/\d/.test(input[i]) || input[i] === "." && !hasDot)) {
+        if (input[i] === ".") hasDot = true;
+        i++;
+      }
+      tokens.push({
+        type: "NUMBER",
+        value: input.slice(start, i),
+        position: start + offset
+      });
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      const quote = char;
+      const start = i;
+      i++;
+      let str = "";
+      while (i < input.length && input[i] !== quote) {
+        if (input[i] === "\\" && i + 1 < input.length) {
+          i++;
+        }
+        str += input[i];
+        i++;
+      }
+      if (i < input.length && input[i] === quote) {
+        i++;
+      }
+      tokens.push({
+        type: "STRING",
+        value: str,
+        position: start + offset
+      });
+      continue;
+    }
+    if (char === "[") {
+      const start = i;
+      i++;
+      let prop = "";
+      while (i < input.length && input[i] !== "]") {
+        prop += input[i];
+        i++;
+      }
+      if (i < input.length && input[i] === "]") {
+        i++;
+      }
+      tokens.push({
+        type: "PROPERTY_REF",
+        value: prop.trim(),
+        position: start + offset
+      });
+      continue;
+    }
+    if (char === "(") {
+      tokens.push({ type: "LPAREN", value: "(", position: i + offset });
+      i++;
+      continue;
+    }
+    if (char === ")") {
+      tokens.push({ type: "RPAREN", value: ")", position: i + offset });
+      i++;
+      continue;
+    }
+    if (char === ",") {
+      tokens.push({ type: "COMMA", value: ",", position: i + offset });
+      i++;
+      continue;
+    }
+    const twoChars = input.slice(i, i + 2);
+    if (["<=", ">=", "<>", "!="].includes(twoChars)) {
+      tokens.push({
+        type: "OPERATOR",
+        value: twoChars === "!=" ? "<>" : twoChars,
+        position: i + offset
+      });
+      i += 2;
+      continue;
+    }
+    if (["+", "-", "*", "/", "^", "&", "=", "<", ">"].includes(char)) {
+      tokens.push({ type: "OPERATOR", value: char, position: i + offset });
+      i++;
+      continue;
+    }
+    if (/[a-zA-Z_$]/.test(char)) {
+      const start = i;
+      while (i < input.length && /[a-zA-Z0-9_$.]/.test(input[i])) {
+        i++;
+      }
+      const rawWord = input.slice(start, i);
+      if (i < input.length && input[i] === ":") {
+        const colonPos = i;
+        i++;
+        const secondStart = i;
+        while (i < input.length && /[a-zA-Z0-9_$.]/.test(input[i])) {
+          i++;
+        }
+        const secondWord = input.slice(secondStart, i);
+        if (secondWord.length > 0) {
+          tokens.push({
+            type: "RANGE",
+            value: `${rawWord}:${secondWord}`.toUpperCase(),
+            position: start + offset
+          });
+          continue;
+        } else {
+          i = colonPos;
+        }
+      }
+      const upper = rawWord.toUpperCase();
+      if (upper === "TRUE" || upper === "FALSE") {
+        tokens.push({
+          type: "BOOLEAN",
+          value: upper,
+          position: start + offset
+        });
+        continue;
+      }
+      if (/^\$?[A-Za-z]+\$?[0-9]+$/.test(rawWord)) {
+        tokens.push({
+          type: "CELL_REF",
+          value: upper.replace(/\$/g, ""),
+          position: start + offset
+        });
+        continue;
+      }
+      tokens.push({
+        type: "IDENTIFIER",
+        value: upper,
+        position: start + offset
+      });
+      continue;
+    }
+    i++;
+  }
+  tokens.push({ type: "EOF", value: "", position: input.length + offset });
+  return tokens;
+}
+
+// src/spreadsheet/formula/parser.ts
+function parseCellReference(ref) {
+  const match = ref.match(/^([A-Za-z]+)(\d+)$/);
+  if (!match) {
+    throw new Error(`Invalid cell reference: ${ref}`);
+  }
+  return {
+    col: match[1].toUpperCase(),
+    row: parseInt(match[2], 10)
+  };
+}
+function parseRange(rangeStr) {
+  const [start, end] = rangeStr.split(":");
+  const startRef = parseCellReference(start);
+  const endRef = parseCellReference(end);
+  return {
+    type: "Range",
+    raw: rangeStr.toUpperCase(),
+    startCol: startRef.col,
+    startRow: startRef.row,
+    endCol: endRef.col,
+    endRow: endRef.row
+  };
+}
+var FormulaParser = class {
+  tokens = [];
+  current = 0;
+  constructor(tokens) {
+    this.tokens = tokens;
+  }
+  parse() {
+    if (this.peek().type === "EOF") {
+      return { type: "Literal", value: "" };
+    }
+    const expr = this.expression();
+    if (this.peek().type !== "EOF") {
+      throw new Error(`Unexpected token at position ${this.peek().position}: ${this.peek().value}`);
+    }
+    return expr;
+  }
+  expression() {
+    return this.comparison();
+  }
+  comparison() {
+    let expr = this.concatenation();
+    while (this.matchOperator("=", "<>", "<", ">", "<=", ">=")) {
+      const op = this.previous().value;
+      const right = this.concatenation();
+      expr = { type: "BinaryOp", op, left: expr, right };
+    }
+    return expr;
+  }
+  concatenation() {
+    let expr = this.addition();
+    while (this.matchOperator("&")) {
+      const op = this.previous().value;
+      const right = this.addition();
+      expr = { type: "BinaryOp", op, left: expr, right };
+    }
+    return expr;
+  }
+  addition() {
+    let expr = this.multiplication();
+    while (this.matchOperator("+", "-")) {
+      const op = this.previous().value;
+      const right = this.multiplication();
+      expr = { type: "BinaryOp", op, left: expr, right };
+    }
+    return expr;
+  }
+  multiplication() {
+    let expr = this.exponentiation();
+    while (this.matchOperator("*", "/")) {
+      const op = this.previous().value;
+      const right = this.exponentiation();
+      expr = { type: "BinaryOp", op, left: expr, right };
+    }
+    return expr;
+  }
+  exponentiation() {
+    let expr = this.unary();
+    while (this.matchOperator("^")) {
+      const op = this.previous().value;
+      const right = this.unary();
+      expr = { type: "BinaryOp", op, left: expr, right };
+    }
+    return expr;
+  }
+  unary() {
+    if (this.matchOperator("-", "+")) {
+      const op = this.previous().value;
+      const argument = this.unary();
+      return { type: "UnaryOp", op, argument };
+    }
+    return this.primary();
+  }
+  primary() {
+    const token = this.peek();
+    if (token.type === "NUMBER") {
+      this.advance();
+      return { type: "Literal", value: parseFloat(token.value) };
+    }
+    if (token.type === "STRING") {
+      this.advance();
+      return { type: "Literal", value: token.value };
+    }
+    if (token.type === "BOOLEAN") {
+      this.advance();
+      return { type: "Literal", value: token.value === "TRUE" };
+    }
+    if (token.type === "CELL_REF") {
+      this.advance();
+      const parsed = parseCellReference(token.value);
+      return {
+        type: "CellRef",
+        ref: token.value,
+        col: parsed.col,
+        row: parsed.row
+      };
+    }
+    if (token.type === "RANGE") {
+      this.advance();
+      return parseRange(token.value);
+    }
+    if (token.type === "PROPERTY_REF") {
+      this.advance();
+      return {
+        type: "PropertyRef",
+        property: token.value
+      };
+    }
+    if (token.type === "IDENTIFIER") {
+      const name = token.value;
+      this.advance();
+      if (this.check("LPAREN")) {
+        this.consume("LPAREN", `Expected '(' after function ${name}`);
+        const args = [];
+        if (!this.check("RPAREN")) {
+          do {
+            args.push(this.expression());
+          } while (this.match("COMMA"));
+        }
+        this.consume("RPAREN", `Expected ')' after function arguments`);
+        return {
+          type: "FunctionCall",
+          name,
+          args
+        };
+      }
+      return { type: "Literal", value: name };
+    }
+    if (this.match("LPAREN")) {
+      const expr = this.expression();
+      this.consume("RPAREN", `Expected ')' after expression`);
+      return expr;
+    }
+    throw new Error(`Unexpected token at position ${token.position}: ${token.value || token.type}`);
+  }
+  match(...types) {
+    for (const type of types) {
+      if (this.check(type)) {
+        this.advance();
+        return true;
+      }
+    }
+    return false;
+  }
+  matchOperator(...ops) {
+    if (this.check("OPERATOR") && ops.includes(this.peek().value)) {
+      this.advance();
+      return true;
+    }
+    return false;
+  }
+  check(type) {
+    if (this.isAtEnd()) return false;
+    return this.peek().type === type;
+  }
+  advance() {
+    if (!this.isAtEnd()) this.current++;
+    return this.previous();
+  }
+  isAtEnd() {
+    return this.peek().type === "EOF";
+  }
+  peek() {
+    return this.tokens[this.current];
+  }
+  previous() {
+    return this.tokens[this.current - 1];
+  }
+  consume(type, message) {
+    if (this.check(type)) return this.advance();
+    throw new Error(message);
+  }
+};
+function parseFormula(formula) {
+  const tokens = tokenizeFormula(formula);
+  const parser = new FormulaParser(tokens);
+  return parser.parse();
+}
+
+// src/spreadsheet/formula/evaluator.ts
+function colNameToIndex(col) {
+  let index = 0;
+  const upper = col.toUpperCase();
+  for (let i = 0; i < upper.length; i++) {
+    index = index * 26 + (upper.charCodeAt(i) - 65 + 1);
+  }
+  return index - 1;
+}
+function indexToColName(index) {
+  let num = index + 1;
+  let name = "";
+  while (num > 0) {
+    const mod = (num - 1) % 26;
+    name = String.fromCharCode(65 + mod) + name;
+    num = Math.floor((num - mod) / 26);
+  }
+  return name;
+}
+var FormulaEvaluator = class {
+  context;
+  constructor(context = {}) {
+    this.context = context;
+  }
+  evaluate(astOrFormula) {
+    const ast = typeof astOrFormula === "string" ? parseFormula(astOrFormula) : astOrFormula;
+    return this.evaluateNode(ast);
+  }
+  evaluateNode(node) {
+    switch (node.type) {
+      case "Literal":
+        return node.value;
+      case "CellRef": {
+        if (!this.context.resolveCell) {
+          throw new Error(`Cannot resolve cell reference ${node.ref}: no cell resolver provided`);
+        }
+        return this.context.resolveCell(node.col, node.row);
+      }
+      case "Range": {
+        if (!this.context.resolveRange) {
+          throw new Error(`Cannot resolve range ${node.raw}: no range resolver provided`);
+        }
+        return this.context.resolveRange(node.startCol, node.startRow, node.endCol, node.endRow);
+      }
+      case "PropertyRef": {
+        if (!this.context.resolveProperty) {
+          throw new Error(`Cannot resolve property [${node.property}]: no property resolver provided`);
+        }
+        return this.context.resolveProperty(node.property);
+      }
+      case "UnaryOp": {
+        const val = this.evaluateNode(node.argument);
+        if (node.op === "-") return -Number(val);
+        if (node.op === "+") return +Number(val);
+        throw new Error(`Unsupported unary operator: ${node.op}`);
+      }
+      case "BinaryOp": {
+        const left = this.evaluateNode(node.left);
+        const right = this.evaluateNode(node.right);
+        switch (node.op) {
+          case "+":
+            return Number(left) + Number(right);
+          case "-":
+            return Number(left) - Number(right);
+          case "*":
+            return Number(left) * Number(right);
+          case "/": {
+            const denom = Number(right);
+            if (denom === 0) return "#DIV/0!";
+            return Number(left) / denom;
+          }
+          case "^":
+            return Math.pow(Number(left), Number(right));
+          case "&":
+            return `${left ?? ""}${right ?? ""}`;
+          case "=":
+            return String(left).toLowerCase() === String(right).toLowerCase();
+          case "<>":
+            return String(left).toLowerCase() !== String(right).toLowerCase();
+          case "<":
+            return Number(left) < Number(right);
+          case "<=":
+            return Number(left) <= Number(right);
+          case ">":
+            return Number(left) > Number(right);
+          case ">=":
+            return Number(left) >= Number(right);
+          default:
+            throw new Error(`Unsupported binary operator: ${node.op}`);
+        }
+      }
+      case "FunctionCall": {
+        return this.callFunction(node.name, node.args);
+      }
+      default:
+        throw new Error(`Unknown AST node: ${node.type}`);
+    }
+  }
+  callFunction(name, args) {
+    const fnName = name.toUpperCase();
+    const evaluateAndFlatten = () => {
+      const items = [];
+      for (const arg of args) {
+        const val = this.evaluateNode(arg);
+        if (Array.isArray(val)) {
+          items.push(...val);
+        } else {
+          items.push(val);
+        }
+      }
+      return items;
+    };
+    switch (fnName) {
+      case "SUM": {
+        const items = evaluateAndFlatten();
+        let total = 0;
+        for (const item of items) {
+          const num = Number(item);
+          if (!isNaN(num)) total += num;
+        }
+        return total;
+      }
+      case "AVERAGE": {
+        const items = evaluateAndFlatten();
+        let total = 0;
+        let count = 0;
+        for (const item of items) {
+          const num = Number(item);
+          if (!isNaN(num) && item !== "" && item !== null && item !== void 0) {
+            total += num;
+            count++;
+          }
+        }
+        return count === 0 ? 0 : total / count;
+      }
+      case "COUNT": {
+        const items = evaluateAndFlatten();
+        let count = 0;
+        for (const item of items) {
+          const num = Number(item);
+          if (!isNaN(num) && item !== "" && item !== null && item !== void 0) {
+            count++;
+          }
+        }
+        return count;
+      }
+      case "COUNTA": {
+        const items = evaluateAndFlatten();
+        let count = 0;
+        for (const item of items) {
+          if (item !== "" && item !== null && item !== void 0) {
+            count++;
+          }
+        }
+        return count;
+      }
+      case "MIN": {
+        const items = evaluateAndFlatten().map(Number).filter((n) => !isNaN(n));
+        return items.length === 0 ? 0 : Math.min(...items);
+      }
+      case "MAX": {
+        const items = evaluateAndFlatten().map(Number).filter((n) => !isNaN(n));
+        return items.length === 0 ? 0 : Math.max(...items);
+      }
+      case "IF": {
+        if (args.length < 2) throw new Error("IF requires at least 2 arguments");
+        const condition = Boolean(this.evaluateNode(args[0]));
+        if (condition) {
+          return this.evaluateNode(args[1]);
+        } else {
+          return args.length > 2 ? this.evaluateNode(args[2]) : false;
+        }
+      }
+      case "CONCAT": {
+        const items = evaluateAndFlatten();
+        return items.map((i) => i === null || i === void 0 ? "" : String(i)).join("");
+      }
+      case "UPPER": {
+        if (args.length !== 1) throw new Error("UPPER requires 1 argument");
+        const val = this.evaluateNode(args[0]);
+        return String(val ?? "").toUpperCase();
+      }
+      case "LOWER": {
+        if (args.length !== 1) throw new Error("LOWER requires 1 argument");
+        const val = this.evaluateNode(args[0]);
+        return String(val ?? "").toLowerCase();
+      }
+      case "TRIM": {
+        if (args.length !== 1) throw new Error("TRIM requires 1 argument");
+        const val = this.evaluateNode(args[0]);
+        return String(val ?? "").trim();
+      }
+      case "LEN": {
+        if (args.length !== 1) throw new Error("LEN requires 1 argument");
+        const val = this.evaluateNode(args[0]);
+        return String(val ?? "").length;
+      }
+      case "ROUND": {
+        if (args.length < 1) throw new Error("ROUND requires at least 1 argument");
+        const num = Number(this.evaluateNode(args[0]));
+        const decimals = args.length > 1 ? Number(this.evaluateNode(args[1])) : 0;
+        const factor = Math.pow(10, decimals);
+        return Math.round(num * factor) / factor;
+      }
+      case "ABS": {
+        if (args.length !== 1) throw new Error("ABS requires 1 argument");
+        return Math.abs(Number(this.evaluateNode(args[0])));
+      }
+      case "TODAY": {
+        return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      }
+      case "DAYS": {
+        if (args.length !== 2) throw new Error("DAYS requires 2 arguments (end_date, start_date)");
+        const d1 = new Date(this.evaluateNode(args[0]));
+        const d2 = new Date(this.evaluateNode(args[1]));
+        const diffTime = d1.getTime() - d2.getTime();
+        return Math.round(diffTime / (1e3 * 60 * 60 * 24));
+      }
+      default:
+        throw new Error(`Unknown function: ${fnName}`);
+    }
+  }
+};
+
+// src/spreadsheet/formula/dependency-graph.ts
+function extractCellDependencies(node) {
+  const deps = [];
+  const visit = (curr) => {
+    if (curr.type === "CellRef") {
+      deps.push({ col: curr.col, row: curr.row });
+    } else if (curr.type === "Range") {
+      const startC = colNameToIndex(curr.startCol);
+      const endC = colNameToIndex(curr.endCol);
+      const minC = Math.min(startC, endC);
+      const maxC = Math.max(startC, endC);
+      const minR = Math.min(curr.startRow, curr.endRow);
+      const maxR = Math.max(curr.startRow, curr.endRow);
+      for (let c = minC; c <= maxC; c++) {
+        for (let r = minR; r <= maxR; r++) {
+          deps.push({ col: indexToColName(c), row: r });
+        }
+      }
+    } else if (curr.type === "BinaryOp") {
+      visit(curr.left);
+      visit(curr.right);
+    } else if (curr.type === "UnaryOp") {
+      visit(curr.argument);
+    } else if (curr.type === "FunctionCall") {
+      curr.args.forEach(visit);
+    }
+  };
+  visit(node);
+  return deps;
+}
+var DependencyGraph = class {
+  // Map of cellKey (e.g. "B2") -> Set of cellKeys that this cell depends ON
+  dependencies = /* @__PURE__ */ new Map();
+  // Map of cellKey (e.g. "A1") -> Set of cellKeys that depend ON this cell (dependents)
+  dependents = /* @__PURE__ */ new Map();
+  setCellFormula(cellKey, formulaStr) {
+    const key = cellKey.toUpperCase();
+    const oldDeps = this.dependencies.get(key) || /* @__PURE__ */ new Set();
+    for (const dep of oldDeps) {
+      this.dependents.get(dep)?.delete(key);
+    }
+    this.dependencies.delete(key);
+    if (!formulaStr || !formulaStr.startsWith("=")) {
+      return;
+    }
+    try {
+      const ast = parseFormula(formulaStr);
+      const deps = extractCellDependencies(ast);
+      const newDeps = /* @__PURE__ */ new Set();
+      for (const d of deps) {
+        const depKey = `${d.col}${d.row}`.toUpperCase();
+        newDeps.add(depKey);
+        if (!this.dependents.has(depKey)) {
+          this.dependents.set(depKey, /* @__PURE__ */ new Set());
+        }
+        this.dependents.get(depKey).add(key);
+      }
+      this.dependencies.set(key, newDeps);
+    } catch {
+    }
+  }
+  getDependencies(cellKey) {
+    return Array.from(this.dependencies.get(cellKey.toUpperCase()) || []);
+  }
+  getDependents(cellKey) {
+    return Array.from(this.dependents.get(cellKey.toUpperCase()) || []);
+  }
+  /**
+   * Detects if there is a cycle containing cellKey.
+   */
+  hasCycle(cellKey) {
+    const key = cellKey.toUpperCase();
+    const visited = /* @__PURE__ */ new Set();
+    const recStack = /* @__PURE__ */ new Set();
+    const dfs = (node) => {
+      visited.add(node);
+      recStack.add(node);
+      const deps = this.dependencies.get(node) || /* @__PURE__ */ new Set();
+      for (const neighbor of deps) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor)) return true;
+        } else if (recStack.has(neighbor)) {
+          return true;
+        }
+      }
+      recStack.delete(node);
+      return false;
+    };
+    return dfs(key);
+  }
+  /**
+   * Returns cells affected by updating cellKey in topological order.
+   */
+  getEvaluationOrder(startCellKey) {
+    const start = startCellKey.toUpperCase();
+    const visited = /* @__PURE__ */ new Set();
+    const recStack = /* @__PURE__ */ new Set();
+    const order = [];
+    let cycleDetected = false;
+    const affected = /* @__PURE__ */ new Set();
+    const collectAffected = (node) => {
+      affected.add(node);
+      const directDependents = this.dependents.get(node) || /* @__PURE__ */ new Set();
+      for (const dep of directDependents) {
+        if (!affected.has(dep)) {
+          collectAffected(dep);
+        }
+      }
+    };
+    collectAffected(start);
+    const visit = (node) => {
+      if (recStack.has(node)) {
+        cycleDetected = true;
+        return;
+      }
+      if (visited.has(node)) return;
+      recStack.add(node);
+      visited.add(node);
+      const deps = this.dependencies.get(node) || /* @__PURE__ */ new Set();
+      for (const neighbor of deps) {
+        if (affected.has(neighbor)) {
+          visit(neighbor);
+        }
+      }
+      recStack.delete(node);
+      order.push(node);
+    };
+    for (const node of affected) {
+      if (!visited.has(node)) {
+        visit(node);
+      }
+    }
+    return { order, hasCycle: cycleDetected };
+  }
+};
+
+// src/spreadsheet/datasource/index.ts
+var DataSourceBinder = class {
+  dataSources = /* @__PURE__ */ new Map();
+  register(dataSource) {
+    this.dataSources.set(dataSource.id, dataSource);
+  }
+  unregister(dataSourceId) {
+    this.dataSources.delete(dataSourceId);
+  }
+  getDataSource(id) {
+    return this.dataSources.get(id);
+  }
+  /**
+   * Generates or reconciles spreadsheet rows from a primary data source.
+   */
+  syncRows(currentRows, dataSourceId) {
+    const ds = this.dataSources.get(dataSourceId);
+    if (!ds) return currentRows;
+    const records = ds.getRecords();
+    const existingRecordRowMap = /* @__PURE__ */ new Map();
+    const freeformRows = [];
+    for (const row of currentRows) {
+      if (row.type === "record" && row.recordId) {
+        existingRecordRowMap.set(row.recordId, row);
+      } else {
+        freeformRows.push(row);
+      }
+    }
+    const nextRows = [];
+    let rowIndex = 0;
+    for (const record of records) {
+      const existing = existingRecordRowMap.get(record.id);
+      nextRows.push({
+        id: existing?.id || `row_${record.id}`,
+        index: rowIndex++,
+        height: existing?.height || 32,
+        recordId: record.id,
+        type: "record"
+      });
+      existingRecordRowMap.delete(record.id);
+    }
+    for (const freeform of freeformRows) {
+      nextRows.push({
+        ...freeform,
+        index: rowIndex++
+      });
+    }
+    return nextRows;
+  }
+  /**
+   * Resolves a record's bound field value.
+   */
+  resolveBoundValue(dataSourceId, recordId, field) {
+    const ds = this.dataSources.get(dataSourceId);
+    if (!ds) return void 0;
+    const records = ds.getRecords();
+    const record = records.find((r) => r.id === recordId);
+    return record ? record[field] : void 0;
+  }
+  /**
+   * Dispatches an update to the underlying data source.
+   */
+  async commitBoundValue(dataSourceId, recordId, field, value) {
+    const ds = this.dataSources.get(dataSourceId);
+    if (!ds) return;
+    await ds.updateRecord(recordId, field, value);
+  }
+};
+
+// src/spreadsheet/controller.ts
+var SpreadsheetController = class {
+  document;
+  activeCell = null;
+  selectedRange = null;
+  editingCell = null;
+  draftValue = "";
+  binder = new DataSourceBinder();
+  depGraph = new DependencyGraph();
+  evaluator;
+  primaryDataSourceId;
+  onDocumentChange;
+  onSelectionChange;
+  onCellCommit;
+  // History stack for undo/redo
+  undoStack = [];
+  redoStack = [];
+  isApplyingHistory = false;
+  constructor(options = {}) {
+    const defaultCols = [
+      { id: "col_a", key: "A", title: "A", width: 120, type: "freeform" },
+      { id: "col_b", key: "B", title: "B", width: 120, type: "freeform" },
+      { id: "col_c", key: "C", title: "C", width: 120, type: "freeform" },
+      { id: "col_d", key: "D", title: "D", width: 120, type: "freeform" }
+    ];
+    const defaultRows = options.primaryDataSourceId ? [] : Array.from({ length: 10 }, (_, i) => ({
+      id: `row_${i + 1}`,
+      index: i,
+      height: 32,
+      type: "freeform"
+    }));
+    this.document = {
+      id: options.document?.id || `sheet_${Date.now()}`,
+      name: options.document?.name || "Sheet 1",
+      columns: options.document?.columns || defaultCols,
+      rows: options.document?.rows || defaultRows,
+      cells: options.document?.cells || {},
+      createdAt: options.document?.createdAt || Date.now(),
+      updatedAt: options.document?.updatedAt || Date.now()
+    };
+    this.primaryDataSourceId = options.primaryDataSourceId;
+    this.onDocumentChange = options.onDocumentChange;
+    this.onSelectionChange = options.onSelectionChange;
+    this.onCellCommit = options.onCellCommit;
+    if (options.dataSources) {
+      options.dataSources.forEach((ds) => this.binder.register(ds));
+    }
+    this.evaluator = new FormulaEvaluator({
+      resolveCell: (colStr, rowNum) => this.resolveCellByCoord(colStr, rowNum),
+      resolveRange: (sCol, sRow, eCol, eRow) => this.resolveRangeByCoords(sCol, sRow, eCol, eRow),
+      resolveProperty: (prop) => this.resolveCurrentRowProperty(prop)
+    });
+    this.syncWithDataSource();
+    this.recalculateAll();
+  }
+  registerDataSource(ds) {
+    this.binder.register(ds);
+    this.syncWithDataSource();
+    this.recalculateAll();
+  }
+  setPrimaryDataSource(dataSourceId) {
+    this.primaryDataSourceId = dataSourceId;
+    this.syncWithDataSource();
+    this.recalculateAll();
+  }
+  syncWithDataSource() {
+    if (!this.primaryDataSourceId) return;
+    this.document.rows = this.binder.syncRows(this.document.rows, this.primaryDataSourceId);
+    this.recomputeRowIndices();
+  }
+  recomputeRowIndices() {
+    this.document.rows.forEach((r, idx) => {
+      r.index = idx;
+    });
+    this.document.columns.forEach((c, idx) => {
+      c.key = indexToColName(idx);
+    });
+  }
+  getColumn(colIdOrKey) {
+    return this.document.columns.find(
+      (c) => c.id === colIdOrKey || c.key.toUpperCase() === colIdOrKey.toUpperCase()
+    );
+  }
+  getRow(rowIdOrIndex) {
+    if (typeof rowIdOrIndex === "number") {
+      return this.document.rows[rowIdOrIndex];
+    }
+    return this.document.rows.find((r) => r.id === rowIdOrIndex);
+  }
+  getCell(rowId, colId) {
+    const existing = this.document.cells[rowId]?.[colId];
+    if (existing) return existing;
+    const col = this.document.columns.find((c) => c.id === colId);
+    const row = this.document.rows.find((r) => r.id === rowId);
+    if (col && row && col.type === "bound" && col.binding && row.recordId) {
+      const boundVal = this.binder.resolveBoundValue(
+        col.binding.dataSource,
+        row.recordId,
+        col.binding.field
+      );
+      return {
+        raw: boundVal !== void 0 ? String(boundVal) : "",
+        value: boundVal ?? "",
+        format: col.format
+      };
+    }
+    if (col && col.type === "formula" && col.formula) {
+      return {
+        raw: col.formula,
+        value: "",
+        format: col.format
+      };
+    }
+    return { raw: "", value: "", format: col?.format };
+  }
+  setCellValue(rowId, colId, raw) {
+    this.recordSnapshot();
+    if (!this.document.cells[rowId]) {
+      this.document.cells[rowId] = {};
+    }
+    const col = this.document.columns.find((c) => c.id === colId);
+    const row = this.document.rows.find((r) => r.id === rowId);
+    if (col?.type === "bound" && col.binding && row?.recordId) {
+      this.binder.commitBoundValue(
+        col.binding.dataSource,
+        row.recordId,
+        col.binding.field,
+        raw
+      );
+    }
+    const cellKey = this.getCellKey(rowId, colId);
+    this.depGraph.setCellFormula(cellKey, raw.startsWith("=") ? raw : null);
+    this.document.cells[rowId][colId] = {
+      raw,
+      value: raw,
+      format: col?.format
+    };
+    this.document.updatedAt = Date.now();
+    this.recalculateCell(rowId, colId);
+    this.notifyChange();
+    const evaluatedVal = this.document.cells[rowId][colId]?.value;
+    this.onCellCommit?.(rowId, colId, raw, evaluatedVal);
+  }
+  getCellKey(rowId, colId) {
+    const row = this.document.rows.find((r) => r.id === rowId);
+    const col = this.document.columns.find((c) => c.id === colId);
+    if (!row || !col) return `${colId}_${rowId}`;
+    return `${col.key}${row.index + 1}`.toUpperCase();
+  }
+  recalculateCell(rowId, colId) {
+    const cellKey = this.getCellKey(rowId, colId);
+    const { order, hasCycle } = this.depGraph.getEvaluationOrder(cellKey);
+    if (hasCycle) {
+      if (this.document.cells[rowId]?.[colId]) {
+        this.document.cells[rowId][colId].error = "#CYCLE!";
+        this.document.cells[rowId][colId].value = "#CYCLE!";
+      }
+      return;
+    }
+    for (const key of order) {
+      this.evalSingleCellByKey(key);
+    }
+  }
+  recalculateAll() {
+    for (const row of this.document.rows) {
+      for (const col of this.document.columns) {
+        const cell = this.getCell(row.id, col.id);
+        const cellKey = `${col.key}${row.index + 1}`.toUpperCase();
+        if (cell.raw.startsWith("=")) {
+          this.depGraph.setCellFormula(cellKey, cell.raw);
+        }
+      }
+    }
+    for (const row of this.document.rows) {
+      for (const col of this.document.columns) {
+        const cellKey = `${col.key}${row.index + 1}`.toUpperCase();
+        this.evalSingleCellByKey(cellKey);
+      }
+    }
+  }
+  evalSingleCellByKey(cellKey) {
+    const match = cellKey.match(/^([A-Za-z]+)(\d+)$/);
+    if (!match) return;
+    const colName = match[1].toUpperCase();
+    const rowNum = parseInt(match[2], 10);
+    const col = this.document.columns.find((c) => c.key.toUpperCase() === colName);
+    const row = this.document.rows[rowNum - 1];
+    if (!col || !row) return;
+    const cell = this.getCell(row.id, col.id);
+    if (!cell.raw.startsWith("=")) {
+      if (cell.error === "#CYCLE!") {
+        cell.error = void 0;
+      }
+      return;
+    }
+    try {
+      const computed = this.evaluator.evaluate(cell.raw);
+      if (!this.document.cells[row.id]) {
+        this.document.cells[row.id] = {};
+      }
+      this.document.cells[row.id][col.id] = {
+        ...cell,
+        value: computed,
+        error: void 0
+      };
+    } catch (err) {
+      if (!this.document.cells[row.id]) {
+        this.document.cells[row.id] = {};
+      }
+      this.document.cells[row.id][col.id] = {
+        ...cell,
+        value: "#ERROR!",
+        error: err?.message || "Formula error"
+      };
+    }
+  }
+  resolveCellByCoord(colStr, rowNum) {
+    const col = this.document.columns.find((c) => c.key.toUpperCase() === colStr.toUpperCase());
+    const row = this.document.rows[rowNum - 1];
+    if (!col || !row) return 0;
+    const cell = this.getCell(row.id, col.id);
+    return cell.value !== void 0 && cell.value !== "" ? cell.value : 0;
+  }
+  resolveRangeByCoords(sCol, sRow, eCol, eRow) {
+    const startC = colNameToIndex(sCol);
+    const endC = colNameToIndex(eCol);
+    const minC = Math.min(startC, endC);
+    const maxC = Math.max(startC, endC);
+    const minR = Math.min(sRow, eRow);
+    const maxR = Math.max(sRow, eRow);
+    const results = [];
+    for (let c = minC; c <= maxC; c++) {
+      const colName = indexToColName(c);
+      const col = this.document.columns.find((colDef) => colDef.key.toUpperCase() === colName);
+      if (!col) continue;
+      for (let r = minR; r <= maxR; r++) {
+        const row = this.document.rows[r - 1];
+        if (!row) continue;
+        const cell = this.getCell(row.id, col.id);
+        results.push(cell.value !== void 0 && cell.value !== "" ? cell.value : 0);
+      }
+    }
+    return results;
+  }
+  resolveCurrentRowProperty(prop) {
+    if (!this.activeCell) return 0;
+    const row = this.document.rows[this.activeCell.row];
+    if (!row || !row.recordId || !this.primaryDataSourceId) return 0;
+    return this.binder.resolveBoundValue(this.primaryDataSourceId, row.recordId, prop) ?? 0;
+  }
+  // --- Selection and Navigation ---
+  selectCell(row, col, extendSelection = false) {
+    const clampedRow = Math.max(0, Math.min(row, this.document.rows.length - 1));
+    const clampedCol = Math.max(0, Math.min(col, this.document.columns.length - 1));
+    const rowObj = this.document.rows[clampedRow];
+    const colObj = this.document.columns[clampedCol];
+    this.activeCell = {
+      row: clampedRow,
+      col: clampedCol,
+      rowId: rowObj?.id,
+      colId: colObj?.id
+    };
+    if (extendSelection && this.selectedRange) {
+      this.selectedRange = {
+        startRow: this.selectedRange.startRow,
+        startCol: this.selectedRange.startCol,
+        endRow: clampedRow,
+        endCol: clampedCol
+      };
+    } else {
+      this.selectedRange = {
+        startRow: clampedRow,
+        startCol: clampedCol,
+        endRow: clampedRow,
+        endCol: clampedCol
+      };
+    }
+    this.onSelectionChange?.(this.activeCell, this.selectedRange);
+  }
+  selectRange(range) {
+    this.selectedRange = range;
+    this.onSelectionChange?.(this.activeCell, this.selectedRange);
+  }
+  startEditing(row, col, initialValue) {
+    const targetRow = row ?? this.activeCell?.row ?? 0;
+    const targetCol = col ?? this.activeCell?.col ?? 0;
+    this.selectCell(targetRow, targetCol);
+    const rowObj = this.document.rows[targetRow];
+    const colObj = this.document.columns[targetCol];
+    if (!rowObj || !colObj) return;
+    this.editingCell = {
+      row: targetRow,
+      col: targetCol,
+      rowId: rowObj.id,
+      colId: colObj.id
+    };
+    const cell = this.getCell(rowObj.id, colObj.id);
+    this.draftValue = initialValue !== void 0 ? initialValue : cell.raw;
+  }
+  commitEditing(valueToCommit) {
+    if (!this.editingCell) return;
+    const val = valueToCommit !== void 0 ? valueToCommit : this.draftValue;
+    if (this.editingCell.rowId && this.editingCell.colId) {
+      this.setCellValue(this.editingCell.rowId, this.editingCell.colId, val);
+    }
+    this.editingCell = null;
+    this.draftValue = "";
+  }
+  cancelEditing() {
+    this.editingCell = null;
+    this.draftValue = "";
+  }
+  moveCursor(direction, extendSelection = false) {
+    if (!this.activeCell) {
+      this.selectCell(0, 0);
+      return;
+    }
+    let nextRow = this.activeCell.row;
+    let nextCol = this.activeCell.col;
+    switch (direction) {
+      case "up":
+        nextRow = Math.max(0, nextRow - 1);
+        break;
+      case "down":
+        nextRow = Math.min(this.document.rows.length - 1, nextRow + 1);
+        break;
+      case "left":
+        nextCol = Math.max(0, nextCol - 1);
+        break;
+      case "right":
+        nextCol = Math.min(this.document.columns.length - 1, nextCol + 1);
+        break;
+    }
+    this.selectCell(nextRow, nextCol, extendSelection);
+  }
+  // --- Grid Structure Mutations ---
+  insertColumn(index, config) {
+    this.recordSnapshot();
+    const newId = config?.id || `col_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    const newCol = {
+      id: newId,
+      key: indexToColName(index),
+      title: config?.title || indexToColName(index),
+      width: config?.width || 130,
+      type: config?.type || "freeform",
+      binding: config?.binding,
+      formula: config?.formula,
+      format: config?.format || "text",
+      readOnly: config?.readOnly
+    };
+    this.document.columns.splice(index, 0, newCol);
+    this.recomputeRowIndices();
+    this.recalculateAll();
+    this.notifyChange();
+  }
+  deleteColumn(colId) {
+    this.recordSnapshot();
+    this.document.columns = this.document.columns.filter((c) => c.id !== colId);
+    for (const rowId of Object.keys(this.document.cells)) {
+      delete this.document.cells[rowId][colId];
+    }
+    this.recomputeRowIndices();
+    this.recalculateAll();
+    this.notifyChange();
+  }
+  insertRow(index, config) {
+    this.recordSnapshot();
+    const newId = config?.id || `row_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    const newRow = {
+      id: newId,
+      index,
+      height: config?.height || 32,
+      recordId: config?.recordId,
+      type: config?.type || "freeform"
+    };
+    this.document.rows.splice(index, 0, newRow);
+    this.recomputeRowIndices();
+    this.recalculateAll();
+    this.notifyChange();
+  }
+  deleteRow(rowId) {
+    this.recordSnapshot();
+    this.document.rows = this.document.rows.filter((r) => r.id !== rowId);
+    delete this.document.cells[rowId];
+    this.recomputeRowIndices();
+    this.recalculateAll();
+    this.notifyChange();
+  }
+  setColumnWidth(colId, width) {
+    const col = this.document.columns.find((c) => c.id === colId);
+    if (col) {
+      col.width = Math.max(50, width);
+      this.notifyChange();
+    }
+  }
+  // --- Clipboard TSV/CSV ---
+  exportToTsv() {
+    return this.document.rows.map(
+      (row) => this.document.columns.map((col) => {
+        const cell = this.getCell(row.id, col.id);
+        return String(cell.value ?? "").replace(/\t/g, " ");
+      }).join("	")
+    ).join("\n");
+  }
+  importFromTsv(tsvData, startRow = 0, startCol = 0) {
+    this.recordSnapshot();
+    const lines = tsvData.trim().split("\n");
+    lines.forEach((line, rIdx) => {
+      const cells = line.split("	");
+      const targetR = startRow + rIdx;
+      while (targetR >= this.document.rows.length) {
+        this.insertRow(this.document.rows.length);
+      }
+      const row = this.document.rows[targetR];
+      cells.forEach((val, cIdx) => {
+        const targetC = startCol + cIdx;
+        while (targetC >= this.document.columns.length) {
+          this.insertColumn(this.document.columns.length);
+        }
+        const col = this.document.columns[targetC];
+        this.setCellValue(row.id, col.id, val);
+      });
+    });
+    this.recalculateAll();
+    this.notifyChange();
+  }
+  // --- Undo/Redo Snapshots ---
+  recordSnapshot() {
+    if (this.isApplyingHistory) return;
+    this.undoStack.push(JSON.stringify(this.document));
+    if (this.undoStack.length > 50) this.undoStack.shift();
+    this.redoStack = [];
+  }
+  undo() {
+    if (this.undoStack.length === 0) return;
+    this.isApplyingHistory = true;
+    this.redoStack.push(JSON.stringify(this.document));
+    const previous = JSON.parse(this.undoStack.pop());
+    this.document = previous;
+    this.recalculateAll();
+    this.notifyChange();
+    this.isApplyingHistory = false;
+  }
+  redo() {
+    if (this.redoStack.length === 0) return;
+    this.isApplyingHistory = true;
+    this.undoStack.push(JSON.stringify(this.document));
+    const next = JSON.parse(this.redoStack.pop());
+    this.document = next;
+    this.recalculateAll();
+    this.notifyChange();
+    this.isApplyingHistory = false;
+  }
+  notifyChange() {
+    this.onDocumentChange?.(this.document);
+  }
+};
 export {
   ColorHighlighter,
+  DataSourceBinder,
+  DependencyGraph,
   EditorController,
   FontSize,
+  FormulaEvaluator,
+  FormulaParser,
   GradientText,
   INSTRUCTION_REGEX,
   LoadingNode,
   Mention,
   SlashCommands,
   SmilieReplacer,
+  SpreadsheetController,
   TEMPLATE_REGEX,
   TemplateSuggestions,
   VARIABLE_REGEX,
+  colNameToIndex,
   createEditor,
   createMentionExtension,
   createRichTextPreset,
   escapeHtml,
+  extractCellDependencies,
   extractInstructionNames,
   extractMentionsFromDoc,
   extractTemplateNames,
@@ -1237,14 +2489,19 @@ export {
   getEditorText,
   getLatestVersion,
   htmlToPlainText,
+  indexToColName,
   instructionRegex,
   mapRawOffsetToResolved,
   mapResolvedOffsetToRaw,
+  parseCellReference,
+  parseFormula,
+  parseRange,
   plainTextToTipTapHtml,
   resolveTemplates,
   resolveTemplatesWithMapping,
   resolveVariables,
   templateRegex,
+  tokenizeFormula,
   tokenizePrompt,
   variableRegex
 };