@svgrid/enterprise 3.0.1 → 3.0.2

package/dist/sheet/document.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The sheet document: the workbook plus everything a sheet keeps beside its
+ * cells, per sheet, in one model.
+ *
+ * The shell used to keep five Maps (format stores, column widths, row
+ * heights, hidden lines, frozen panes), each keyed by sheet name, each
+ * swapped on a sheet switch and each moved by hand on an insert or delete.
+ * Comments, validation rules, conditional formats, protection and merges
+ * would have made it ten. The document holds all of it, moves all of it in
+ * one `shift()` when rows or columns are inserted or deleted, saves and
+ * restores all of it through one `getState()` / `setState()` pair, and tells
+ * a listener once per tick what changed. `SvSheet` is a view over it: it
+ * puts the active sheet's sizes and hidden lines on the grid and writes
+ * them back here whenever they change, so the document is always the
+ * truth and the grid a rendering of it.
+ *
+ * Nothing in here touches the DOM, so a document can be built, edited,
+ * saved and restored in Node, in a test, or on a server.
+ */
+import { type Workbook, type SheetData } from './workbook.js';
+import { type SheetFormatStore, type CellFormatEntry } from './format-store.js';
+import type { FreezeState } from './freeze.js';
+import type { StructuralEdit } from './refs.js';
+import { type NotesMap, type Rect } from './rects.js';
+import { type ValidationRule } from './validation.js';
+import { type CfRule } from './conditional-formats.js';
+import { type AutoFilterState } from './auto-filter.js';
+/** Why the document changed. A listener gets every reason since its last call. */
+export type SheetChangeReason = {
+    kind: 'cells';
+} | {
+    kind: 'formats';
+} | {
+    kind: 'sizes';
+} | {
+    kind: 'hidden';
+} | {
+    kind: 'freeze';
+} | {
+    kind: 'sheets';
+} | {
+    kind: 'comments';
+} | {
+    kind: 'validation';
+} | {
+    kind: 'conditional-formats';
+} | {
+    kind: 'protection';
+} | {
+    kind: 'merges';
+} | {
+    kind: 'filter';
+} | {
+    kind: 'structure';
+    sheet: string;
+    edit: StructuralEdit;
+} | {
+    kind: 'restore';
+};
+/** What one sheet keeps beside its cells. Live objects, not a snapshot. */
+export type PerSheetState = {
+    formats: SheetFormatStore;
+    /** Column widths in px by letter; a letter absent here reads the default. */
+    widths: Record<string, number>;
+    /** Row heights in px by row index; a row absent here reads the default. */
+    heights: Map<number, number>;
+    hidden: {
+        rows: Set<number>;
+        cols: Set<number>;
+    };
+    freeze: FreezeState;
+    /** Cell comments in the grid's `notes` shape: `r4` -> `B` -> text. */
+    notes: NotesMap;
+    protected: boolean;
+    merges: Rect[];
+    /** Data validation rules, in order; the last one covering a cell applies. */
+    validation: ValidationRule[];
+    /** Conditional formatting rules, in priority order: the first one decides. */
+    conditionalFormats: CfRule[];
+    /** Excel's AutoFilter over a region, or null when the arrows are off. */
+    autoFilter: AutoFilterState | null;
+    /** The rows the AutoFilter hides right now; worked out, never saved. */
+    filterHidden: Set<number>;
+};
+/** One sheet's part of a saved document. JSON-safe. */
+export type SheetStateEntry = {
+    formats: Record<string, CellFormatEntry>;
+    columnWidths: Record<string, number>;
+    rowHeights: Array<[row: number, px: number]>;
+    hidden: {
+        rows: number[];
+        cols: number[];
+    };
+    freeze: FreezeState;
+    comments: NotesMap;
+    protected: boolean;
+    merges: Array<[number, number, number, number]>;
+    validation: ValidationRule[];
+    conditionalFormats: CfRule[];
+    autoFilter: AutoFilterState | null;
+};
+/**
+ * A saved document. `workbook` is the raw text of every cell (formulas as
+ * typed), the sheet order, the active sheet and the defined names; `sheets`
+ * is keyed by the sheet's spelled name.
+ */
+export type SheetState = {
+    version: 1;
+    workbook: ReturnType<Workbook['serialize']>;
+    sheets: Record<string, SheetStateEntry>;
+};
+export type SheetDocument = {
+    readonly workbook: Workbook;
+    /** The sheet's state, created on first use. Names compare case-insensitively. */
+    get(name: string): PerSheetState;
+    has(name: string): boolean;
+    rename(from: string, to: string): void;
+    remove(name: string): void;
+    /** The sheets that have state, in no particular order. */
+    names(): string[];
+    /**
+     * Move every position-keyed part of a sheet for an insert or delete:
+     * formats, heights, hidden lines, comments, merges. The workbook's own
+     * cells and formulas move through `workbook.applyStructuralEdit`; the
+     * shell calls both.
+     */
+    shift(name: string, edit: StructuralEdit): void;
+    getState(): SheetState;
+    /**
+     * Put a saved document back. The workbook is edited in place (sheets
+     * added, removed and reordered to match, cells written where they differ,
+     * names and the active sheet set), so the workbook a consumer holds stays
+     * the same object.
+     */
+    setState(state: SheetState): void;
+    /** Hear about changes, once per tick with every reason since the last call. */
+    subscribe(listener: (reasons: ReadonlyArray<SheetChangeReason>) => void): () => void;
+    /** Record a change. Coalesced per microtask; silent while muted. */
+    changed(reason: SheetChangeReason): void;
+    /** Run `fn` without reporting changes: restores and mount-time seeding. */
+    mute<T>(fn: () => T): T;
+};
+export type SheetDocumentInit = {
+    /** An existing workbook to wrap. Created from `sheets` or `state` when absent. */
+    workbook?: Workbook;
+    sheets?: ReadonlyArray<SheetData>;
+    /** A saved document to start from; wins over `sheets`. */
+    state?: SheetState;
+};
+export declare function createSheetDocument(init?: SheetDocumentInit): SheetDocument;

