@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/workbook.js

@@ -12,12 +12,21 @@
  * disagree with the formula above it.
  */
 import { parseFormula } from './parse.js';
-import { evaluate, rangeValues } from './evaluate.js';
+import { evaluate, rangeValues, tableRectOf } from './evaluate.js';
 import { withCustomFunctions } from './functions.js';
-import { isError } from './ast.js';
-import { createDependencyGraph, precedentsOf, cellKey } from './deps.js';
+import { isError, typedError } from './ast.js';
+import { createDependencyGraph, precedentsOf, isVolatile, cellKey, parseCellKey } from './deps.js';
+import { createTableRegistry, isValidTableName, shiftTables } from './tables.js';
 import { createNames } from './names.js';
-import { fixupReferences, renameSheetReferences } from './refs.js';
+import { fixupReferences, renameSheetReferences, repointReferences } from './refs.js';
+import { builtinEngine } from './engine.js';
+export const DEFAULT_ITERATION = { enabled: false, maxIterations: 100, maxChange: 0.001 };
+/** Excel's text prefix. A cell typed as `'007` holds the text `007`: the
+ *  apostrophe says "what follows is text", and it is not part of the value,
+ *  so it is never displayed, printed, exported or compared. */
+export const TEXT_PREFIX = "'";
+/** The value a typed text stands for once the prefix is taken off. */
+export const withoutTextPrefix = (text) => text.startsWith(TEXT_PREFIX) ? text.slice(1) : text;
 /** A name Excel would accept for a sheet. */
 export function isValidSheetName(name) {
     if (name.trim() === '' || name.length > 31)
@@ -34,17 +43,106 @@ function nextSheetName(taken) {
             return candidate;
     }
 }
