@pixerate/editor 0.21.0 → 0.23.0

package/dist/{chunk-GVW4P7BG.js → chunk-K3R5NG2D.js}

@@ -2,15 +2,23 @@ import {
   FormulaEvaluator,
   WHOLE_COLUMN_END_ROW,
   colNameToIndex,
+  compareValues,
+  describeFormulaError,
+  formatCellDisplay,
   getFormulaArgumentSpecIndex,
   getFormulaFunction,
   getFormulaSignature,
   getFormulaSignatureParts,
   indexToColName,
+  isFormulaError,
+  numericValue,
+  parseCellInput,
   parseFormula,
+  parseIsoDate,
   searchFormulaFunctions,
+  sortCompareValues,
   tokenizeFormula
-} from "./chunk-A7DKIA72.js";
+} from "./chunk-QBJ22YZR.js";
 
 // src/spreadsheet/formula/dependency-graph.ts
 var columnDependencyKey = (col) => `${col.toUpperCase()}:`;
@@ -19,6 +27,8 @@ function extractCellDependencies(node) {
   const visit = (curr) => {
     if (curr.type === "CellRef") {
       deps.push({ col: curr.col, row: curr.row });
+    } else if (curr.type === "SpillRef") {
+      deps.push({ col: curr.col, row: curr.row });
     } else if (curr.type === "Range" && curr.endRow >= WHOLE_COLUMN_END_ROW) {
       const startC = colNameToIndex(curr.startCol);
       const endC = colNameToIndex(curr.endCol);
@@ -54,6 +64,14 @@ var DependencyGraph = class {
   dependencies = /* @__PURE__ */ new Map();
   // Map of cellKey (e.g. "A1") -> Set of cellKeys that depend ON this cell (dependents)
   dependents = /* @__PURE__ */ new Map();
+  // Dynamic-array edges, set by the controller after evaluating an anchor:
+  // spilled cells depend on their anchor, and a blocked (#SPILL!) anchor
+  // depends on the cells blocking it. Kept apart from formula dependencies,
+  // so re-entering a formula doesn't drop them.
+  spillDependencies = /* @__PURE__ */ new Map();
+  spillDependents = /* @__PURE__ */ new Map();
+  // anchor -> the edges it registered (so they can be replaced).
+  spillEdges = /* @__PURE__ */ new Map();
   setCellFormula(cellKey, formulaStr) {
     const key = cellKey.toUpperCase();
     const oldDeps = this.dependencies.get(key) || /* @__PURE__ */ new Set();
@@ -84,12 +102,49 @@ var DependencyGraph = class {
   clear() {
     this.dependencies.clear();
     this.dependents.clear();
+    this.spillDependencies.clear();
+    this.spillDependents.clear();
+    this.spillEdges.clear();
   }
+  /**
+   * Records the dynamic-array edges of the anchor `anchorKey`, replacing its
+   * previous ones: every key in `spilledKeys` (cells holding its spilled
+   * values) depends on the anchor, and the anchor depends on every key in
+   * `blockingKeys` (cells that stop it spilling). Pass empty lists to remove
+   * the anchor's edges.
+   */
+  setSpillEdges(anchorKey, spilledKeys, blockingKeys = []) {
+    const anchor = anchorKey.toUpperCase();
+    for (const [from, to] of this.spillEdges.get(anchor) ?? []) {
+      this.spillDependencies.get(from)?.delete(to);
+      this.spillDependents.get(to)?.delete(from);
+    }
+    const edges = [];
+    for (const key of spilledKeys) edges.push([key.toUpperCase(), anchor]);
+    for (const key of blockingKeys) edges.push([anchor, key.toUpperCase()]);
+    for (const [from, to] of edges) {
+      if (!this.spillDependencies.has(from)) this.spillDependencies.set(from, /* @__PURE__ */ new Set());
+      this.spillDependencies.get(from).add(to);
+      if (!this.spillDependents.has(to)) this.spillDependents.set(to, /* @__PURE__ */ new Set());
+      this.spillDependents.get(to).add(from);
+    }
+    if (edges.length > 0) this.spillEdges.set(anchor, edges);
+    else this.spillEdges.delete(anchor);
+  }
+  /** The spilled cells registered for `anchorKey` by `setSpillEdges`. */
+  getSpilledKeys(anchorKey) {
+    const anchor = anchorKey.toUpperCase();
+    return (this.spillEdges.get(anchor) ?? []).filter(([, to]) => to === anchor).map(([from]) => from);
+  }
+  /** Formula dependencies plus dynamic-array (spill) dependencies of a cell. */
   getDependencies(cellKey) {
-    return Array.from(this.dependencies.get(cellKey.toUpperCase()) || []);
+    const key = cellKey.toUpperCase();
+    return unionOf(this.dependencies.get(key), this.spillDependencies.get(key));
   }
+  /** Cells depending on `cellKey`, through formulas or spills. */
   getDependents(cellKey) {
-    return Array.from(this.dependents.get(cellKey.toUpperCase()) || []);
+    const key = cellKey.toUpperCase();
+    return unionOf(this.dependents.get(key), this.spillDependents.get(key));
   }
   /**
    * Detects if there is a cycle containing cellKey.
@@ -101,7 +156,7 @@ var DependencyGraph = class {
     const dfs = (node) => {
       visited.add(node);
       recStack.add(node);
-      const deps = this.dependencies.get(node) || /* @__PURE__ */ new Set();
+      const deps = this.getDependencies(node);
       for (const neighbor of deps) {
         if (!visited.has(neighbor)) {
           if (dfs(neighbor)) return true;
@@ -180,6 +235,7 @@ var DependencyGraph = class {
         const node = queue.pop();
         const direct = [
           ...this.dependents.get(node) ?? [],
+          ...this.spillDependents.get(node) ?? [],
           ...this.dependents.get(columnDependencyKey(node.replace(/\d+$/, ""))) ?? []
         ];
         for (const dep of direct) {
@@ -192,7 +248,7 @@ var DependencyGraph = class {
     }
     const neighbors = (node) => {
       const result = [];
-      for (const dep of this.dependencies.get(node) ?? []) {
+      for (const dep of this.getDependencies(node)) {
         if (dep.endsWith(":")) {
           const col = dep.slice(0, -1);
           for (const candidate of nodes) {
@@ -258,6 +314,11 @@ var DependencyGraph = class {
     return { order, cyclic };
   }
 };
+function unionOf(a, b) {
+  if (!b || b.size === 0) return Array.from(a ?? []);
+  if (!a || a.size === 0) return Array.from(b);
+  return Array.from(/* @__PURE__ */ new Set([...a, ...b]));
+}
 
 // src/spreadsheet/formula/references.ts
 var CELL_PART = /^(\$?)([A-Za-z]+)(\$?)(\d+)$/;
@@ -335,11 +396,17 @@ function mapFormulaReferences(formula, rewrite) {
   let cursor = 0;
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
-    if (token.type !== "CELL_REF" && token.type !== "RANGE") continue;
+    if (token.type !== "CELL_REF" && token.type !== "RANGE" && token.type !== "SPILL_REF") continue;
     if (tokens[i + 1]?.type === "LPAREN") continue;
     let end = token.position;
     while (end < formula.length && REF_CHAR.test(formula[end])) end++;
     const original = formula.slice(token.position, end);
+    if (token.type === "SPILL_REF") {
+      const rewritten = rewrite(original);
+      result += formula.slice(cursor, token.position) + (rewritten === "#REF!" ? rewritten : `${rewritten}#`);
+      cursor = end + 1;
+      continue;
+    }
     result += formula.slice(cursor, token.position) + rewrite(original);
     cursor = end;
   }
@@ -617,28 +684,41 @@ function compareCellValues(a, b, direction = "asc") {
   const aBlank = isBlankValue(a);
   const bBlank = isBlankValue(b);
   if (aBlank || bBlank) return aBlank === bBlank ? 0 : aBlank ? 1 : -1;
-  const aNum = toNumber(a);
-  const bNum = toNumber(b);
   let result;
-  if (aNum !== null && bNum !== null) result = aNum - bNum;
-  else if (aNum !== null) result = -1;
-  else if (bNum !== null) result = 1;
-  else result = compareText(String(a), String(b));
+  if (isPlainText(a) && isPlainText(b) && !(parseIsoDate(a) && parseIsoDate(b))) {
+    result = compareText(a, b);
+  } else {
+    result = sortCompareValues(a, b);
+  }
   if (result === 0) return 0;
   return direction === "desc" ? -Math.sign(result) : Math.sign(result);
 }
+var isPlainText = (value) => typeof value === "string" && !isFormulaError(value);
+function filterValue(value) {
+  if (isBlankValue(value) || isFormulaError(value)) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? { value, kind: "number" } : null;
+  if (typeof value === "boolean") return { value, kind: "boolean" };
+  const num = numericValue(value);
+  if (num !== null) return { value: num, kind: "number" };
+  const text = String(value);
+  return { value: text, kind: parseIsoDate(text) ? "number" : "text" };
+}
+function filterOperand(operand) {
+  if (typeof operand !== "string") return filterValue(operand);
+  if (operand.trim() === "") return null;
+  const parsed = parseCellInput(operand.trim());
+  if (parsed.type === "number" || parsed.type === "date" || parsed.type === "boolean") return filterValue(parsed.value);
+  return { value: operand, kind: "text" };
+}
 function compareForFilter(value, operand) {
-  if (isBlankValue(value) || isBlankValue(operand)) return null;
-  const a = toNumber(value);
-  const b = toNumber(operand);
-  if (a !== null && b !== null) return a - b;
-  if (a !== null || b !== null) return null;
-  return compareText(String(value), String(operand));
+  const a = filterValue(value);
+  const b = filterOperand(operand);
+  if (!a || !b || a.kind !== b.kind) return null;
+  return compareValues(a.value, b.value);
 }
 function looselyEquals(value, operand) {
-  const a = toNumber(value);
-  const b = toNumber(operand);
-  if (a !== null && b !== null) return a === b;
+  const c = compareForFilter(value, operand);
+  if (c !== null) return c === 0;
   return String(value ?? "").trim().toLowerCase() === String(operand ?? "").trim().toLowerCase();
 }
 function matchesFilterRule(value, rule) {
@@ -713,7 +793,8 @@ function classifyFillValue(raw) {
   if (raw.trim() === "") return { kind: "blank" };
   const num = toNumber(raw);
   if (num !== null) return { kind: "number", value: num };
-  const date = ISO_DATE_PATTERN.exec(raw.trim());
+  const typed = parseCellInput(raw);
+  const date = ISO_DATE_PATTERN.exec(typed.type === "date" ? String(typed.value) : raw.trim());
   if (date) {
     const [year, month, day] = [Number(date[1]), Number(date[2]), Number(date[3])];
     const time = Date.UTC(year, month - 1, day);
@@ -1010,11 +1091,16 @@ function parseHtmlTable(html) {
   return rows.length > 0 ? rows : null;
 }
 function createSpreadsheetClipboardData(cells, origin) {
-  const values = cells.map((row) => row.map((cell) => cell.value));
-  const payload = { type: "pixerate-spreadsheet", version: 1, origin, cells };
+  const texts = cells.map((row) => row.map((cell) => cell.text ?? displayText(cell.value)));
+  const payload = {
+    type: "pixerate-spreadsheet",
+    version: 1,
+    origin,
+    cells: cells.map((row) => row.map(({ raw, value }) => ({ raw, value })))
+  };
   return {
-    "text/plain": serializeTsv(values.map((row) => row.map(displayText))),
-    "text/html": serializeHtmlTable(values),
+    "text/plain": serializeTsv(texts),
+    "text/html": serializeHtmlTable(texts),
     [SPREADSHEET_CLIPBOARD_MIME]: JSON.stringify(payload)
   };
 }
@@ -1228,6 +1314,9 @@ function buildSpreadsheetView(doc, getValue) {
 
 // src/spreadsheet/controller.ts
 var nextIdSequence = 0;
+var DEFAULT_MAX_HISTORY_BYTES = 64 * 1024 * 1024;
+var MAX_SPILL_PASSES = 25;
+var spillCellId = (rowId, colId) => `${rowId}\0${colId}`;
 var SpreadsheetController = class {
   document;
   activeCell = null;
@@ -1245,11 +1334,24 @@ var SpreadsheetController = class {
   undoStack = [];
   redoStack = [];
   isApplyingHistory = false;
+  maxHistoryBytes;
   // Set while importing TSV: history and recalculation are done once at the end.
   batching = false;
   pendingCommits = [];
   // Row being evaluated, so [property] references resolve per row.
   evaluatingRowIndex = null;
+  // Cell being evaluated, for implicit intersection (`=@A:A`).
+  evaluatingCell = null;
+  // Dynamic arrays. Spilled values are derived state: they live here, not in
+  // the document, and every recalculation rebuilds them.
+  spills = /* @__PURE__ */ new Map();
+  // anchor key -> spill
+  spilledBy = /* @__PURE__ */ new Map();
+  // spilled cell key -> anchor key
+  spillCells = /* @__PURE__ */ new Map();
+  // spillCellId -> displayed cell
+  // Cells whose spill ownership changed during the current pass.
+  spillChanges = null;
   constructor(options = {}) {
     const defaultCols = [
       { id: "col_a", key: "A", title: "A", width: 120, type: "freeform" },
@@ -1274,6 +1376,7 @@ var SpreadsheetController = class {
       ...options.document?.table ? { table: options.document.table } : {}
     };
     this.primaryDataSourceId = options.primaryDataSourceId;
+    this.maxHistoryBytes = Math.max(0, options.maxHistoryBytes ?? DEFAULT_MAX_HISTORY_BYTES);
     this.onDocumentChange = options.onDocumentChange;
     this.onSelectionChange = options.onSelectionChange;
     this.onCellCommit = options.onCellCommit;
@@ -1283,9 +1386,12 @@ var SpreadsheetController = class {
     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)
+      resolveProperty: (prop) => this.resolveCurrentRowProperty(prop),
+      resolveSpill: (colStr, rowNum) => this.resolveSpillByCoord(colStr, rowNum),
+      getFormulaCell: () => this.evaluatingCell
     });
     this.syncWithDataSource();
+    this.rederiveTypedValues();
     this.recalculateAll();
   }
   loadDocument(document) {
@@ -1297,9 +1403,63 @@ var SpreadsheetController = class {
     this.undoStack = [];
     this.redoStack = [];
     this.syncWithDataSource();
+    this.rederiveTypedValues();
     this.recalculateAll();
     this.notifyChange();
   }
+  /**
+   * Re-parses the value of every stored typed (non-formula) cell from its
+   * `raw` input, so documents saved before typed input was parsed (whose
+   * values are text such as `"120"`) compare and sort as numbers. Cells of
+   * bound columns in record rows keep their value: it belongs to the data
+   * source.
+   */
+  rederiveTypedValues() {
+    for (const row of this.document.rows) {
+      const cells = this.document.cells[row.id];
+      if (!cells) continue;
+      for (const col of this.document.columns) {
+        const cell = cells[col.id];
+        if (!cell || typeof cell.raw !== "string" || cell.raw.startsWith("=")) continue;
+        if (col.type === "bound" && col.binding && row.recordId) continue;
+        const typed = this.typedCell(cell.raw, cell.format);
+        cell.value = typed.value;
+        if (typed.numberFormat) cell.numberFormat = typed.numberFormat;
+        else delete cell.numberFormat;
+        if (typed.format) cell.format = typed.format;
+      }
+    }
+  }
+  /**
+   * Value of typed (non-formula) input: a number, boolean, ISO date, error
+   * or text (see `parseCellInput`), its automatic number format, and the
+   * `CellFormat` to use: the automatic one (currency, percentage, date,
+   * number) when `format` is unset or `text` (the default of new columns).
+   */
+  typedCell(raw, format) {
+    const parsed = parseCellInput(raw);
+    return {
+      value: parsed.value,
+      ...parsed.numberFormat ? { numberFormat: parsed.numberFormat } : {},
+      format: parsed.cellFormat && (!format || format === "text") ? parsed.cellFormat : format
+    };
+  }
+  /**
+   * Typed input for a bound field, coerced by the field's declared type:
+   * number, boolean and date fields get a number, boolean or ISO date when
+   * the input parses as one; string and enum fields (and unknown fields)
+   * keep the text exactly as typed.
+   */
+  boundInputValue(dataSourceId, field, raw) {
+    if (raw.startsWith("=")) return raw;
+    const type = this.binder.getDataSource(dataSourceId)?.getFields().find((f) => f.key === field)?.type;
+    if (type !== "number" && type !== "boolean" && type !== "date") return raw;
+    const parsed = parseCellInput(raw);
+    if (type === "number" && parsed.type === "number") return parsed.value;
+    if (type === "boolean" && parsed.type === "boolean") return parsed.value;
+    if (type === "date" && parsed.type === "date") return parsed.value;
+    return raw;
+  }
   registerDataSource(ds) {
     this.binder.register(ds);
     this.syncWithDataSource();
@@ -1336,6 +1496,11 @@ var SpreadsheetController = class {
   }
   getCell(rowId, colId) {
     const existing = this.document.cells[rowId]?.[colId];
+    if (existing && existing.raw !== "") return existing;
+    if (this.spillCells.size > 0) {
+      const spilled = this.spillCells.get(spillCellId(rowId, colId));
+      if (spilled) return spilled;
+    }
     if (existing) return existing;
     const col = this.document.columns.find((c) => c.id === colId);
     const row = this.document.rows.find((r) => r.id === rowId);
@@ -1371,21 +1536,20 @@ var SpreadsheetController = class {
     }
     const col = this.document.columns.find((c) => c.id === colId);
     const row = this.document.rows.find((r) => r.id === rowId);
+    const isFormula = raw.startsWith("=");
+    let cell;
     if (col?.type === "bound" && col.binding && row?.recordId) {
-      this.binder.commitBoundValue(
-        col.binding.dataSource,
-        row.recordId,
-        col.binding.field,
-        raw
-      );
+      const value = this.boundInputValue(col.binding.dataSource, col.binding.field, raw);
+      this.binder.commitBoundValue(col.binding.dataSource, row.recordId, col.binding.field, value);
+      cell = { raw, value, format: col.format };
+    } else if (isFormula) {
+      cell = { raw, value: raw, format: col?.format };
+    } else {
+      cell = { raw, ...this.typedCell(raw, col?.format) };
     }
     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.depGraph.setCellFormula(cellKey, isFormula ? raw : null);
+    this.document.cells[rowId][colId] = cell;
     this.document.updatedAt = Date.now();
     if (this.batching) {
       this.pendingCommits.push([rowId, colId, raw]);
@@ -1408,7 +1572,30 @@ var SpreadsheetController = class {
    */
   recalculateCell(rowId, colId) {
     const cellKey = this.getCellKey(rowId, colId);
-    this.runEvaluationPlan(this.depGraph.getEvaluationPlan([cellKey], { includeDependents: true }));
+    const anchor = this.spilledBy.get(cellKey);
+    this.recalculateKeys(anchor ? [cellKey, anchor] : [cellKey], true);
+  }
+  /**
+   * Recalculates `keys` (and, with `includeDependents`, their dependents) in
+   * dependency order. Spill ranges are only known after evaluating their
+   * anchors, so when a pass changes which cells hold spilled values (and so
+   * the dependency graph), the dependents of those cells are recalculated in
+   * another pass, until nothing changes.
+   */
+  recalculateKeys(keys, includeDependents) {
+    let pending = Array.from(keys);
+    let withDependents = includeDependents;
+    for (let pass = 0; pass < MAX_SPILL_PASSES && pending.length > 0; pass++) {
+      const changed = /* @__PURE__ */ new Set();
+      this.spillChanges = changed;
+      try {
+        this.runEvaluationPlan(this.depGraph.getEvaluationPlan(pending, { includeDependents: withDependents }));
+      } finally {
+        this.spillChanges = null;
+      }
+      pending = Array.from(changed);
+      withDependents = true;
+    }
   }
   /**
    * Rebuilds the dependency graph from scratch and recalculates every formula
@@ -1416,6 +1603,9 @@ var SpreadsheetController = class {
    */
   recalculateAll() {
     this.depGraph.clear();
+    this.spills.clear();
+    this.spilledBy.clear();
+    this.spillCells.clear();
     const formulaKeys = [];
     for (const row of this.document.rows) {
       for (const col of this.document.columns) {
@@ -1427,7 +1617,7 @@ var SpreadsheetController = class {
         }
       }
     }
-    this.runEvaluationPlan(this.depGraph.getEvaluationPlan(formulaKeys));
+    this.recalculateKeys(formulaKeys, false);
   }
   runEvaluationPlan(plan) {
     for (const key of plan.order) {
@@ -1454,7 +1644,10 @@ var SpreadsheetController = class {
     if (!this.document.cells[row.id]) this.document.cells[row.id] = {};
     const deps = this.depGraph.getDependencies(cellKey);
     const selfReference = deps.includes(cellKey) || deps.includes(`${col.key.toUpperCase()}:`);
-    const errorMessage = selfReference ? "This formula can't reference its own cell." : "This formula is part of a circular reference: it depends on its own result through other cells.";
+    const spilledKeys = this.depGraph.getSpilledKeys(cellKey);
+    const ownSpill = deps.find((dep) => spilledKeys.includes(dep));
+    const errorMessage = selfReference ? "This formula can't reference its own cell." : ownSpill ? `This formula refers to ${ownSpill}, which holds its own spilled results (a circular reference).` : "This formula is part of a circular reference: it depends on its own result through other cells.";
+    this.clearSpill(cellKey.toUpperCase(), true);
     this.document.cells[row.id][col.id] = { ...cell, value: "#CYCLE!", error: "#CYCLE!", errorMessage };
   }
   evalSingleCellByKey(cellKey) {
@@ -1471,25 +1664,176 @@ var SpreadsheetController = class {
         cell.error = void 0;
         cell.errorMessage = void 0;
       }
+      this.clearSpill(`${colName}${rowNum}`);
       return;
     }
     try {
       this.evaluatingRowIndex = rowNum - 1;
+      this.evaluatingCell = { col: colName, row: rowNum };
       const result = this.evaluator.evaluateWithDiagnostics(cell.raw);
       if (!this.document.cells[row.id]) {
         this.document.cells[row.id] = {};
       }
+      let { value, error, message } = result;
+      if (result.array) {
+        const blocked = this.placeSpill(`${colName}${rowNum}`, rowNum - 1, this.document.columns.indexOf(col), result.array);
+        if (blocked) {
+          value = "#SPILL!";
+          error = "#SPILL!";
+          message = blocked;
+        }
+      } else {
+        this.clearSpill(`${colName}${rowNum}`);
+      }
       this.document.cells[row.id][col.id] = {
         ...cell,
-        value: result.value,
+        value,
         // `#ERROR!` (malformed formula, wrong argument count) keeps its
         // message in `error`, as before; other errors store their code.
-        error: result.error === "#ERROR!" ? result.message : result.error,
-        errorMessage: result.message
+        error: error === "#ERROR!" ? message : error,
+        errorMessage: message
       };
     } finally {
       this.evaluatingRowIndex = null;
+      this.evaluatingCell = null;
+    }
+  }
+  // --- Dynamic arrays (spilling) ---
+  /**
+   * Spills `array` from the anchor at (row, col) into the cells below and to
+   * the right. Returns why it can't (the anchor then shows `#SPILL!`), or
+   * null once placed. The grid never grows to fit an array, as in Excel.
+   */
+  placeSpill(anchor, row, col, array) {
+    const { rows, cols } = array;
+    const area = { startRow: row, startCol: col, endRow: row + rows - 1, endCol: col + cols - 1 };
+    const label = `${indexToColName(area.startCol)}${area.startRow + 1}:${indexToColName(area.endCol)}${area.endRow + 1}`;
+    let reason = null;
+    const blockers = [];
+    if (area.endRow >= this.document.rows.length || area.endCol >= this.document.columns.length) {
+      reason = `The ${rows}\xD7${cols} result needs ${label}, which extends past the edge of the sheet.`;
+    } else if (this.getMerges().some((m) => rangesIntersect(m, area))) {
+      reason = `The result can't spill into merged cells (it needs ${label}).`;
+    } else {
+      for (let c = area.startCol; c <= area.endCol; c++) {
+        const column = this.document.columns[c];
+        for (let r = area.startRow; r <= area.endRow; r++) {
+          if (r === row && c === col) continue;
+          const rowObj = this.document.rows[r];
+          const key = `${column.key}${r + 1}`.toUpperCase();
+          const stored = this.document.cells[rowObj.id]?.[column.id];
+          const raw = stored ? stored.raw : this.getDerivedCell(rowObj, column).raw;
+          const owner = this.spilledBy.get(key);
+          if (raw !== "") {
+            blockers.push(key);
+            reason ??= `The result needs ${label}, but ${key} isn't empty.`;
+          } else if (owner && owner !== anchor) {
+            blockers.push(key);
+            reason ??= `The result needs ${label}, but ${key} already holds values spilled from ${owner}.`;
+          }
+        }
+      }
+    }
+    if (reason) {
+      this.clearSpill(anchor);
+      this.depGraph.setSpillEdges(anchor, [], blockers);
+      return reason;
+    }
+    const previous = this.spills.get(anchor);
+    const cells = [];
+    for (let c = 0; c < cols; c++) {
+      const column = this.document.columns[col + c];
+      for (let r = 0; r < rows; r++) {
+        if (r === 0 && c === 0) continue;
+        const rowObj = this.document.rows[row + r];
+        const key = `${column.key}${row + r + 1}`.toUpperCase();
+        const value = array.values[c * rows + r] ?? "";
+        const display = { raw: "", value, format: column.format, spillAnchor: anchor };
+        if (isFormulaError(value)) {
+          display.error = value;
+          display.errorMessage = describeFormulaError(value);
+        }
+        this.spillCells.set(spillCellId(rowObj.id, column.id), display);
+        if (this.spilledBy.get(key) !== anchor) {
+          this.spilledBy.set(key, anchor);
+          this.spillChanges?.add(key);
+        }
+        cells.push({ key, rowId: rowObj.id, colId: column.id });
+      }
+    }
+    if (previous) {
+      const kept = new Set(cells.map((cell) => cell.key));
+      for (const old of previous.cells) {
+        if (kept.has(old.key)) continue;
+        this.forgetSpilledCell(anchor, old);
+      }
+    }
+    this.spills.set(anchor, { anchor, row, col, rows, cols, values: array.values, cells });
+    this.depGraph.setSpillEdges(anchor, cells.map((cell) => cell.key));
+    return null;
+  }
+  /** Removes the array spilled from `anchor`. With `keepEdges`, its dependency edges stay. */
+  clearSpill(anchor, keepEdges = false) {
+    const record = this.spills.get(anchor);
+    if (record) {
+      for (const cell of record.cells) this.forgetSpilledCell(anchor, cell);
+      this.spills.delete(anchor);
+    }
+    if (!keepEdges) this.depGraph.setSpillEdges(anchor, []);
+  }
+  forgetSpilledCell(anchor, cell) {
+    if (this.spilledBy.get(cell.key) !== anchor) return;
+    this.spilledBy.delete(cell.key);
+    this.spillCells.delete(spillCellId(cell.rowId, cell.colId));
+    this.spillChanges?.add(cell.key);
+  }
+  resolveSpillByCoord(colStr, rowNum) {
+    const record = this.spills.get(`${colStr}${rowNum}`.toUpperCase());
+    if (record) return { rows: record.rows, cols: record.cols, values: record.values };
+    const value = this.resolveCellByCoord(colStr, rowNum);
+    return isFormulaError(value) ? value : "#REF!";
+  }
+  toSpill(record) {
+    const row = this.document.rows[record.row];
+    const col = this.document.columns[record.col];
+    return {
+      key: record.anchor,
+      anchor: { row: record.row, col: record.col },
+      range: {
+        startRow: record.row,
+        startCol: record.col,
+        endRow: record.row + record.rows - 1,
+        endCol: record.col + record.cols - 1
+      },
+      formula: row && col ? this.getCell(row.id, col.id).raw : ""
+    };
+  }
+  /**
+   * The dynamic array covering (row, col), whether it is the anchor (the cell
+   * holding the formula) or a spilled cell; null when there is none.
+   */
+  getSpillAt(row, col) {
+    if (this.spills.size === 0) return null;
+    const key = `${indexToColName(col)}${row + 1}`;
+    const record = this.spills.get(key) ?? this.spills.get(this.spilledBy.get(key) ?? "");
+    return record ? this.toSpill(record) : null;
+  }
+  /** Every dynamic array currently spilled. */
+  getSpills() {
+    return Array.from(this.spills.values(), (record) => this.toSpill(record));
+  }
+  /** Whether `range` overlaps a spilled array (its anchor or spilled cells). */
+  intersectsSpill(range) {
+    for (const record of this.spills.values()) {
+      const area = {
+        startRow: record.row,
+        startCol: record.col,
+        endRow: record.row + record.rows - 1,
+        endCol: record.col + record.cols - 1
+      };
+      if (rangesIntersect(area, range)) return true;
     }
+    return false;
   }
   resolveCellByCoord(colStr, rowNum) {
     const col = this.document.columns.find((c) => c.key.toUpperCase() === colStr.toUpperCase());
@@ -1721,7 +2065,7 @@ var SpreadsheetController = class {
     let maxLen = (col.title || "").length + (col.key ? col.key.length + 3 : 0);
     for (const row of this.document.rows) {
       const cell = this.getCell(row.id, col.id);
-      const valStr = cell.value != null ? String(cell.value) : "";
+      const valStr = formatCellDisplay(cell);
       if (valStr.length > maxLen) {
         maxLen = valStr.length;
       }
@@ -1745,8 +2089,7 @@ var SpreadsheetController = class {
     ) : this.document.columns;
     return rows.map(
       (row) => columns.map((col) => {
-        const cell = this.getCell(row.id, col.id);
-        return String(cell.value ?? "").replace(/\t/g, " ");
+        return formatCellDisplay(this.getCell(row.id, col.id)).replace(/\t/g, " ");
       }).join("	")
     ).join("\n");
   }
@@ -1823,7 +2166,7 @@ var SpreadsheetController = class {
    */
   exportToCsv(options = {}) {
     const matrix = this.readMatrix(options.range ?? null).map(
-      (row) => row.map((cell) => options.formulas ? cell.raw : String(cell.value ?? ""))
+      (row) => row.map((cell) => options.formulas ? cell.raw : formatCellDisplay(cell))
     );
     return serializeCsv(matrix, {
       delimiter: options.delimiter,
@@ -1861,7 +2204,16 @@ var SpreadsheetController = class {
    */
   copyToClipboardData(range = this.selectedRange) {
     const r = range ? normalizeRange(range) : { startRow: 0, startCol: 0, endRow: this.document.rows.length - 1, endCol: this.document.columns.length - 1 };
-    const cells = this.readMatrix(r).map((row) => row.map((cell) => ({ raw: cell.raw, value: cell.error || cell.value })));
+    const cells = this.readMatrix(r).map(
+      (row) => row.map((cell) => {
+        const value = cell.error || cell.value;
+        const text = formatCellDisplay(cell);
+        if (cell.spillAnchor && !this.spillAnchorInRange(cell.spillAnchor, r)) {
+          return { raw: text, value, text };
+        }
+        return { raw: cell.raw, value, text };
+      })
+    );
     return createSpreadsheetClipboardData(cells, { row: r.startRow, col: r.startCol });
   }
   /**
@@ -1884,6 +2236,10 @@ var SpreadsheetController = class {
     this.selectRange(r);
     return true;
   }
+  spillAnchorInRange(anchor, range) {
+    const record = this.spills.get(anchor);
+    return !!record && rangeContains(range, record.row, record.col);
+  }
   getSelectionTopLeft() {
     if (this.selectedRange) {
       const r = normalizeRange(this.selectedRange);
@@ -1979,6 +2335,7 @@ var SpreadsheetController = class {
     if (keyCols.length === 0 || keyCols.some((k) => k.index < startCol || k.index > endCol)) return false;
     const area = { startRow, startCol, endRow, endCol };
     if ((this.document.table?.merges ?? []).some((m) => rangesIntersect(m, area))) return false;
+    if (this.intersectsSpill(area)) return false;
     const sourceRows = [];
     for (let r = startRow; r <= endRow; r++) sourceRows.push(r);
     const sorted = sourceRows.map((r) => ({ r, values: keyCols.map((k) => this.getCellValueAt(r, k.index)) })).sort((a, b) => {
@@ -2186,6 +2543,7 @@ var SpreadsheetController = class {
     }
     const merges = this.getMerges();
     if (merges.some((m) => rangesIntersect(m, r) && !rangeContainsRange(r, m))) return false;
+    if (this.intersectsSpill(r)) return false;
     this.applyTableChange(() => {
       for (let row = r.startRow; row <= r.endRow; row++) {
         const rowId = this.document.rows[row].id;
@@ -2207,7 +2565,7 @@ var SpreadsheetController = class {
     if (remaining.length === merges.length) return false;
     this.applyTableChange(() => {
       this.table.merges = remaining;
-    });
+    }, { recalculate: true });
     return true;
   }
   // --- Autofill ---
@@ -2328,6 +2686,7 @@ var SpreadsheetController = class {
     const width = s.endCol - s.startCol + 1;
     const t = { startRow: s.startRow, startCol: s.startCol, endRow: s.startRow + width - 1, endCol: s.startCol + height - 1 };
     if (this.getMerges().some((m) => rangesIntersect(m, s) || rangesIntersect(m, t))) return false;
+    if (this.intersectsSpill(s) || this.intersectsSpill(t)) return false;
     this.applyTableChange(() => {
       this.growGrid(t.endRow, t.endCol);
       this.remapAllFormulas(({ row, col }) => {
@@ -2371,6 +2730,28 @@ var SpreadsheetController = class {
     this.undoStack.push(JSON.stringify(this.document));
     if (this.undoStack.length > 50) this.undoStack.shift();
     this.redoStack = [];
+    this.trimHistory();
+  }
+  /** Drops the oldest snapshots beyond `maxHistoryBytes`, always keeping the newest. */
+  trimHistory() {
+    if (this.maxHistoryBytes <= 0 || this.undoStack.length <= 1) return;
+    let total = 0;
+    for (const s of this.undoStack) total += s.length * 2;
+    for (const s of this.redoStack) total += s.length * 2;
+    while (total > this.maxHistoryBytes && this.undoStack.length > 1) {
+      total -= this.undoStack.shift().length * 2;
+    }
+  }
+  /** Approximate bytes held by the undo/redo snapshots (UTF-16 size). */
+  getHistoryByteSize() {
+    let total = 0;
+    for (const s of this.undoStack) total += s.length * 2;
+    for (const s of this.redoStack) total += s.length * 2;
+    return total;
+  }
+  /** Number of undo / redo snapshots currently held. */
+  getHistoryDepth() {
+    return { undo: this.undoStack.length, redo: this.redoStack.length };
   }
   undo() {
     if (this.undoStack.length === 0) return;
@@ -2412,6 +2793,17 @@ function stepInOrder(order, from, delta) {
 }
 
 // src/spreadsheet/menu.ts
+function clampMenuPosition(point, size, viewport, margin = 4) {
+  const place = (start, length, limit) => {
+    if (start + length <= limit - margin) return Math.max(margin, start);
+    const flipped = start - length;
+    return Math.max(margin, flipped >= margin ? flipped : limit - margin - length);
+  };
+  return {
+    x: place(point.x, size.width, viewport.width),
+    y: place(point.y, size.height, viewport.height)
+  };
+}
 var quote = (value) => {
   const text = String(value ?? "");
   return text.length > 24 ? `"${text.slice(0, 23)}\u2026"` : `"${text}"`;
@@ -2423,7 +2815,8 @@ function getSpreadsheetMenuItems(controller, cell) {
   if (!column || !row) return [];
   const selection = controller.selectedRange && rangeContains(controller.selectedRange, cell.row, cell.col) ? normalizeRange(controller.selectedRange) : { startRow: cell.row, startCol: cell.col, endRow: cell.row, endCol: cell.col };
   const colName = indexToColName(cell.col);
-  const value = controller.getCell(row.id, column.id).value;
+  const cellData = controller.getCell(row.id, column.id);
+  const value = cellData.value;
   const table = doc.table ?? {};
   const filter = controller.getFilterState();
   const grouping = table.grouping;
@@ -2445,7 +2838,7 @@ function getSpreadsheetMenuItems(controller, cell) {
     },
     {
       id: "filter-equals",
-      label: `Show only rows where ${colName} = ${quote(value)}`,
+      label: `Show only rows where ${colName} = ${quote(formatCellDisplay(cellData))}`,
       separatorBefore: true,
       run: () => controller.addFilterRule({ colId: column.id, operator: "equals", value: String(value ?? "") })
     },
@@ -2694,6 +3087,7 @@ export {
   computeRowGroups,
   buildSpreadsheetView,
   SpreadsheetController,
+  clampMenuPosition,
   getSpreadsheetMenuItems,
   SPREADSHEET_TABLE_ACTIONS,
   bindSpreadsheetTableActions,
@@ -2703,4 +3097,4 @@ export {
   registerSpreadsheetImportAdapters,
   importFileIntoSpreadsheet
 };
-//# sourceMappingURL=chunk-GVW4P7BG.js.map
+//# sourceMappingURL=chunk-K3R5NG2D.js.map