package/dist/sheet/document.js

@@ -0,0 +1,264 @@
+/**
+ * The sheet document: the workbook plus everything a sheet keeps beside its
+ * cells, per sheet, in one model.
+ *
+ * The shell used to keep five Maps (format stores, column widths, row
+ * heights, hidden lines, frozen panes), each keyed by sheet name, each
+ * swapped on a sheet switch and each moved by hand on an insert or delete.
+ * Comments, validation rules, conditional formats, protection and merges
+ * would have made it ten. The document holds all of it, moves all of it in
+ * one `shift()` when rows or columns are inserted or deleted, saves and
+ * restores all of it through one `getState()` / `setState()` pair, and tells
+ * a listener once per tick what changed. `SvSheet` is a view over it: it
+ * puts the active sheet's sizes and hidden lines on the grid and writes
+ * them back here whenever they change, so the document is always the
+ * truth and the grid a rendering of it.
+ *
+ * Nothing in here touches the DOM, so a document can be built, edited,
+ * saved and restored in Node, in a test, or on a server.
+ */
+import { createWorkbook } from './workbook.js';
+import { createFormatStore } from './format-store.js';
+import { lineShift, remapNotes, shiftRect } from './rects.js';
+import { colToLetters, lettersToCol } from './address.js';
+import { shiftValidation } from './validation.js';
+import { shiftCf } from './conditional-formats.js';
+import { shiftAutoFilter } from './auto-filter.js';
+function emptySheetState() {
+    return {
+        formats: createFormatStore(),
+        widths: {},
+        heights: new Map(),
+        hidden: { rows: new Set(), cols: new Set() },
+        freeze: { rows: 0, cols: 0 },
+        notes: {},
+        protected: false,
+        merges: [],
+        validation: [],
+        conditionalFormats: [],
+        autoFilter: null,
+        filterHidden: new Set(),
+    };
+}
+export function createSheetDocument(init = {}) {
+    const workbook = init.workbook ??
+        createWorkbook(init.state ? init.state.workbook.sheets.map((s) => ({ name: s.name, cells: s.cells })) : (init.sheets ? [...init.sheets] : [{ name: 'Sheet1', cells: [] }]));
+    const entries = new Map();
+    const listeners = new Set();
+    let pending = [];
+    let scheduled = false;
+    let muted = 0;
+    const key = (name) => name.toLowerCase();
+    function get(name) {
+        let found = entries.get(key(name));
+        if (!found) {
+            found = emptySheetState();
+            entries.set(key(name), found);
+        }
+        return found;
+    }
+    function flush() {
+        scheduled = false;
+        const batch = pending;
+        pending = [];
+        for (const listener of listeners)
+            listener(batch);
+    }
+    function changed(reason) {
+        if (muted > 0)
+            return;
+        // The same plain reason twice in a tick says nothing new; a structural
+        // edit is worth hearing about each time.
+        if (reason.kind !== 'structure' && pending.some((r) => r.kind === reason.kind))
+            return;
+        pending.push(reason);
+        if (scheduled)
+            return;
+        scheduled = true;
+        queueMicrotask(flush);
+    }
+    function serializeEntry(state) {
+        return {
+            formats: state.formats.serialize(),
+            columnWidths: { ...state.widths },
+            rowHeights: [...state.heights].map(([r, h]) => [r, h]),
+            hidden: { rows: [...state.hidden.rows], cols: [...state.hidden.cols] },
+            freeze: { ...state.freeze },
+            comments: Object.fromEntries(Object.entries(state.notes).map(([r, line]) => [r, { ...line }])),
+            protected: state.protected,
+            merges: state.merges.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]),
+            validation: state.validation.map((rule) => ({ ...rule, rects: rule.rects.map((r) => [...r]), alert: { ...rule.alert } })),
+            conditionalFormats: state.conditionalFormats.map((rule) => ({ ...rule, rects: rule.rects.map((r) => [...r]) })),
+            autoFilter: state.autoFilter ? { range: [...state.autoFilter.range], filters: { ...state.autoFilter.filters } } : null,
+        };
+    }
+    function hydrateEntry(state, entry) {
+        state.formats.hydrate(entry.formats ?? {});
+        state.widths = { ...(entry.columnWidths ?? {}) };
+        state.heights = new Map(entry.rowHeights ?? []);
+        state.hidden = { rows: new Set(entry.hidden?.rows ?? []), cols: new Set(entry.hidden?.cols ?? []) };
+        state.freeze = { rows: entry.freeze?.rows ?? 0, cols: entry.freeze?.cols ?? 0 };
+        state.notes = Object.fromEntries(Object.entries(entry.comments ?? {}).map(([r, line]) => [r, { ...line }]));
+        state.protected = entry.protected ?? false;
+        state.merges = (entry.merges ?? []).map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]);
+        state.validation = (entry.validation ?? []).map((rule) => ({
+            ...rule,
+            rects: rule.rects.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]),
+            alert: { ...rule.alert },
+        }));
+        state.conditionalFormats = (entry.conditionalFormats ?? []).map((rule) => ({
+            ...rule,
+            rects: rule.rects.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]),
+        }));
+        const af = entry.autoFilter;
+        state.autoFilter = af ? { range: [af.range[0], af.range[1], af.range[2], af.range[3]], filters: { ...af.filters } } : null;
+        state.filterHidden = new Set();
+    }
+    const document = {
+        workbook,
+        get,
+        has: (name) => entries.has(key(name)),
+        rename(from, to) {
+            const moved = entries.get(key(from));
+            entries.delete(key(from));
+            if (moved)
+                entries.set(key(to), moved);
+        },
+        remove(name) {
+            entries.delete(key(name));
+        },
+        names: () => [...entries.keys()],
+        shift(name, edit) {
+            const state = get(name);
+            const shift = lineShift(edit);
+            const rows = edit.kind === 'insertRows' || edit.kind === 'deleteRows';
+            if (rows) {
+                state.formats.remapRows((id) => {
+                    const i = Number(id.slice(1));
+                    const next = Number.isInteger(i) ? shift(i) : i;
+                    return next === null ? null : `r${next}`;
+                });
+                const heights = new Map();
+                for (const [r, h] of state.heights) {
+                    const next = shift(r);
+                    if (next !== null)
+                        heights.set(next, h);
+                }
+                state.heights = heights;
+                const hiddenRows = new Set();
+                for (const r of state.hidden.rows) {
+                    const next = shift(r);
+                    if (next !== null)
+                        hiddenRows.add(next);
+                }
+                state.hidden = { rows: hiddenRows, cols: state.hidden.cols };
+                state.notes = remapNotes(state.notes, 'rows', shift);
+            }
+            else {
+                state.formats.remapColumns((id) => {
+                    const i = lettersToCol(id);
+                    const next = i < 0 ? i : shift(i);
+                    return next === null ? null : colToLetters(next);
+                });
+                const widths = {};
+                for (const [letter, w] of Object.entries(state.widths)) {
+                    const i = lettersToCol(letter);
+                    const next = i < 0 ? i : shift(i);
+                    if (next !== null)
+                        widths[i < 0 ? letter : colToLetters(next)] = w;
+                }
+                state.widths = widths;
+                const hiddenCols = new Set();
+                for (const c of state.hidden.cols) {
+                    const next = shift(c);
+                    if (next !== null)
+                        hiddenCols.add(next);
+                }
+                state.hidden = { rows: state.hidden.rows, cols: hiddenCols };
+                state.notes = remapNotes(state.notes, 'cols', shift);
+            }
+            state.merges = state.merges.map((m) => shiftRect(m, edit)).filter((m) => m !== null);
+            state.validation = shiftValidation(state.validation, edit);
+            state.conditionalFormats = shiftCf(state.conditionalFormats, edit);
+            state.autoFilter = shiftAutoFilter(state.autoFilter, edit);
+        },
+        getState() {
+            const sheets = {};
+            for (const name of workbook.sheets)
+                sheets[name] = serializeEntry(get(name));
+            return { version: 1, workbook: workbook.serialize(), sheets };
+        },
+        setState(state) {
+            document.mute(() => {
+                const wanted = state.workbook.sheets.map((s) => s.name);
+                const wantedKeys = new Set(wanted.map(key));
+                // Sheets to add, then the ones to drop (never the last one standing),
+                // then the order, then the cells.
+                for (const name of wanted) {
+                    if (!workbook.sheets.some((s) => key(s) === key(name)))
+                        workbook.addSheet(name);
+                }
+                for (const name of [...workbook.sheets]) {
+                    if (!wantedKeys.has(key(name)) && workbook.sheets.length > 1) {
+                        workbook.removeSheet(name);
+                        entries.delete(key(name));
+                    }
+                }
+                wanted.forEach((name, index) => {
+                    if (workbook.sheets[index]?.toLowerCase() !== key(name))
+                        workbook.moveSheet(name, index);
+                });
+                for (const sheet of state.workbook.sheets) {
+                    const rows = Math.max(workbook.rowCount(sheet.name), sheet.cells.length);
+                    for (let r = 0; r < rows; r += 1) {
+                        const cols = Math.max(workbook.colCount(sheet.name), sheet.cells[r]?.length ?? 0);
+                        for (let c = 0; c < cols; c += 1) {
+                            const text = sheet.cells[r]?.[c] ?? '';
+                            if (workbook.getRaw(sheet.name, r, c) !== text)
+                                workbook.setRaw(sheet.name, r, c, text);
+                        }
+                    }
+                }
+                workbook.names.hydrate(state.workbook.names ?? {});
+                if (workbook.sheets.some((s) => key(s) === key(state.workbook.active)))
+                    workbook.setActive(state.workbook.active);
+                // Entries are hydrated in place, never replaced: a format store the
+                // shell has registered as its target must stay the store in use, or
+                // every format written after a restore would land in an orphan.
+                const kept = new Set(Object.keys(state.sheets ?? {}).map(key));
+                for (const name of [...entries.keys()])
+                    if (!kept.has(name) && !wantedKeys.has(name))
+                        entries.delete(name);
+                for (const name of workbook.sheets)
+                    hydrateEntry(get(name), state.sheets?.[name] ?? {});
+            });
+            changed({ kind: 'restore' });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        changed,
+        mute(fn) {
+            muted += 1;
+            try {
+                return fn();
+            }
+            finally {
+                muted -= 1;
+            }
+        },
+    };
+    if (init.state) {
+        document.mute(() => {
+            workbook.names.hydrate(init.state.workbook.names ?? {});
+            if (workbook.sheets.some((s) => key(s) === key(init.state.workbook.active)))
+                workbook.setActive(init.state.workbook.active);
+            for (const [name, entry] of Object.entries(init.state.sheets ?? {}))
+                hydrateEntry(get(name), entry);
+        });
+    }
+    return document;
+}