+/** Iteration settings with the defaults filled in and the numbers sane. */
+export function cleanIteration(next) {
+    const passes = Math.round(Number(next?.maxIterations ?? DEFAULT_ITERATION.maxIterations));
+    const change = Number(next?.maxChange ?? DEFAULT_ITERATION.maxChange);
+    return {
+        enabled: next?.enabled === true,
+        maxIterations: Number.isFinite(passes) ? Math.min(Math.max(passes, 1), 32767) : DEFAULT_ITERATION.maxIterations,
+        maxChange: Number.isFinite(change) && change >= 0 ? change : DEFAULT_ITERATION.maxChange,
+    };
+}
+/**
+ * How far a cell moved between two passes. Two numbers are their distance;
+ * anything else has moved either not at all or immeasurably, and an
+ * immeasurable move keeps the loop going until the passes run out.
+ */
+function moved(before, after) {
+    if (typeof before === 'number' && typeof after === 'number')
+        return Math.abs(after - before);
+    if (before === undefined)
+        return Infinity;
+    if (isError(before) || isError(after)) {
+        return isError(before) && isError(after) && before.error === after.error ? 0 : Infinity;
+    }
+    return before === after ? 0 : Infinity;
+}
 export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], options = {}) {
     const order = [];
+    /** What the shell is hiding, for SUBTOTAL. Null until it says. */
+    let hiddenRows = null;
+    /** Whether any cell holds a SUBTOTAL, so a filter click can skip the
+     *  recalculation when nothing reads what is hidden. Null when unknown. */
+    let subtotalsHere = null;
     const byName = new Map();
     const graph = createDependencyGraph();
+    /**
+     * The workbook's tables. The parser has always read a structured
+     * reference (`Orders[Amount]`, `[@Qty]`); this is what makes one resolve,
+     * because a reference like that means nothing until something says where
+     * the table is.
+     */
+    const rawTables = createTableRegistry(options.tables);
+    /**
+     * The registry as the workbook hands it out: every change drops the
+     * cached values and settles again.
+     *
+     * A table decides what `Orders[Amount]` means, so defining one, removing
+     * one or growing one changes the answer of every formula that mentions
+     * it. Without this, a table defined after the cells were read leaves each
+     * of those formulas showing the `#REF!` it worked out when there was no
+     * table, which is the first thing anyone hits.
+     */
+    const tables = {
+        get: (name) => rawTables.get(name),
+        list: () => rawTables.list(),
+        at: (sheet, row, col) => rawTables.at(sheet, row, col),
+        define(table) { rawTables.define(table); afterTables(); },
+        remove(name) { const gone = rawTables.remove(name); if (gone)
+            afterTables(); return gone; },
+        growToInclude(sheet, row, col) { const grew = rawTables.growToInclude(sheet, row, col); if (grew)
+            afterTables(); return grew; },
+        clear() { rawTables.clear(); afterTables(); },
+    };
+    /**
+     * `Orders2`, `Orders3`, ...: a table name nothing has taken yet.
+     *
+     * A short name plus a number can read as a cell reference (`T2`), which
+     * Excel refuses as a table name and so does the registry, so those fall
+     * back to Excel's own `Table2`.
+     */
+    function freeTableName(base) {
+        const taken = new Set(rawTables.list().map((t) => t.name.toLowerCase()));
+        const root = base.replace(/\d+$/, '') || 'Table';
+        for (let i = 2;; i += 1) {
+            for (const candidate of [`${root}${i}`, `Table${i}`]) {
+                if (!taken.has(candidate.toLowerCase()) && isValidTableName(candidate))
+                    return candidate;
+            }
+        }
+    }
+    function afterTables() {
+        dropAll();
+        loadEngine();
+        settleAll();
+    }
     const functions = withCustomFunctions(options.functions);
+    const engine = options.engine ?? builtinEngine();
     /** Computed values, keyed the same way the graph is. Rebuilt lazily and
      *  invalidated by every write, so it can never hold a value whose formula
      *  has since changed. */
     const values = new Map();
     /** Cells currently being resolved, for cycle detection. */
     const visiting = new Set();
+    /** Iterative calculation, and the value each cell had on the pass before:
+     *  what a cell in a cycle reads for itself while iteration is on, and what
+     *  the convergence test measures against. */
+    let iteration = cleanIteration(options.iteration);
+    const previous = new Map();
+    /** Cells whose formula is volatile (INDIRECT, OFFSET, RAND, NOW ...):
+     *  recomputed on every write, since the graph cannot see what they read. */
+    const volatile = new Set();
     /** Parsed formulas, keyed by their TEXT rather than their position: a
      *  column of =A1*2 filled down is one parse, not one per row. */
     const astCache = new Map();
@@ -52,9 +150,23 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
     // the dependency graph only knows the CELLS a name pointed at when the
     // formula was last evaluated. Dropping the cache is the honest answer:
     // names change rarely, and a full recompute costs less than one stale total.
+    /**
+     * Dynamic arrays. A formula whose answer is a grid spills it over the
+     * cells below and to the right: `spills` keeps each anchor's rectangle,
+     * `spilledBy` points every covered cell back at its anchor, and a covered
+     * cell reads its value from the anchor's grid while its own text stays
+     * blank, as in Excel. An anchor whose rectangle runs into a cell that
+     * holds text, or into another spill, shows #SPILL! and sits in `blocked`
+     * until a write frees the way.
+     */
+    const spills = new Map();
+    const spilledBy = new Map();
+    const blocked = new Set();
+    /** Cells whose value a spill just changed under them, to compute once the write settles. */
+    const pending = new Set();
     const names = (() => {
         const inner = createNames();
-        const drop = () => { values.clear(); graph.clear(); };
+        const drop = () => { dropAll(); settleAll(); };
         return {
             ...inner,
             define: (name, refersTo) => { inner.define(name, refersTo); drop(); },
@@ -72,6 +184,16 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
     function resolveSheetName(sheet, self) {
         return sheet ?? self;
     }
+    /** The sheets from `from` to `to` in tab order, inclusive, for a 3D
+     *  reference; null when either name is not a sheet. */
+    function sheetsInRange(from, to) {
+        const lower = order.map((n) => n.toLowerCase());
+        const i = lower.indexOf(from.toLowerCase());
+        const j = lower.indexOf(to.toLowerCase());
+        if (i < 0 || j < 0)
+            return null;
+        return i <= j ? order.slice(i, j + 1) : order.slice(j, i + 1);
+    }
     function parseCached(text) {
         if (astCache.has(text))
             return astCache.get(text) ?? null;
@@ -85,8 +207,9 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
         astCache.set(text, ast);
         return ast;
     }
-    function contextFor(self, override) {
+    function contextFor(self, override, at) {
         return {
+            currentCell: at ? { sheet: self, row: at.row, col: at.col } : undefined,
             resolve: (sheet, row, col) => {
                 const name = resolveSheetName(sheet, self);
                 // A validation rule reads the cell it is checking as the text being
@@ -96,10 +219,273 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                 return compute(name, row, col);
             },
             lastRow: (sheet) => Math.max(rowCount(resolveSheetName(sheet, self)) - 1, 0),
+            spillRect: (sheet, row, col) => {
+                // The array anchored here, computed first so a formula that reads
+                // `A1#` sees the spill even on the pass that establishes it. Only an
+                // anchor has an entry; a covered cell or a plain value gives null,
+                // which the operator reads as #REF!.
+                const name = resolveSheetName(sheet, self);
+                compute(name, row, col);
+                const rect = spills.get(cellKey(name, row, col));
+                return rect ? [rect.r1, rect.c1, rect.r2, rect.c2] : null;
+            },
+            sheetsBetween: (from, to) => sheetsInRange(from, to),
             resolveNameNode: (name) => names.resolve(name),
+            findTable: (name) => rawTables.get(name),
+            tableAt: (sheet, row, col) => rawTables.at(resolveSheetName(sheet, self), row, col),
+            hiddenRow: hiddenRows ? (sheet, row) => hiddenRows(resolveSheetName(sheet, self), row) : undefined,
+            isSubtotal: (sheet, row, col) => {
+                const text = sheetCells(resolveSheetName(sheet, self))?.[row]?.[col] ?? '';
+                return /^\s*=\s*SUBTOTAL\s*\(/i.test(text);
+            },
             functions,
         };
     }
+    /** The engine's copy of the cells, for an engine that keeps one. */
+    function loadEngine() {
+        engine.load?.(order.map((name) => ({ name, cells: sheetCells(name).map((r) => [...r]) })));
+    }
+    /** Forget every derived thing: values, edges, volatility, spills. */
+    function dropAll() {
+        // Cells may have been replaced wholesale, so the SUBTOTAL flag is stale.
+        subtotalsHere = null;
+        values.clear();
+        previous.clear();
+        graph.clear();
+        volatile.clear();
+        spills.clear();
+        spilledBy.clear();
+        blocked.clear();
+        pending.clear();
+    }
+    const SUBTOTAL_TEXT = /^\s*=[\s\S]*SUBTOTAL\s*\(/i;
+    /** Whether any cell in the workbook holds a SUBTOTAL. Worked out once and
+     *  forgotten again whenever a write could change the answer. */
+    function hasSubtotal() {
+        if (subtotalsHere !== null)
+            return subtotalsHere;
+        let found = false;
+        for (const sheet of order) {
+            const cells = sheetCells(sheet);
+            for (const line of cells) {
+                for (const text of line) {
+                    if (text && SUBTOTAL_TEXT.test(text)) {
+                        found = true;
+                        break;
+                    }
+                }
+                if (found)
+                    break;
+            }
+            if (found)
+                break;
+        }
+        subtotalsHere = found;
+        return found;
+    }
+    /** Whether a key holds a formula, for the settling passes. */
+    function isFormulaKey(key) {
+        const at = parseCellKey(key);
+        return (sheetCells(at.sheet ?? '')?.[at.row]?.[at.col] ?? '').trim().startsWith('=');
+    }
+    /**
+     * Compute every formula in the workbook, so every spill is on record
+     * before any cell it covers is read. Lazy evaluation alone would leave a
+     * covered cell blank when it is read before its anchor, which a repaint
+     * from the top of a scrolled sheet does.
+     */
+    function settleAll() {
+        for (const other of order) {
+            const cells = sheetCells(other) ?? [];
+            for (let r = 0; r < cells.length; r += 1) {
+                const line = cells[r];
+                for (let c = 0; c < line.length; c += 1)
+                    if (line[c].trim().startsWith('='))
+                        compute(other, r, c);
+            }
+        }
+        settlePending();
+        runIterations();
+    }
+    /**
+     * Run the cycles until they stop moving.
+     *
+     * Everything in a cycle, and everything downstream of one, is recomputed
+     * from the values it last had; a pass that moves no cell by more than
+     * `maxChange` is the last one, and so is pass number `maxIterations`. This
+     * is Excel's model exactly: it does not promise convergence, it promises a
+     * bounded number of tries and whatever they reached.
+     */
+    function runIterations() {
+        if (!iteration.enabled)
+            return [];
+        const seeds = graph.cycles();
+        if (seeds.length === 0)
+            return [];
+        // Cycle members are downstream of each other, so `dirtyFrom` already
+        // includes them; the union is for a seed whose readers were never
+        // evaluated.
+        const affected = [...new Set([...seeds, ...graph.dirtyFrom(seeds)])];
+        for (let pass = 0; pass < Math.max(1, iteration.maxIterations); pass += 1) {
+            const before = new Map();
+            for (const key of affected) {
+                before.set(key, values.get(key) ?? previous.get(key));
+                values.delete(key);
+            }
+            let worst = 0;
+            for (const key of affected) {
+                const at = parseCellKey(key);
+                const after = compute(at.sheet ?? '', at.row, at.col);
+                worst = Math.max(worst, moved(before.get(key), after));
+            }
+            if (worst <= iteration.maxChange)
+                break;
+        }
+        return affected;
+    }
+    /** Compute what a spill changed under other formulas, until nothing is left. */
+    function settlePending() {
+        const done = [];
+        while (pending.size) {
+            const batch = [...pending];
+            pending.clear();
+            for (const key of batch) {
+                const at = parseCellKey(key);
+                compute(at.sheet ?? '', at.row, at.col);
+                done.push(key);
+            }
+        }
+        return done;
+    }
+    /** Drop an anchor's spill; the covered cells' values and edges go with it. */
+    function clearSpill(anchor) {
+        const rect = spills.get(anchor);
+        if (!rect)
+            return [];
+        spills.delete(anchor);
+        const at = parseCellKey(anchor);
+        const covered = [];
+        for (let r = rect.r1; r <= rect.r2; r += 1) {
+            for (let c = rect.c1; c <= rect.c2; c += 1) {
+                if (r === at.row && c === at.col)
+                    continue;
+                const key = cellKey(at.sheet, r, c);
+                if (spilledBy.get(key) !== anchor)
+                    continue;
+                spilledBy.delete(key);
+                values.delete(key);
+                graph.setPrecedents(key, null);
+                covered.push(key);
+            }
+        }
+        return covered;
+    }
+    /**
+     * Record an anchor's grid over its rectangle, or refuse it. Returns the
+     * anchor's own value: the grid's top-left cell, or #SPILL! when a cell
+     * in the way holds text or belongs to another spill.
+     */
+    function recordSpill(anchor, sheet, row, col, grid) {
+        const cells = sheetCells(sheet);
+        const rect = { r1: row, c1: col, r2: row + grid.length - 1, c2: col + (grid[0]?.length ?? 1) - 1 };
+        for (let r = rect.r1; r <= rect.r2; r += 1) {
+            for (let c = rect.c1; c <= rect.c2; c += 1) {
+                if (r === row && c === col)
+                    continue;
+                const key = cellKey(sheet, r, c);
+                const owner = spilledBy.get(key);
+                if ((cells[r]?.[c] ?? '').trim() !== '' || (owner !== undefined && owner !== anchor)) {
+                    for (const k of clearSpill(anchor))
+                        pending.add(k);
+                    blocked.add(anchor);
+                    return { error: '#SPILL!' };
+                }
+            }
+        }
+        blocked.delete(anchor);
+        const before = spills.get(anchor);
+        const stillCovered = new Set();
+        for (let r = rect.r1; r <= rect.r2; r += 1) {
+            for (let c = rect.c1; c <= rect.c2; c += 1) {
+                if (r === row && c === col)
+                    continue;
+                const key = cellKey(sheet, r, c);
+                stillCovered.add(key);
+                const fresh = spilledBy.get(key) !== anchor;
+                spilledBy.set(key, anchor);
+                values.set(key, grid[r - row]?.[c - col] ?? '');
+                graph.setPrecedents(key, [anchor]);
+                // Reported as changed, and a formula that read this cell while it
+                // was blank has a stale value.
+                pending.add(key);
+                if (fresh)
+                    for (const k of graph.dirtyFrom([key]))
+                        if (k !== key) {
+                            values.delete(k);
+                            pending.add(k);
+                        }
+            }
+        }
+        // The cells the old rectangle covered and the new one does not read blank again.
+        if (before) {
+            for (let r = before.r1; r <= before.r2; r += 1) {
+                for (let c = before.c1; c <= before.c2; c += 1) {
+                    const key = cellKey(sheet, r, c);
+                    if (stillCovered.has(key) || spilledBy.get(key) !== anchor)
+                        continue;
+                    spilledBy.delete(key);
+                    values.delete(key);
+                    graph.setPrecedents(key, null);
+                    pending.add(key);
+                    for (const k of graph.dirtyFrom([key]))
+                        if (k !== key) {
+                            values.delete(k);
+                            pending.add(k);
+                        }
+                }
+            }
+        }
+        spills.set(anchor, rect);
+        return grid[0]?.[0] ?? '';
+    }
+    /**
+     * How deep a cell's value may be resolved by recursion before the chain is
+     * primed from the far end instead. A running-balance column is a chain as
+     * long as the sheet, and evaluating the last cell of one by recursion
+     * overflows the JavaScript stack somewhere past a thousand rows, which the
+     * evaluator turns into a `#NUM!`. Priming keeps the depth flat, so the
+     * only limit left is the sheet's own size.
+     */
+    const DEEP = 150;
+    let depth = 0;
+    /**
+     * Compute what a cell reads, furthest first, so the cell itself resolves
+     * against cached values rather than by recursing through the chain. The
+     * precedents are the ones the graph recorded at the last evaluation, which
+     * is exactly the chain a re-evaluation is about to walk again.
+     */
+    function primeChain(from) {
+        const seen = new Set([from]);
+        const chain = [from];
+        const stack = [from];
+        while (stack.length) {
+            const cur = stack.pop();
+            for (const p of graph.precedentsOf(cur)) {
+                if (seen.has(p) || values.get(p) !== undefined)
+                    continue;
+                seen.add(p);
+                chain.push(p);
+                stack.push(p);
+            }
+        }
+        for (let i = chain.length - 1; i >= 1; i -= 1) {
+            const key = chain[i];
+            if (values.get(key) !== undefined)
+                continue;
+            const at = parseCellKey(key);
+            compute(at.sheet ?? '', at.row, at.col);
+        }
+    }
     function compute(sheet, row, col) {
         const cells = sheetCells(sheet);
         if (!cells)
@@ -114,39 +500,123 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
         // #REF! is reserved for the two cases that really are broken: a sheet
         // that does not exist, and a negative index, which is what a reference
         // shifted off the top by a delete becomes.
-        if (row >= cells.length || col >= (cells[row]?.length ?? 0))
-            return '';
         const key = cellKey(sheet, row, col);
         const cached = values.get(key);
         if (cached !== undefined)
             return cached;
-        if (visiting.has(key))
-            return { error: '#CYCLE!' };
+        if (row >= cells.length || col >= (cells[row]?.length ?? 0)) {
+            // Past the written area, unless a spill reaches here.
+            const anchor = spilledBy.get(key);
+            if (anchor === undefined)
+                return '';
+            const at = parseCellKey(anchor);
+            compute(at.sheet ?? sheet, at.row, at.col);
+            return values.get(key) ?? '';
+        }
+        if (visiting.has(key)) {
+            // The cell is being asked for itself. Without iteration that is the
+            // error; with it, the loop is meant, and the answer is what this cell
+            // was worth on the last pass, starting from 0 as Excel does.
+            if (!iteration.enabled)
+                return { error: '#CYCLE!' };
+            return previous.get(key) ?? 0;
+        }
+        // Deep enough that recursion is a risk: resolve what this cell reads from
+        // the far end first, and come back to it with everything cached.
+        if (depth >= DEEP)
+            primeChain(key);
         visiting.add(key);
+        depth += 1;
         const text = (cells[row]?.[col] ?? '').trim();
         let value;
         if (text === '') {
+            // A blank cell shows what an array formula spills into it.
+            const anchor = spilledBy.get(key);
+            if (anchor !== undefined) {
+                const at = parseCellKey(anchor);
+                compute(at.sheet ?? sheet, at.row, at.col);
+                const spilled = values.get(key);
+                if (spilled !== undefined) {
+                    visiting.delete(key);
+                    depth -= 1;
+                    return spilled;
+                }
+            }
             value = '';
         }
         else if (text.startsWith('=')) {
             const ast = parseCached(text);
-            if (!ast)
-                value = { error: '#PARSE!' };
+            // The graph, the volatile set and the spill ranges are read off the
+            // reference grammar, which is Excel's whatever evaluates it, so they
+            // stay right for any engine. Only the value and the grid are asked for.
+            const result = engine.evaluate(text, { sheet, row, col }, {
+                context: contextFor(sheet, undefined, { row, col }),
+                parse: parseCached,
+            });
+            value = result.value;
+            const grid = isError(value) ? null : result.spill ?? null;
+            if (grid)
+                value = recordSpill(key, sheet, row, col, grid);
+            else if (spills.has(key))
+                for (const k of clearSpill(key))
+                    pending.add(k);
+            if (ast) {
+                if (isVolatile(ast))
+                    volatile.add(key);
+                else
+                    volatile.delete(key);
+                graph.setPrecedents(key, precedentsOf(ast, { sheet }, (s) => Math.max(rowCount(s ?? sheet) - 1, 0), (name) => names.resolve(name), 
+                // A structured reference's cells, so a total over a table is
+                // recalculated when a cell inside the table is typed. Best effort:
+                // a reference that cannot be resolved records no precedents rather
+                // than taking the cell's value down with it, since the value has
+                // already been worked out by the time this runs.
+                (node) => {
+                    try {
+                        return tableRectOf(node, contextFor(sheet, undefined, { row, col }));
+                    }
+                    catch {
+                        return null;
+                    }
+                }, 
+                // The cells a spilled-range operator covers right now. The anchor
+                // has just been computed by this same pass, so its rectangle is on
+                // record; reading it here (rather than recomputing) keeps the
+                // dependency extraction free of side effects.
+                (node) => {
+                    const name = resolveSheetName(node.ref.sheet, sheet);
+                    const rect = spills.get(cellKey(name, node.ref.row ?? 0, node.ref.col));
+                    return rect ? { sheet: name, r1: rect.r1, c1: rect.c1, r2: rect.r2, c2: rect.c2 } : null;
+                }, 
+                // The sheets a 3D reference spans, so it recalculates when the cell
+                // on any of them is typed into.
+                (from, to) => sheetsInRange(from, to)));
+            }
             else {
-                value = evaluate(ast, contextFor(sheet));
-                graph.setPrecedents(key, precedentsOf(ast, { sheet }, (s) => Math.max(rowCount(s ?? sheet) - 1, 0), (name) => names.resolve(name)));
+                graph.setPrecedents(key, null);
+                volatile.delete(key);
             }
         }
+        else if (text.startsWith(TEXT_PREFIX)) {
+            // Excel's apostrophe: what follows is text, whatever it looks like,
+            // and the apostrophe itself is not part of it. It is the only way to
+            // keep a leading zero, a part number that reads as a date, or the
+            // text of a formula in a cell.
+            value = text.slice(1);
+        }
         else {
             const n = Number(text);
             const upper = text.toUpperCase();
             value = text !== '' && Number.isFinite(n) ? n
                 : upper === 'TRUE' ? true
                     : upper === 'FALSE' ? false
-                        : text;
+                        : typedError(text) ?? text;
         }
         visiting.delete(key);
+        depth -= 1;
         values.set(key, value);
+        if (iteration.enabled)
+            previous.set(key, value);
         return value;
     }
     /** What typed text is worth when it is not a formula: a number, a boolean or itself. */
@@ -154,11 +624,16 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
         const t = text.trim();
         if (t === '')
             return '';
+        if (t.startsWith(TEXT_PREFIX))
+            return t.slice(1);
         if (t.startsWith('='))
             return t;
         const n = Number(t);
         const upper = t.toUpperCase();
-        return Number.isFinite(n) ? n : upper === 'TRUE' ? true : upper === 'FALSE' ? false : t;
+        return Number.isFinite(n) ? n
+            : upper === 'TRUE' ? true
+                : upper === 'FALSE' ? false
+                    : typedError(t) ?? t;
     }
     function rowCount(sheet) {
         return sheetCells(sheet)?.length ?? 0;
@@ -169,17 +644,29 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
             return 0;
         return cells.reduce((max, row) => Math.max(max, row.length), 0);
     }
-    /** Drop cached values for a cell and everything downstream of it. */
+    /** Drop cached values for a cell and everything downstream of it, and
+     *  for every volatile cell and its readers, which any write may affect. */
     function invalidate(keys) {
         const touched = [...keys];
         for (const key of keys)
             values.delete(key);
-        for (const key of graph.dirtyFrom(keys)) {
+        for (const key of volatile) {
+            if (values.delete(key))
+                touched.push(key);
+        }
+        for (const key of graph.dirtyFrom([...keys, ...volatile])) {
             values.delete(key);
             touched.push(key);
         }
         return touched;
     }
+    /** Every listener on raw writes, plus the option that is one of them. */
+    const writeListeners = new Set();
+    function emitWrite(change) {
+        options.onWrite?.(change);
+        for (const listener of writeListeners)
+            listener(change);
+    }
     function reportRecalc(keys) {
         const cb = options.onRecalc;
         if (!cb || keys.length === 0)
@@ -197,6 +684,7 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
         get sheets() { return [...order]; },
         get active() { return active; },
         get names() { return names; },
+        get tables() { return tables; },
         setActive(name) {
             if (sheetCells(name))
                 active = order.find((n) => n.toLowerCase() === name.toLowerCase()) ?? active;
@@ -212,6 +700,7 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
             const index = at === undefined ? order.length : Math.max(0, Math.min(at, order.length));
             order.splice(index, 0, chosen);
             active = chosen;
+            loadEngine();
             return chosen;
         },
         removeSheet(name) {
@@ -222,12 +711,19 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                 return false;
             const [removed] = order.splice(index, 1);
             byName.delete(removed.toLowerCase());
+            // The tables that lived on it go with it: a table on a sheet that is
+            // gone resolves to cells that are gone.
+            for (const table of rawTables.list()) {
+                if (table.sheet.toLowerCase() === removed.toLowerCase())
+                    rawTables.remove(table.name);
+            }
             // Every cached value may have read the sheet that just went.
-            values.clear();
-            graph.clear();
+            dropAll();
+            loadEngine();
             if (active.toLowerCase() === removed.toLowerCase()) {
                 active = order[Math.min(index, order.length - 1)] ?? order[0];
             }
+            settleAll();
             return true;
         },
         renameSheet(from, to) {
@@ -260,8 +756,16 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                 if (typeof next === 'string' && next !== entry.refersTo)
                     names.define(entry.name, next);
             }
-            values.clear();
-            graph.clear();
+            // A table names the sheet it sits on, and a structured reference
+            // resolves through that name. Leaving it behind turned every
+            // `=SUM(Orders[Amount])` into #REF! the moment the sheet was renamed.
+            for (const table of rawTables.list()) {
+                if (table.sheet.toLowerCase() === from.toLowerCase())
+                    rawTables.define({ ...table, sheet: to });
+            }
+            dropAll();
+            loadEngine();
+            settleAll();
             return true;
         },
         moveSheet(name, to) {
@@ -272,6 +776,46 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
             order.splice(Math.max(0, Math.min(to, order.length)), 0, moved);
             return true;
         },
+        copySheet(from, to) {
+            const index = order.findIndex((n) => n.toLowerCase() === from.toLowerCase());
+            const source = sheetCells(from);
+            if (index < 0 || !source)
+                return null;
+            let name = to;
+            if (name === undefined) {
+                const base = order[index];
+                for (let i = 2;; i += 1) {
+                    const candidate = `${base} (${i})`;
+                    if (!sheetCells(candidate) && isValidSheetName(candidate)) {
+                        name = candidate;
+                        break;
+                    }
+                    if (i > 1000)
+                        return null;
+                }
+            }
+            if (!isValidSheetName(name) || sheetCells(name))
+                return null;
+            byName.set(name.toLowerCase(), source.map((line) => [...line]));
+            order.splice(index + 1, 0, name);
+            active = name;
+            // A table belongs to its sheet, so the copy gets one of its own, as
+            // Excel's Move or Copy does. Without it the copied cells keep their
+            // `[@Qty]` formulas with no table to resolve them, and every one of
+            // them reads #REF!.
+            for (const table of rawTables.list()) {
+                if (table.sheet.toLowerCase() !== from.toLowerCase())
+                    continue;
+                rawTables.define({ ...table, sheet: name, name: freeTableName(table.name) });
+            }
+            // Nothing cached read the new sheet yet, but a formula elsewhere
+            // that reads a whole column of it by name cannot exist either, so
+            // only the graph needs the new cells' precedents, which compute
+            // records on first read. An engine with a copy of the cells does
+            // need the new sheet.
+            loadEngine();
+            return name;
+        },
         getRaw(sheet, row, col) {
             return sheetCells(sheet)?.[row]?.[col] ?? '';
         },
@@ -286,17 +830,41 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                 line.push('');
             if (line[col] === text)
                 return;
+            if (SUBTOTAL_TEXT.test(text) || SUBTOTAL_TEXT.test(line[col] ?? ''))
+                subtotalsHere = null;
             line[col] = text;
+            engine.write?.(sheet, row, col, text);
+            emitWrite({ sheet: order.find((n) => n.toLowerCase() === sheet.toLowerCase()) ?? sheet, row, col, text });
             const key = cellKey(sheet, row, col);
-            // A cell that is no longer a formula reads nothing.
-            if (!text.trim().startsWith('='))
+            const keys = [key];
+            // A cell that is no longer a formula reads nothing, and spills nothing.
+            if (!text.trim().startsWith('=')) {
                 graph.setPrecedents(key, null);
-            reportRecalc(invalidate([key]));
+                volatile.delete(key);
+            }
+            if (spills.has(key))
+                keys.push(...clearSpill(key));
+            // Text landing in a spilled cell blocks its anchor; a cell going
+            // blank may free one that was blocked.
+            const anchor = spilledBy.get(key);
+            if (anchor !== undefined)
+                keys.push(anchor);
+            keys.push(...blocked);
+            const touched = invalidate(keys);
+            // The written cell and the anchors it touched compute now, so a new
+            // or changed spill is on record before anything reads under it;
+            // plain dependents wait for their next read, as before.
+            for (const k of keys)
+                if (isFormulaKey(k)) {
+                    const at = parseCellKey(k);
+                    compute(at.sheet ?? sheet, at.row, at.col);
+                }
+            reportRecalc([...new Set([...touched, ...settlePending(), ...runIterations()])]);
         },
         getValue(sheet, row, col) {
             return compute(sheet, row, col);
         },
-        evaluateText(sheet, text, override) {
+        evaluateText(sheet, text, override, at) {
             const t = text.trim();
             if (t === '')
                 return '';
@@ -304,7 +872,9 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                 if (!sheetCells(sheet))
                     return { error: '#REF!' };
                 const ast = parseCached(t);
-                return ast ? evaluate(ast, contextFor(sheet, override)) : { error: '#PARSE!' };
+                // The cell the text is read for, so ROW() and COLUMN() and a
+                // [@Column] reference mean something in a rule's formula.
+                return ast ? evaluate(ast, contextFor(sheet, override, at ?? (override ? { row: override.row, col: override.col } : undefined))) : { error: '#PARSE!' };
             }
             return literal(t);
         },
@@ -327,10 +897,55 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
             }
             return out;
         },
+        repointAfterMove(move) {
+            if (!sheetCells(move.sheet) || !sheetCells(move.toSheet))
+                return;
+            if (move.dRow === 0 && move.dCol === 0 && move.sheet === move.toSheet)
+                return;
+            let touched = false;
+            // The whole workbook: another sheet's =Orders!A5 names a moved cell
+            // just as a local reference does.
+            for (const other of order) {
+                const cells = sheetCells(other);
+                for (let r = 0; r < cells.length; r += 1) {
+                    const line = cells[r];
+                    for (let c = 0; c < line.length; c += 1) {
+                        const text = line[c] ?? '';
+                        if (!text.startsWith('='))
+                            continue;
+                        const next = repointReferences(text, move, other);
+                        if (typeof next === 'string' && next !== text) {
+                            line[c] = next;
+                            touched = true;
+                        }
+                    }
+                }
+            }
+            // A name has no home sheet, so only a qualified reference can match.
+            for (const entry of names.list()) {
+                const next = repointReferences(entry.refersTo, move, null);
+                if (typeof next === 'string' && next !== entry.refersTo) {
+                    names.define(entry.name, next);
+                    touched = true;
+                }
+            }
+            if (!touched)
+                return;
+            dropAll();
+            astCache.clear();
+            loadEngine();
+            settleAll();
+        },
         applyStructuralEdit(sheet, edit) {
             const target = sheetCells(sheet);
             if (!target || edit.count <= 0)
                 return;
+            // The tables move with their cells, so a structured reference keeps
+            // meaning the same column after a row is inserted above the table.
+            const moved = shiftTables(rawTables.list(), sheet, edit);
+            rawTables.clear();
+            for (const table of moved)
+                rawTables.define(table);
             // Rewrite every formula in the WORKBOOK, not just this sheet: another
             // sheet may hold =Orders!A5, and inserting a row in Orders has to move
             // it exactly as if it were local.
@@ -381,21 +996,115 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
                         line.splice(edit.at, edit.count);
                 }
             }
-            values.clear();
-            graph.clear();
+            dropAll();
             astCache.clear();
+            loadEngine();
+            settleAll();
+        },
+        precedents(sheet, row, col) {
+            const name = order.find((n) => n.toLowerCase() === sheet.toLowerCase());
+            if (!name)
+                return [];
+            // Computing the cell records what it reads.
+            compute(name, row, col);
+            return graph.precedentsOf(cellKey(name, row, col)).map((key) => {
+                const at = parseCellKey(key);
+                return { sheet: at.sheet ?? name, row: at.row, col: at.col };
+            });
+        },
+        dependents(sheet, row, col) {
+            const name = order.find((n) => n.toLowerCase() === sheet.toLowerCase());
+            if (!name)
+                return [];
+            // A formula that was never evaluated has no edge yet: evaluate every
+            // formula once so the graph is whole.
+            for (const other of order) {
+                const cells = sheetCells(other) ?? [];
+                for (let r = 0; r < cells.length; r += 1) {
+                    const line = cells[r];
+                    for (let c = 0; c < line.length; c += 1)
+                        if (line[c].trim().startsWith('='))
+                            compute(other, r, c);
+                }
+            }
+            return graph.dependentsOf(cellKey(name, row, col)).map((key) => {
+                const at = parseCellKey(key);
+                return { sheet: at.sheet ?? name, row: at.row, col: at.col };
+            });
+        },
+        subscribeWrites(listener) {
+            writeListeners.add(listener);
+            return () => { writeListeners.delete(listener); };
+        },
+        setHiddenRows(source) {
+            hiddenRows = source;
+            // Only SUBTOTAL reads what is hidden, and nothing in the dependency
+            // graph can see that it changed - so everything is recomputed, but
+            // only when there is a SUBTOTAL to recompute.
+            if (!hasSubtotal())
+                return;
+            dropAll();
+            settleAll();
         },
         recalculate() {
-            values.clear();
-            graph.clear();
+            dropAll();
+            loadEngine();
+            settleAll();
+        },
+        get iteration() { return { ...iteration }; },
+        setIteration(next) {
+            const wanted = cleanIteration({ ...iteration, ...next });
+            if (wanted.enabled === iteration.enabled && wanted.maxIterations === iteration.maxIterations && wanted.maxChange === iteration.maxChange)
+                return;
+            iteration = wanted;
+            // Turning it on turns #CYCLE! into a number, and turning it off turns
+            // the number back into #CYCLE!, so every cached value is suspect.
+            dropAll();
+            settleAll();
+        },
+        spillOf(sheet, row, col) {
+            const name = order.find((n) => n.toLowerCase() === sheet.toLowerCase());
+            if (!name)
+                return null;
+            compute(name, row, col);
+            const key = cellKey(name, row, col);
+            const anchor = spills.has(key) ? key : spilledBy.get(key);
+            if (anchor === undefined)
+                return null;
+            const rect = spills.get(anchor);
+            if (!rect)
+                return null;
+            const at = parseCellKey(anchor);
+            return { anchor: { row: at.row, col: at.col }, rect: [rect.r1, rect.c1, rect.r2, rect.c2] };
+        },
+        spills(sheet) {
+            const name = order.find((n) => n.toLowerCase() === sheet.toLowerCase());
+            if (!name)
+                return [];
+            settleAll();
+            const out = [];
+            for (const [anchor, rect] of spills) {
+                const at = parseCellKey(anchor);
+                if ((at.sheet ?? '').toLowerCase() !== name.toLowerCase())
+                    continue;
+                out.push({ row: at.row, col: at.col, rect: [rect.r1, rect.c1, rect.r2, rect.c2] });
+            }
+            return out.sort((a, b) => a.row - b.row || a.col - b.col);
         },
         rowCount,
         colCount,
         serialize() {
+            const list = rawTables.list();
             return {
                 sheets: order.map((name) => ({ name, cells: sheetCells(name).map((r) => [...r]) })),
                 active,
                 names: names.serialize(),
+                // Absent rather than empty in a workbook with no tables, so a saved
+                // document from before they existed reads the same either way.
+                ...(list.length ? { tables: list.map((t) => ({ ...t })) } : {}),
+                // Written only when it is on, so a document saved by a workbook that
+                // never heard of iteration reads back identically.
+                ...(iteration.enabled ? { iteration: { ...iteration } } : {}),
             };
         },
     };
@@ -404,6 +1113,8 @@ export function createWorkbook(initial = [{ name: 'Sheet1', cells: [] }], option
         order.push(sheet.name);
     }
     active = order[0] ?? '';
+    loadEngine();
+    settleAll();
     return workbook;
 }
 export { isError };