@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/entry.d.ts

@@ -6,13 +6,17 @@
  * the user typed names both a value and how to show it, and the cell keeps
  * both, so `=A1*2` over a `12%` cell is 0.24 rather than `#VALUE!`. The
  * format is the one Excel would pick, with the decimals the user typed.
- * Anything else, formulas included, is stored as typed.
+ * `3/4/2026` is the sheet's `2026-03-04` under a date format and `10:30`
+ * is 0.4375 of a day under a time format, for the same reason. Anything
+ * else, formulas included, is stored as typed.
  */
+import { type SheetCulture } from './culture.js';
 export type ParsedEntry = {
     /** The number, as text the workbook stores. */
     value: string;
-    /** The Excel format string the entry implies. */
-    numFmt: string;
+    /** The Excel format string the entry implies; none for a bare number
+     *  read out of an accountant's parentheses, which Excel shows as General. */
+    numFmt?: string;
 };
 /**
  * Excel's AutoComplete for a column of text.
@@ -28,4 +32,4 @@ export type ParsedEntry = {
  * `entries` are the distinct text entries of the run, any order.
  */
 export declare function completeEntry(typed: string, entries: Iterable<string>): string | null;
-export declare function parseEntry(text: string): ParsedEntry | null;
+export declare function parseEntry(text: string, culture?: SheetCulture): ParsedEntry | null;

package/dist/sheet/entry.js

@@ -1,18 +1,79 @@
+/**
+ * What Excel makes of a typed entry before it is stored.
+ *
+ * `12%` is the number 0.12 shown as a percentage, `$1,200` is 1200 shown
+ * as currency, `1,234.5` is 1234.5 with a thousands separator: the text
+ * the user typed names both a value and how to show it, and the cell keeps
+ * both, so `=A1*2` over a `12%` cell is 0.24 rather than `#VALUE!`. The
+ * format is the one Excel would pick, with the decimals the user typed.
+ * `3/4/2026` is the sheet's `2026-03-04` under a date format and `10:30`
+ * is 0.4375 of a day under a time format, for the same reason. Anything
+ * else, formulas included, is stored as typed.
+ */
+import { INVARIANT_CULTURE, isInvariant, parseNumberInCulture, slashDateParts, SPACE_GROUP_MARKS } from './culture.js';
 const zeros = (n) => (n > 0 ? '.' + '0'.repeat(n) : '');