package/dist/sheet/edit-keys.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Keys that act on the text of a formula while it is being written.
+ *
+ * F4 in Excel cycles the reference at the caret through its four anchorings:
+ * `A1` -> `$A$1` -> `A$1` -> `$A1` -> `A1`, both ends of a range together.
+ * The caret counts as "at" a reference when it sits inside it or right after
+ * it, which is where it is after typing one. A sheet prefix (`Orders!A1`)
+ * is left as it is; only the cell part turns.
+ */
+export type TextEdit = {
+    text: string;
+    caret: number;
+};
+export declare function cycleReference(text: string, caret: number): TextEdit | null;

package/dist/sheet/edit-keys.js

@@ -0,0 +1,40 @@
+const CELL = String.raw `\$?[A-Za-z]{1,3}\$?\d+`;
+const REFERENCE = new RegExp(String.raw `(${CELL})(?::(${CELL}))?`, 'g');
+/** The next anchoring in Excel's F4 order. */
+function turn(cell) {
+    const m = /^(\$?)([A-Za-z]+)(\$?)(\d+)$/.exec(cell);
+    if (!m)
+        return cell;
+    const [, colAbs, col, rowAbs, row] = m;
+    const state = (colAbs ? 2 : 0) + (rowAbs ? 1 : 0);
+    // relative -> both -> row only -> column only -> relative
+    const next = { 0: 3, 3: 1, 1: 2, 2: 0 }[state];
+    return `${next & 2 ? '$' : ''}${col}${next & 1 ? '$' : ''}${row}`;
+}
+export function cycleReference(text, caret) {
+    if (!text.startsWith('='))
+        return null;
+    REFERENCE.lastIndex = 0;
+    let m;
+    while ((m = REFERENCE.exec(text)) !== null) {
+        const start = m.index;
+        const end = start + m[0].length;
+        if (caret < start || caret > end)
+            continue;
+        // A word character before the match means this is part of a name or a
+        // function (SUM1 is not a cell), not a reference.
+        const before = text[start - 1];
+        if (before && /[A-Za-z0-9_.]/.test(before))
+            continue;
+        // And a parenthesis after it makes it a function call: SUM1 is a cell in
+        // Excel's grid, SUM1( is not.
+        if (text[end] === '(')
+            continue;
+        const replaced = m[2] ? `${turn(m[1])}:${turn(m[2])}` : turn(m[1]);
+        return {
+            text: text.slice(0, start) + replaced + text.slice(end),
+            caret: start + replaced.length,
+        };
+    }
+    return null;
+}

