@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/workbook.js

@@ -0,0 +1,1120 @@
+/**
+ * The workbook: several named sheets that can read each other.
+ *
+ * The engine already parsed `Orders!A1` and `'Price list'!A1:C9` from the day
+ * it was promoted, because demo 119 had them. What was missing is the thing
+ * those references point AT. This is that model, plus the recalculation that
+ * has to span sheets once they can.
+ *
+ * Cells hold raw text and nothing else. Everything derived - the computed
+ * value, the dependency edges, the display string - is recomputed from it, so
+ * there is exactly one copy of the truth and no way for a cached value to
+ * disagree with the formula above it.
+ */
+import { parseFormula } from './parse.js';
+import { evaluate, rangeValues, tableRectOf } from './evaluate.js';
+import { withCustomFunctions } from './functions.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, 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)
+        return false;
+    // Excel forbids these because they are the reference grammar.
+    return !/[:\\/?*[\]]/.test(name);
+}
+/** `Sheet1`, `Sheet2`, ... skipping any that already exist. */
+function nextSheetName(taken) {
+    const used = new Set(taken.map((n) => n.toLowerCase()));
+    for (let i = 1;; i += 1) {
+        const candidate = `Sheet${i}`;
+        if (!used.has(candidate.toLowerCase()))
+            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();
+    // Changing what a name refers to changes every formula that uses it, and
+    // 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 = () => { dropAll(); settleAll(); };
+        return {
+            ...inner,
+            define: (name, refersTo) => { inner.define(name, refersTo); drop(); },
+            remove: (name) => { inner.remove(name); drop(); },
+            hydrate: (entries) => { inner.hydrate(entries); drop(); },
+            clear: () => { inner.clear(); drop(); },
+        };
+    })();
+    let active = '';
+    function sheetCells(name) {
+        return byName.get(name.toLowerCase());
+    }
+    /** Resolve a sheet reference. A null sheet means the one being evaluated,
+     *  which the resolver tracks as it descends. */
+    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;
+        let ast;
+        try {
+            ast = parseFormula(text);
+        }
+        catch {
+            ast = null;
+        }
+        astCache.set(text, ast);
+        return ast;
+    }
+    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
+                // entered, which is not in the sheet yet; nothing else is overridden.
+                if (override && name === self && row === override.row && col === override.col)
+                    return literal(override.text);
+                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)
+            return { error: '#REF!' };
+        if (row < 0 || col < 0)
+            return { error: '#REF!' };
+        // Anything past the written area is BLANK. A sheet has no size in this
+        // model beyond what has been typed into it, so there is no edge to fall
+        // off: =SUM(A1:A100) over a twelve-row sheet is an ordinary thing to
+        // write, and returning #REF! for the empty rows would poison the total.
+        //
+        // #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.
+        const key = cellKey(sheet, row, col);
+        const cached = values.get(key);
+        if (cached !== undefined)
+            return cached;
+        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);
+            // 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 {
+                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
+                        : 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. */
+    function literal(text) {
+        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
+                    : typedError(t) ?? t;
+    }
+    function rowCount(sheet) {
+        return sheetCells(sheet)?.length ?? 0;
+    }
+    function colCount(sheet) {
+        const cells = sheetCells(sheet);
+        if (!cells)
+            return 0;
+        return cells.reduce((max, row) => Math.max(max, row.length), 0);
+    }
+    /** 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 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)
+            return;
+        cb(keys.map((key) => {
+            const gap = key.indexOf(' ');
+            const gap2 = key.indexOf(' ', gap + 1);
+            const row = Number(key.slice(0, gap));
+            const col = Number(key.slice(gap + 1, gap2));
+            const sheet = key.slice(gap2 + 1);
+            return { sheet, row, col, value: compute(sheet, row, col) };
+        }));
+    }
+    const workbook = {
+        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;
+        },
+        addSheet(name, at) {
+            const chosen = name ?? nextSheetName(order);
+            if (!isValidSheetName(chosen)) {
+                throw new Error(`"${chosen}" is not a valid sheet name: it must be 1 to 31 characters and must not contain : \\ / ? * [ ]`);
+            }
+            if (sheetCells(chosen))
+                throw new Error(`a sheet named "${chosen}" already exists`);
+            byName.set(chosen.toLowerCase(), []);
+            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) {
+            const index = order.findIndex((n) => n.toLowerCase() === name.toLowerCase());
+            // A workbook with no sheets has nowhere to put the cursor, and Excel
+            // refuses the same way.
+            if (index < 0 || order.length <= 1)
+                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.
+            dropAll();
+            loadEngine();
+            if (active.toLowerCase() === removed.toLowerCase()) {
+                active = order[Math.min(index, order.length - 1)] ?? order[0];
+            }
+            settleAll();
+            return true;
+        },
+        renameSheet(from, to) {
+            const index = order.findIndex((n) => n.toLowerCase() === from.toLowerCase());
+            if (index < 0 || !isValidSheetName(to))
+                return false;
+            if (from.toLowerCase() !== to.toLowerCase() && sheetCells(to))
+                return false;
+            const cells = sheetCells(from);
+            byName.delete(from.toLowerCase());
+            byName.set(to.toLowerCase(), cells);
+            order[index] = to;
+            if (active.toLowerCase() === from.toLowerCase())
+                active = to;
+            // Every formula and name that pointed at the old name points at the
+            // new one, as in Excel; otherwise =Orders!B2 on Summary read #REF!
+            // the moment Orders became Sales. The rewrite goes through the parser,
+            // so a string literal holding the old name is not touched.
+            for (const [, sheet] of byName) {
+                for (const line of sheet) {
+                    for (let c = 0; c < line.length; c += 1) {
+                        const next = renameSheetReferences(line[c], from, to);
+                        if (typeof next === 'string')
+                            line[c] = next;
+                    }
+                }
+            }
+            for (const entry of names.list()) {
+                const next = renameSheetReferences(entry.refersTo, from, to);
+                if (typeof next === 'string' && next !== entry.refersTo)
+                    names.define(entry.name, next);
+            }
+            // 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) {
+            const index = order.findIndex((n) => n.toLowerCase() === name.toLowerCase());
+            if (index < 0)
+                return false;
+            const [moved] = order.splice(index, 1);
+            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] ?? '';
+        },
+        setRaw(sheet, row, col, text) {
+            const cells = sheetCells(sheet);
+            if (!cells || row < 0 || col < 0)
+                return;
+            while (cells.length <= row)
+                cells.push([]);
+            const line = cells[row];
+            while (line.length <= col)
+                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);
+            const keys = [key];
+            // A cell that is no longer a formula reads nothing, and spills nothing.
+            if (!text.trim().startsWith('=')) {
+                graph.setPrecedents(key, null);
+                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, at) {
+            const t = text.trim();
+            if (t === '')
+                return '';
+            if (t.startsWith('=')) {
+                if (!sheetCells(sheet))
+                    return { error: '#REF!' };
+                const ast = parseCached(t);
+                // 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);
+        },
+        evaluateRange(sheet, text) {
+            const t = text.trim();
+            if (!t.startsWith('=') || !sheetCells(sheet))
+                return null;
+            const ast = parseCached(t);
+            return ast ? rangeValues(ast, contextFor(sheet)) : null;
+        },
+        snapshot(sheet) {
+            const rows = rowCount(sheet);
+            const cols = colCount(sheet);
+            const out = [];
+            for (let r = 0; r < rows; r += 1) {
+                const line = [];
+                for (let c = 0; c < cols; c += 1)
+                    line.push(compute(sheet, r, c));
+                out.push(line);
+            }
+            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.
+            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;
+                        // Only references INTO this sheet move: an unqualified one on
+                        // another sheet belongs to that sheet's geometry, which did not
+                        // change, and a reference on THIS sheet that names another sheet
+                        // belongs to that one. The scope tells the rewriter both.
+                        if (other !== sheet && !text.includes(`${sheet}!`) && !text.includes(`'${sheet}'!`))
+                            continue;
+                        const next = fixupReferences(text, edit, { sheet, self: other });
+                        if (typeof next === 'string')
+                            line[c] = next;
+                    }
+                }
+            }
+            // A name has no home sheet, so only one that names this sheet moves.
+            // NetSales = Orders!$I$2:$I$25 must not shift because a column went
+            // into Summary.
+            for (const entry of names.list()) {
+                const next = fixupReferences(entry.refersTo, edit, { sheet, self: null });
+                if (typeof next === 'string' && next !== entry.refersTo)
+                    names.define(entry.name, next);
+            }
+            const blankRow = () => [];
+            if (edit.kind === 'insertRows') {
+                target.splice(edit.at, 0, ...Array.from({ length: edit.count }, blankRow));
+            }
+            else if (edit.kind === 'deleteRows') {
+                target.splice(edit.at, edit.count);
+            }
+            else if (edit.kind === 'insertCols') {
+                for (const line of target) {
+                    if (line.length >= edit.at)
+                        line.splice(edit.at, 0, ...Array(edit.count).fill(''));
+                }
+            }
+            else {
+                for (const line of target) {
+                    if (line.length > edit.at)
+                        line.splice(edit.at, edit.count);
+                }
+            }
+            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() {
+            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 } } : {}),
+            };
+        },
+    };
+    for (const sheet of initial.length > 0 ? initial : [{ name: 'Sheet1', cells: [] }]) {
+        byName.set(sheet.name.toLowerCase(), sheet.cells.map((r) => [...r]));
+        order.push(sheet.name);
+    }
+    active = order[0] ?? '';
+    loadEngine();
+    settleAll();
+    return workbook;
+}
+export { isError };