-/** Digits with optional thousands separators and decimals, as a number. */
-function numberOf(digits) {
-    const plain = digits.replace(/,/g, '');
+/** For putting a separator that may be `.` or a space inside a pattern. */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const PATTERN_CACHE = new Map();
+function patternsFor(culture) {
+    const key = `${culture.decimal}\u0000${culture.group}\u0000${culture.dateOrder}`;
+    const hit = PATTERN_CACHE.get(key);
+    if (hit)
+        return hit;
+    const d = escapeRe(culture.decimal);
+    // A space-like group mark is accepted in any of its shapes, since a
+    // narrow no-break space is what fr-FR formats with and a plain space is
+    // what anyone types.
+    const g = /\s/.test(culture.group) ? '[\\s\\u00a0\\u202f]' : escapeRe(culture.group);
+    const grouped = String.raw `(?:\d{1,3}(?:${g}\d{3})+|\d+)(?:${d}\d+)?`;
+    const built = {
+        culture,
+        percent: new RegExp(String.raw `^(-?)(${grouped})\s?%$`),
+        currency: new RegExp(String.raw `^(-?)\$\s?(${grouped})$`),
+        currencyParen: new RegExp(String.raw `^\(\$\s?(${grouped})\)$`),
+        thousands: new RegExp(String.raw `^(-?)(\d{1,3}(?:${g}\d{3})+(?:${d}\d+)?)$`),
+        /** (5): a negative the way a statement writes one, read as -5. */
+        paren: new RegExp(String.raw `^\((${grouped})\)$`),
+        slashDate: /^(\d{1,2})\/(\d{1,2})(?:\/(\d{2}|\d{4}))?$/,
+    };
+    PATTERN_CACHE.set(key, built);
+    return built;
+}
+/** Digits with optional group marks and decimals, as a number. */
+function numberOf(digits, culture) {
+    let plain = digits;
+    for (const g of [culture.group, ...SPACE_GROUP_MARKS]) {
+        if (g !== '' && g !== culture.decimal)
+            plain = plain.split(g).join('');
+    }
+    if (culture.decimal !== '.')
+        plain = plain.split(culture.decimal).join('.');
     const n = Number(plain);
     return Number.isFinite(n) ? n : null;
 }
-const decimalsOf = (digits) => digits.split('.')[1]?.length ?? 0;
+const decimalsOf = (digits, culture) => digits.split(culture.decimal)[1]?.length ?? 0;
 /** Round away the binary noise of a division: 33.3% is 0.333, not 0.33299999. */
 const trim = (n, places) => String(Number(n.toFixed(places)));
-const GROUPED = String.raw `(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?`;
-const PERCENT = new RegExp(String.raw `^(-?)(${GROUPED})\s?%$`);
-const CURRENCY = new RegExp(String.raw `^(-?)\$\s?(${GROUPED})$`);
-const CURRENCY_PAREN = new RegExp(String.raw `^\(\$\s?(${GROUPED})\)$`);
-const THOUSANDS = new RegExp(String.raw `^(-?)(\d{1,3}(?:,\d{3})+(?:\.\d+)?)$`);
+// A fraction typed with a whole part, as Excel takes one: `3 1/2` is 3.5 and
+// `0 1/2` is the way to enter a bare half without `1/2` becoming a date. The
+// whole part is required - that space is what tells it apart from a date.
+const FRACTION = /^(-?)(\d+)\s+(\d+)\/(\d+)$/;
+const CLOCK = /^(\d{1,2}):(\d{2})(?::(\d{2}))?(?:\s*([AaPp])\.?[Mm]?\.?)?$/;
+const pad2 = (n) => String(n).padStart(2, '0');
+/** English month names to a 1-12 number: `jan`/`january` alike. */
+const MONTH_NUMBER = (() => {
+    const full = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+    const out = {};
+    full.forEach((name, i) => { out[name] = i + 1; out[name.slice(0, 3)] = i + 1; });
+    out.sept = 9;
+    return out;
+})();
+// A day and a month name in either order, with an optional year:
+// 4-Mar-2026, 4 Mar 26, Mar 4, March 4, 2026. The separator is a space,
+// a hyphen or (for the day-first form) a slash; a comma may follow the day.
+const DAY_MONTH = /^(\d{1,2})[\s\-/]+([A-Za-z]{3,9})(?:,?[\s\-/]+(\d{2}|\d{4}))?$/;
+const MONTH_DAY = /^([A-Za-z]{3,9})[\s\-/]+(\d{1,2})(?:,?[\s\-/]+(\d{2}|\d{4}))?$/;
+const yearOf = (raw) => raw === undefined ? new Date().getFullYear() : raw.length === 2 ? (Number(raw) < 30 ? 2000 : 1900) + Number(raw) : Number(raw);
 /**
  * Excel's AutoComplete for a column of text.
  *
@@ -40,37 +101,126 @@ export function completeEntry(typed, entries) {
     }
     return found;
 }
-export function parseEntry(text) {
+export function parseEntry(text, culture = INVARIANT_CULTURE) {
     const t = text.trim();
-    if (t === '' || t.startsWith('='))
+    // An apostrophe says the rest is text, so nothing is read out of it and no
+    // format is implied: '12% is the text 12%, not twelve percent.
+    if (t === '' || t.startsWith('=') || t.startsWith("'"))
         return null;
-    let m = PERCENT.exec(t);
+    const p = patternsFor(culture);
+    let m = p.percent.exec(t);
     if (m) {
-        const n = numberOf(m[2]);
+        const n = numberOf(m[2], culture);
         if (n === null)
             return null;
-        const places = decimalsOf(m[2]);
+        const places = decimalsOf(m[2], culture);
         return { value: trim((m[1] ? -n : n) / 100, places + 2), numFmt: `0${zeros(places)}%` };
     }
-    m = CURRENCY.exec(t);
-    const paren = m ? null : CURRENCY_PAREN.exec(t);
+    m = p.currency.exec(t);
+    const paren = m ? null : p.currencyParen.exec(t);
     if (m || paren) {
         const digits = (m ? m[2] : paren[1]);
-        const n = numberOf(digits);
+        const n = numberOf(digits, culture);
         if (n === null)
             return null;
         const negative = m ? m[1] === '-' : true;
-        const places = decimalsOf(digits) > 0 ? 2 : 0;
+        const places = decimalsOf(digits, culture) > 0 ? 2 : 0;
         const body = `$#,##0${zeros(places)}`;
         return { value: String(negative ? -n : n), numFmt: `${body};(${body})` };
     }
-    m = THOUSANDS.exec(t);
+    m = p.thousands.exec(t);
     if (m) {
-        const n = numberOf(m[2]);
+        const n = numberOf(m[2], culture);
         if (n === null)
             return null;
-        const places = decimalsOf(m[2]);
+        const places = decimalsOf(m[2], culture);
         return { value: String(m[1] ? -n : n), numFmt: `#,##0${zeros(places)}` };
     }
+    m = p.paren.exec(t);
+    if (m) {
+        const n = numberOf(m[1], culture);
+        return n === null ? null : { value: String(-n) };
+    }
+    // A plain number written the culture's way, with no format implied.
+    //
+    // The invariant culture never reaches here with anything to do, since
+    // `1.5` is already what the document stores, and returning null lets the
+    // caller keep the text exactly as typed. A culture that spells it `1,5`
+    // does have something to do: the stored value has to be turned back into
+    // the invariant spelling, or the engine reads a comma it cannot parse.
+    if (!isInvariant(culture)) {
+        const n = parseNumberInCulture(t, culture);
+        if (n !== null)
+            return { value: String(n) };
+    }
+    // A mixed fraction: 3 1/2 is 3.5, shown back as the fraction under Excel's
+    // `# ?/?` format, so it adds up and =A1*2 over it is 7 rather than #VALUE!.
+    // The whole part is required, which is what keeps 1/2 a date and 0 1/2 a
+    // half. The format widens to the digits typed, so 3 11/16 keeps two.
+    m = FRACTION.exec(t);
+    if (m) {
+        const den = Number(m[4]);
+        if (den === 0)
+            return null;
+        const value = (m[1] ? -1 : 1) * (Number(m[2]) + Number(m[3]) / den);
+        return { value: trim(value, 10), numFmt: `# ${'?'.repeat(m[3].length)}/${'?'.repeat(m[4].length)}` };
+    }
+    // A slash date, in the order the culture writes one: 3/4/2026 is the
+    // fourth of March where the locale puts the month first and the third of
+    // April where it puts the day first. A two-digit year 00-29 is this
+    // century, 30-99 the last. Stored as the sheet's `yyyy-mm-dd` text,
+    // which is what the date functions read and what the file writer turns
+    // into a serial, under a date format so the ribbon says Date and a
+    // formula over it inherits one.
+    m = p.slashDate.exec(t);
+    if (m) {
+        const parts = slashDateParts(Number(m[1]), Number(m[2]), culture);
+        if (!parts)
+            return null;
+        const y = yearOf(m[3]);
+        const { month, day } = parts;
+        if (day <= new Date(Date.UTC(y, month, 0)).getUTCDate()) {
+            return { value: `${y}-${pad2(month)}-${pad2(day)}`, numFmt: 'yyyy-mm-dd' };
+        }
+        return null;
+    }
+    // A date written with the month spelled out, as Excel reads one:
+    // 4-Mar-2026, 4 Mar 26, March 4, 2026, Mar 4. English month names only,
+    // the language the shell speaks; stored the same yyyy-mm-dd as a slash
+    // date. Either order, so both 4-Mar and Mar-4 are the fourth of March.
+    const monthDate = (dayText, monthName, yearText) => {
+        const month = MONTH_NUMBER[monthName.toLowerCase()];
+        if (month === undefined)
+            return null;
+        const day = Number(dayText);
+        const y = yearOf(yearText);
+        if (day < 1 || day > new Date(Date.UTC(y, month, 0)).getUTCDate())
+            return null;
+        return { value: `${y}-${pad2(month)}-${pad2(day)}`, numFmt: 'd-mmm-yyyy' };
+    };
+    m = DAY_MONTH.exec(t);
+    if (m)
+        return monthDate(m[1], m[2], m[3]);
+    m = MONTH_DAY.exec(t);
+    if (m)
+        return monthDate(m[2], m[1], m[3]);
+    // A clock time is the fraction of the day it is, 10:30 being 0.4375, under
+    // the time format that shows it back, so times add up and =A1*2 over one
+    // is 21:00 rather than #VALUE!. 10:30 PM is the same fraction past noon.
+    m = CLOCK.exec(t);
+    if (m) {
+        let hours = Number(m[1]);
+        const minutes = Number(m[2]), seconds = Number(m[3] ?? 0);
+        const meridiem = m[4]?.toLowerCase();
+        if (meridiem) {
+            if (hours < 1 || hours > 12)
+                return null;
+            hours = (hours % 12) + (meridiem === 'p' ? 12 : 0);
+        }
+        if (hours > 23 || minutes > 59 || seconds > 59)
+            return null;
+        const fraction = (hours * 3600 + minutes * 60 + seconds) / 86400;
+        return { value: String(Number(fraction.toFixed(10))), numFmt: `h:mm${m[3] ? ':ss' : ''}${meridiem ? ' AM/PM' : ''}` };
+    }
     return null;
 }

package/dist/sheet/error-check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Excel's Error Checking: the sheet read once, the cells worth a second
+ * look listed in reading order.
+ *
+ * Two findings, both Excel's own. A cell whose formula works out to an
+ * error is the obvious one, and the dialog says what the error means rather
+ * than leaving `#VALUE!` to be looked up. A formula that breaks the pattern
+ * of the ones above and below it is the useful one: it is how a total that
+ * was dragged one row short, or a cell overtyped with a constant, is found
+ * in a column of two hundred that all look alike.
+ *
+ * Kept out of the shell so it can be tested on a workbook and run by
+ * anything else that wants the list: a save-time check, a report, an agent.
+ */
+import { type CellValue, type SheetError } from './ast.js';
+export type ErrorFindingKind = 'error' | 'inconsistent';
+export type ErrorFinding = {
+    sheet: string;
+    row: number;
+    col: number;
+    kind: ErrorFindingKind;
+    /** The cell's text, which is the formula for both kinds. */
+    text: string;
+    /** The error in the cell, for `kind: 'error'`. */
+    error?: SheetError;
+    /** What the column's own pattern says the formula would be, for
+     *  `kind: 'inconsistent'`. */
+    expected?: string;
+};
+/** What each error means, in a sentence, the way Excel's dialog explains it. */
+export declare const ERROR_MEANINGS: Record<SheetError, string>;
+export type SheetReader = {
+    rowCount(): number;
+    colCount(): number;
+    getRaw(row: number, col: number): string;
+    getValue(row: number, col: number): CellValue;
+};
+/**
+ * Every cell worth a look on one sheet, in reading order.
+ *
+ * `inconsistent` is deliberately quiet: a formula is only called the odd one
+ * out when the cells above and below it both hold formulas, those two agree
+ * with each other once translated, and this one does not. That is the shape
+ * of a column filled down and then broken in the middle, and it is the only
+ * shape reported, because an auditing tool that cries wolf is turned off.
+ */
+export declare function checkSheet(sheet: string, read: SheetReader): ErrorFinding[];
+/** One line saying what is wrong with a cell, for a dialog or a log. */
+export declare function describeFinding(finding: ErrorFinding): string;

package/dist/sheet/error-check.js

@@ -0,0 +1,83 @@
+/**
+ * Excel's Error Checking: the sheet read once, the cells worth a second
+ * look listed in reading order.
+ *
+ * Two findings, both Excel's own. A cell whose formula works out to an
+ * error is the obvious one, and the dialog says what the error means rather
+ * than leaving `#VALUE!` to be looked up. A formula that breaks the pattern
+ * of the ones above and below it is the useful one: it is how a total that
+ * was dragged one row short, or a cell overtyped with a constant, is found
+ * in a column of two hundred that all look alike.
+ *
+ * Kept out of the shell so it can be tested on a workbook and run by
+ * anything else that wants the list: a save-time check, a report, an agent.
+ */
+import { isError } from './ast.js';
+import { translateFormula } from './refs.js';
+/** What each error means, in a sentence, the way Excel's dialog explains it. */
+export const ERROR_MEANINGS = {
+    '#REF!': 'The formula points at a cell that is no longer there, usually because a row, a column or a sheet was deleted.',
+    '#CYCLE!': 'The formula depends on its own cell, directly or through others. Turn on iterative calculation if the loop is meant.',
+    '#DIV/0!': 'Something is divided by zero, or by a blank cell, which counts as zero.',
+    '#VALUE!': 'An argument is the wrong kind: text where a number is needed, most often.',
+    '#NAME?': 'A name in the formula is not known: a misspelled function, a defined name that does not exist, or text left without quotes.',
+    '#NUM!': 'The numbers are out of range for what was asked: a root of a negative, or a value too large to hold.',
+    '#N/A': 'A lookup found nothing. This is the answer, not a fault, when the value really is not there.',
+    '#PARSE!': 'The formula could not be read. A bracket or a quote is usually missing.',
+    '#SPILL!': 'The answer is a block, and something is in the way of it. Clear the cells the outline covers.',
+    '#CALC!': 'The answer is a block the sheet cannot hold: an empty array, or an array inside an array.',
+    '#NULL!': 'Two ranges were asked to overlap and do not. Excel writes it for an intersection with nothing in it.',
+};
+/**
+ * Every cell worth a look on one sheet, in reading order.
+ *
+ * `inconsistent` is deliberately quiet: a formula is only called the odd one
+ * out when the cells above and below it both hold formulas, those two agree
+ * with each other once translated, and this one does not. That is the shape
+ * of a column filled down and then broken in the middle, and it is the only
+ * shape reported, because an auditing tool that cries wolf is turned off.
+ */
+export function checkSheet(sheet, read) {
+    const out = [];
+    const rows = read.rowCount();
+    const cols = read.colCount();
+    for (let row = 0; row < rows; row += 1) {
+        for (let col = 0; col < cols; col += 1) {
+            const text = read.getRaw(row, col).trim();
+            if (!text.startsWith('='))
+                continue;
+            const value = read.getValue(row, col);
+            if (isError(value)) {
+                out.push({ sheet, row, col, kind: 'error', text, error: value.error });
+                continue;
+            }
+            const expected = inconsistentWith(read, row, col, text);
+            if (expected !== null)
+                out.push({ sheet, row, col, kind: 'inconsistent', text, expected });
+        }
+    }
+    return out;
+}
+/** The formula this cell would hold if it followed its neighbours, or null
+ *  when it already does or there is no pattern to follow. */
+function inconsistentWith(read, row, col, text) {
+    if (row < 1)
+        return null;
+    const above = read.getRaw(row - 1, col).trim();
+    const below = read.getRaw(row + 1, col).trim();
+    if (!above.startsWith('=') || !below.startsWith('='))
+        return null;
+    const expected = translateFormula(above, 1, 0);
+    if (typeof expected !== 'string')
+        return null;
+    // The neighbours have to agree with each other, or there is no pattern.
+    if (translateFormula(above, 2, 0) !== below)
+        return null;
+    return expected === text ? null : expected;
+}
+/** One line saying what is wrong with a cell, for a dialog or a log. */
+export function describeFinding(finding) {
+    if (finding.kind === 'error')
+        return ERROR_MEANINGS[finding.error ?? '#VALUE!'];
+    return `This formula is not the one the cells above and below it use. Theirs would read ${finding.expected} here.`;
+}

package/dist/sheet/evaluate-steps.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Excel's Evaluate Formula, as a list of steps.
+ *
+ * The dialog shows a formula with one part underlined, and every click
+ * replaces that part with what it is worth, until the whole thing is the
+ * cell's answer. It is the fastest way to find which half of a long formula
+ * is the wrong half, which is why it is the auditing tool people reach for
+ * after the tracing arrows.
+ *
+ * The steps are worked out here rather than in the dialog, so they can be
+ * tested without a browser and reused by anything that wants to explain a
+ * formula: a tooltip, a report, an agent.
+ *
+ * How a part is evaluated: it is printed back to a formula and handed to the
+ * caller, which passes it to the workbook. That keeps this module out of the
+ * evaluator entirely, so names, tables, other sheets and custom functions all
+ * mean exactly what they mean in the cell, with no second implementation to
+ * disagree with the first.
+ */
+import { type CellValue, type Node } from './ast.js';
+/**
+ * A formula printed back from its tree, without the leading `=`.
+ *
+ * The printer a fill-down already uses, so a step reads the way the sheet
+ * itself would write the formula, brackets and all.
+ */
+export declare function printNode(node: Node): string;
+/** What a value looks like inside a formula being stepped through. */
+export declare function printValue(value: CellValue): string;
+export type EvaluationStep = {
+    /** The formula as it stands before this step, `=` included. */
+    formula: string;
+    /** The part about to be worked out, as offsets into `formula`. */
+    from: number;
+    to: number;
+    /** That part on its own, as it reads at this point in the walk. */
+    expression: string;
+    /** What it is worth. */
+    value: CellValue;
+};
+/**
+ * Walk a formula the way Excel's Evaluate Formula does.
+ *
+ * `evaluate` is given one sub-formula at a time, `=` included, and answers
+ * with its value; the workbook's `evaluateText` is exactly that. The last
+ * step's value is the cell's own.
+ */
+export declare function evaluationSteps(ast: Node, evaluate: (formula: string) => CellValue, limit?: number): EvaluationStep[];

package/dist/sheet/evaluate-steps.js

@@ -0,0 +1,196 @@
+/**
+ * Excel's Evaluate Formula, as a list of steps.
+ *
+ * The dialog shows a formula with one part underlined, and every click
+ * replaces that part with what it is worth, until the whole thing is the
+ * cell's answer. It is the fastest way to find which half of a long formula
+ * is the wrong half, which is why it is the auditing tool people reach for
+ * after the tracing arrows.
+ *
+ * The steps are worked out here rather than in the dialog, so they can be
+ * tested without a browser and reused by anything that wants to explain a
+ * formula: a tooltip, a report, an agent.
+ *
+ * How a part is evaluated: it is printed back to a formula and handed to the
+ * caller, which passes it to the workbook. That keeps this module out of the
+ * evaluator entirely, so names, tables, other sheets and custom functions all
+ * mean exactly what they mean in the cell, with no second implementation to
+ * disagree with the first.
+ */
+import { isError, PRECEDENCE } from './ast.js';
+import { formatFormula } from './refs.js';
+/** A reference that stands for a block rather than one value: printed, never
+ *  replaced, because `A1:A9` on its own is not a number. */
+function isBlock(node) {
+    return node.k === 'range' || node.k === 'name' || node.k === 'table';
+}
+/**
+ * A formula printed back from its tree, without the leading `=`.
+ *
+ * The printer a fill-down already uses, so a step reads the way the sheet
+ * itself would write the formula, brackets and all.
+ */
+export function printNode(node) {
+    return formatFormula(node).slice(1);
+}
+/** What a value looks like inside a formula being stepped through. */
+export function printValue(value) {
+    if (isError(value))
+        return value.error;
+    if (typeof value === 'string')
+        return `"${value.replace(/"/g, '""')}"`;
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    return String(value);
+}
+function toWork(node) {
+    switch (node.k) {
+        case 'unary': return { kind: 'node', node, children: [toWork(node.arg)] };
+        case 'binary': return { kind: 'node', node, children: [toWork(node.left), toWork(node.right)] };
+        case 'fn': return { kind: 'node', node, children: node.args.map(toWork) };
+        default: return { kind: 'node', node, children: [] };
+    }
+}
+/** The formula a piece of the working tree stands for. */
+function originOf(work) {
+    if (work.kind === 'value')
+        return work.origin;
+    const node = work.node;
+    switch (node.k) {
+        case 'unary': return { ...node, arg: originOf(work.children[0]) };
+        case 'binary': return { ...node, left: originOf(work.children[0]), right: originOf(work.children[1]) };
+        case 'fn': return { ...node, args: work.children.map(originOf) };
+        default: return node;
+    }
+}
+/** Print the working tree, and record where each piece landed. */
+function printWork(work, spans, at = 0) {
+    const record = (text) => {
+        spans.set(work, [at, at + text.length]);
+        return text;
+    };
+    if (work.kind === 'value')
+        return record(printValue(work.value));
+    const node = work.node;
+    if (work.children.length === 0)
+        return record(printNode(node));
+    if (node.k === 'unary') {
+        const arg = work.children[0];
+        if (node.op === '%') {
+            const inner = printWorkWrapped(arg, spans, at, 6);
+            return record(`${inner}%`);
+        }
+        const inner = printWorkWrapped(arg, spans, at + node.op.length, 5);
+        return record(`${node.op}${inner}`);
+    }
+    if (node.k === 'binary') {
+        // The shared printer's rule: at equal precedence the right operand takes
+        // the bracket, and `^` is the mirror of that because it binds rightwards.
+        const p = PRECEDENCE[node.op];
+        const rightAssociative = node.op === '^';
+        const left = printWorkWrapped(work.children[0], spans, at, rightAssociative ? p + 1 : p);
+        const right = printWorkWrapped(work.children[1], spans, at + left.length + node.op.length, rightAssociative ? p : p + 1);
+        return record(`${left}${node.op}${right}`);
+    }
+    // A function call, including the `(` node a lambda's arguments build.
+    const lambda = node.k === 'fn' && node.name === '(';
+    const head = lambda ? printWork(work.children[0], spans, at) : `${node.name}`;
+    const args = lambda ? work.children.slice(1) : work.children;
+    let out = `${head}(`;
+    args.forEach((child, i) => {
+        if (i > 0)
+            out += ',';
+        out += printWork(child, spans, at + out.length);
+    });
+    return record(`${out})`);
+}
+function printWorkWrapped(work, spans, at, need) {
+    const bare = work.kind === 'node'
+        && ((work.node.k === 'binary' && PRECEDENCE[work.node.op] < need)
+            || (work.node.k === 'unary' && work.node.op !== '%' && need > 5));
+    const inner = printWork(work, spans, at + (bare ? 1 : 0));
+    return bare ? `(${inner})` : inner;
+}
+/**
+ * The next piece to evaluate: the leftmost, deepest one whose own parts are
+ * already values. A block reference (`A1:A9`, a name, a table column) is
+ * left where it is, and so is a literal, since neither is a step.
+ */
+function nextPiece(work) {
+    if (work.kind === 'value')
+        return null;
+    const node = work.node;
+    // IF picks a branch. Once the condition is a value the whole call is one
+    // step, so the branch that is not taken is never evaluated and never
+    // reports an error the cell does not have.
+    const isIf = node.k === 'fn' && node.name === 'IF';
+    if (isIf) {
+        const condition = work.children[0];
+        if (condition && condition.kind !== 'value') {
+            const inner = nextPiece(condition);
+            return inner ?? condition;
+        }
+        return work;
+    }
+    for (const child of work.children) {
+        const inner = nextPiece(child);
+        if (inner)
+            return inner;
+    }
+    if (work.children.length === 0) {
+        // A leaf: a single cell is a step, a literal and a block are not.
+        return node.k === 'ref' ? work : null;
+    }
+    // Every child is a value or a block, so this call is ready.
+    return work.children.every((c) => c.kind === 'value' || (c.kind === 'node' && (isBlock(c.node) || c.node.k === 'empty' || c.children.length === 0)))
+        ? work
+        : null;
+}
+/**
+ * Walk a formula the way Excel's Evaluate Formula does.
+ *
+ * `evaluate` is given one sub-formula at a time, `=` included, and answers
+ * with its value; the workbook's `evaluateText` is exactly that. The last
+ * step's value is the cell's own.
+ */
+export function evaluationSteps(ast, evaluate, limit = 100) {
+    const steps = [];
+    let root = toWork(ast);
+    for (let i = 0; i < limit; i += 1) {
+        const spans = new Map();
+        const formula = printWork(root, spans);
+        const piece = nextPiece(root);
+        if (!piece)
+            break;
+        const span = spans.get(piece);
+        if (!span)
+            break;
+        // Evaluated as the formula it really is, with every reference still in
+        // place, and shown as it now reads, with the parts already worked out
+        // standing as their values. The two agree because a replacement only
+        // ever stands for what it was worth.
+        const origin = originOf(piece);
+        const value = evaluate(`=${printNode(origin)}`);
+        steps.push({
+            formula: `=${formula}`,
+            from: span[0] + 1,
+            to: span[1] + 1,
+            expression: formula.slice(span[0], span[1]),
+            value,
+        });
+        const replaced = { kind: 'value', value, origin };
+        root = replace(root, piece, replaced);
+        if (root === replaced)
+            break;
+    }
+    return steps;
+}
+/** The tree with one piece swapped out. */
+function replace(work, target, next) {
+    if (work === target)
+        return next;
+    if (work.kind === 'value')
+        return work;
+    const children = work.children.map((c) => replace(c, target, next));
+    return children.some((c, i) => c !== work.children[i]) ? { ...work, children } : work;
+}