package/dist/sheet/entry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ * Anything else, formulas included, is stored as typed.
+ */
+export type ParsedEntry = {
+    /** The number, as text the workbook stores. */
+    value: string;
+    /** The Excel format string the entry implies. */
+    numFmt: string;
+};
+/**
+ * Excel's AutoComplete for a column of text.
+ *
+ * As a cell is typed into, the entries in the same column that run without
+ * a blank above and below it are the candidates; when exactly one distinct
+ * text entry starts with what was typed, that entry is the completion, in
+ * its own case ("jo" completes to "John Smith"). Two candidates that both
+ * fit ("Apple", "Apricot" for "Ap") complete nothing until the typing tells
+ * them apart. Numbers, formulas and booleans never complete, and a typed
+ * text that already is an entry needs none.
+ *
+ * `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;

package/dist/sheet/entry.js

@@ -0,0 +1,76 @@
+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, '');
+    const n = Number(plain);
+    return Number.isFinite(n) ? n : null;
+}
+const decimalsOf = (digits) => digits.split('.')[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+)?)$`);
+/**
+ * Excel's AutoComplete for a column of text.
+ *
+ * As a cell is typed into, the entries in the same column that run without
+ * a blank above and below it are the candidates; when exactly one distinct
+ * text entry starts with what was typed, that entry is the completion, in
+ * its own case ("jo" completes to "John Smith"). Two candidates that both
+ * fit ("Apple", "Apricot" for "Ap") complete nothing until the typing tells
+ * them apart. Numbers, formulas and booleans never complete, and a typed
+ * text that already is an entry needs none.
+ *
+ * `entries` are the distinct text entries of the run, any order.
+ */
+export function completeEntry(typed, entries) {
+    if (typed === '' || typed.startsWith('=') || typed.includes('\n'))
+        return null;
+    const lower = typed.toLowerCase();
+    let found = null;
+    for (const entry of entries) {
+        if (entry.length <= typed.length || !entry.toLowerCase().startsWith(lower))
+            continue;
+        if (found !== null && found !== entry)
+            return null;
+        found = entry;
+    }
+    return found;
+}
+export function parseEntry(text) {
+    const t = text.trim();
+    if (t === '' || t.startsWith('='))
+        return null;
+    let m = PERCENT.exec(t);
+    if (m) {
+        const n = numberOf(m[2]);
+        if (n === null)
+            return null;
+        const places = decimalsOf(m[2]);
+        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);
+    if (m || paren) {
+        const digits = (m ? m[2] : paren[1]);
+        const n = numberOf(digits);
+        if (n === null)
+            return null;
+        const negative = m ? m[1] === '-' : true;
+        const places = decimalsOf(digits) > 0 ? 2 : 0;
+        const body = `$#,##0${zeros(places)}`;
+        return { value: String(negative ? -n : n), numFmt: `${body};(${body})` };
+    }
+    m = THOUSANDS.exec(t);
+    if (m) {
+        const n = numberOf(m[2]);
+        if (n === null)
+            return null;
+        const places = decimalsOf(m[2]);
+        return { value: String(m[1] ? -n : n), numFmt: `#,##0${zeros(places)}` };
+    }
+    return null;
+}

package/dist/sheet/evaluate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The evaluator.
+ *
+ * Errors travel as VALUES once evaluation finishes, but as thrown
+ * `FormulaError`s while it runs. That split is deliberate: a coercion buried
+ * three calls deep inside a function needs to abort the whole expression, and
+ * threading a result type through every branch of every builtin would swamp the
+ * table. The throw is caught here, at the one boundary, and becomes a value.
+ *
+ * Four functions never reach the table because they must NOT have every
+ * argument evaluated first: IF and IFS pick a branch, IFERROR needs to catch,
+ * and SWITCH matches before evaluating. Evaluating both branches of an IF is
+ * not just wasted work - `=IF(A1=0, 0, 100/A1)` would raise #DIV/0! from the
+ * branch it did not take.
+ */
+import { type CellValue, type Node } from './ast.js';
+import { type SheetFunction } from './functions.js';
+import { type TableRegion } from './tables.js';
+export type EvalContext = {
+    /** Read one cell. Out of bounds should return `{ error: '#REF!' }`. */
+    resolve(sheet: string | null, row: number, col: number): CellValue;
+    /** Last used row of a sheet, for open-ended whole-column ranges. */
+    lastRow(sheet: string | null): number;
+    /**
+     * Resolve a defined name to the reference it stands for, or null when
+     * there is no such name. The node is evaluated in place of the name, so a
+     * name that refers to a range behaves as that range: `=SUM(Sales)` adds
+     * the whole column and `=VLOOKUP(x, Prices, 2)` searches the whole table.
+     * Preferred over `resolveName`, which can only ever produce one value.
+     */
+    resolveNameNode?(name: string): Node | null;
+    /** Resolve a defined name to a single value. Consulted when
+     *  `resolveNameNode` is absent or returns null; undefined is #NAME?. */
+    resolveName?(name: string): CellValue | undefined;
+    functions?: Record<string, SheetFunction>;
+    /** Look a table up by name. */
+    findTable?(name: string): TableRegion | undefined;
+    /** The table containing the cell the formula lives in, which is the only
+     *  way the unqualified `[@Amount]` form can mean anything. */
+    tableAt?(sheet: string | null, row: number, col: number): TableRegion | undefined;
+    /** Where the formula being evaluated sits. Needed for `[@Column]`, which
+     *  is relative to the formula rather than to the table. */
+    currentCell?: {
+        sheet: string | null;
+        row: number;
+        col: number;
+    };
+};
+/**
+ * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
+ * inside becomes the matching error value.
+ */
+/**
+ * The values a node stands for as a grid: a range, a reference (one cell),
+ * or a name that refers to either. Null for anything else, which is how a
+ * caller tells "a list source that is a range" from "a formula".
+ */
+export declare function rangeValues(node: Node, ctx: EvalContext): CellValue[][] | null;
+export declare function evaluate(node: Node, ctx: EvalContext): CellValue;
+/** Render a computed value the way a cell shows it. */
+export declare function formatValue(v: CellValue): string;