@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/document.js

@@ -0,0 +1,465 @@
+/**
+ * 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 { copyProtection, defaultProtection } from './protection.js';
+import { copyPageSetup, defaultPageSetup, shiftPageSetup } from './page-setup.js';
+import { copyObject, objectId, shiftObjects } from './objects.js';
+import { copySparkline, shiftSparklines, sparklineId } from './sparklines.js';
+import { copyPivot, pivotId, shiftPivots } from './pivot-range.js';
+import { copyLinks, shiftLinks } from './links.js';
+import { releaseFilteredRows } from './filter-files.js';
+import { colToLetters, lettersToCol } from './address.js';
+import { shiftValidation } from './validation.js';
+import { shiftCf } from './conditional-formats.js';
+import { shiftAutoFilter } from './auto-filter.js';
+import { copyCellType, shiftCellTypes } from './cell-types.js';
+import { copyGridSheet } from './sheet-kinds.js';
+import { emptyOutline, shiftOutline } from './outline.js';
+/** A deep copy of one axis's outline, absent reading as an empty one. */
+const copyOutline = (o) => (o ? { levels: { ...o.levels }, collapsed: [...o.collapsed] } : emptyOutline());
+/** Which change a patched part of a sheet counts as, so listeners hear it. */
+function reasonsForEntry(entry) {
+    const out = [];
+    if (entry.formats !== undefined)
+        out.push({ kind: 'formats' });
+    if (entry.columnWidths !== undefined || entry.rowHeights !== undefined)
+        out.push({ kind: 'sizes' });
+    if (entry.hidden !== undefined || entry.sheetHidden !== undefined)
+        out.push({ kind: 'hidden' });
+    if (entry.freeze !== undefined)
+        out.push({ kind: 'freeze' });
+    if (entry.comments !== undefined)
+        out.push({ kind: 'comments' });
+    if (entry.protected !== undefined || entry.protection !== undefined)
+        out.push({ kind: 'protection' });
+    if (entry.pageSetup !== undefined)
+        out.push({ kind: 'page-setup' });
+    if (entry.objects !== undefined)
+        out.push({ kind: 'objects' });
+    if (entry.sparklines !== undefined)
+        out.push({ kind: 'sparklines' });
+    if (entry.pivots !== undefined)
+        out.push({ kind: 'pivots' });
+    if (entry.links !== undefined)
+        out.push({ kind: 'links' });
+    if (entry.merges !== undefined)
+        out.push({ kind: 'merges' });
+    if (entry.validation !== undefined)
+        out.push({ kind: 'validation' });
+    if (entry.conditionalFormats !== undefined)
+        out.push({ kind: 'conditional-formats' });
+    if (entry.autoFilter !== undefined)
+        out.push({ kind: 'filter' });
+    return out;
+}
+function emptySheetState() {
+    return {
+        formats: createFormatStore(),
+        widths: {},
+        heights: new Map(),
+        hidden: { rows: new Set(), cols: new Set() },
+        outline: { rows: emptyOutline(), cols: emptyOutline() },
+        freeze: { rows: 0, cols: 0 },
+        notes: {},
+        protected: false,
+        protection: defaultProtection(),
+        pageSetup: defaultPageSetup(),
+        objects: [],
+        sparklines: [],
+        pivots: [],
+        links: {},
+        sheetHidden: false,
+        kind: 'cells',
+        merges: [],
+        validation: [],
+        conditionalFormats: [],
+        cellTypes: [],
+        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: [] }]), {
+            ...(init.state?.workbook.tables?.length ? { tables: init.state.workbook.tables } : {}),
+            ...(init.state?.workbook.iteration ? { iteration: init.state.workbook.iteration } : {}),
+        });
+    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);
+    }
+    /** A row of comments copied deep enough that a saved thread is not the live one. */
+    function copyLine(line) {
+        const out = {};
+        for (const [c, v] of Object.entries(line))
+            out[c] = typeof v === 'string' ? v : { ...v, ...(v.replies ? { replies: v.replies.map((r) => ({ ...r })) } : {}) };
+        return out;
+    }
+    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] },
+            outline: { rows: copyOutline(state.outline.rows), cols: copyOutline(state.outline.cols) },
+            freeze: { ...state.freeze },
+            comments: Object.fromEntries(Object.entries(state.notes).map(([r, line]) => [r, copyLine(line)])),
+            protected: state.protected,
+            protection: copyProtection(state.protection),
+            pageSetup: copyPageSetup(state.pageSetup),
+            objects: state.objects.map(copyObject),
+            sparklines: state.sparklines.map(copySparkline),
+            pivots: state.pivots.map(copyPivot),
+            links: copyLinks(state.links),
+            sheetHidden: state.sheetHidden,
+            kind: state.kind,
+            ...(state.grid ? { grid: copyGridSheet(state.grid) } : {}),
+            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]) })),
+            cellTypes: state.cellTypes.map(copyCellType),
+            autoFilter: state.autoFilter ? { range: [...state.autoFilter.range], filters: { ...state.autoFilter.filters } } : null,
+        };
+    }
+    /**
+     * Put back only the parts an entry names, leaving the rest as they are.
+     * `hydrateEntry` below is the whole-sheet version, which resets what is
+     * absent to its default; this one is what a delta applies, since a delta
+     * carries the one feature that changed.
+     */
+    function patchEntry(state, entry) {
+        if (entry.formats !== undefined)
+            state.formats.hydrate(entry.formats);
+        if (entry.columnWidths !== undefined)
+            state.widths = { ...entry.columnWidths };
+        if (entry.rowHeights !== undefined)
+            state.heights = new Map(entry.rowHeights);
+        if (entry.hidden !== undefined)
+            state.hidden = { rows: new Set(entry.hidden.rows ?? []), cols: new Set(entry.hidden.cols ?? []) };
+        if (entry.outline !== undefined)
+            state.outline = { rows: copyOutline(entry.outline.rows), cols: copyOutline(entry.outline.cols) };
+        if (entry.freeze !== undefined)
+            state.freeze = { rows: entry.freeze.rows ?? 0, cols: entry.freeze.cols ?? 0 };
+        if (entry.comments !== undefined)
+            state.notes = Object.fromEntries(Object.entries(entry.comments).map(([r, line]) => [r, copyLine(line)]));
+        if (entry.protected !== undefined)
+            state.protected = entry.protected;
+        if (entry.protection !== undefined)
+            state.protection = copyProtection({ allow: entry.protection.allow ?? {}, ranges: entry.protection.ranges ?? [] });
+        if (entry.pageSetup !== undefined)
+            state.pageSetup = copyPageSetup({ ...defaultPageSetup(), ...entry.pageSetup });
+        if (entry.objects !== undefined)
+            state.objects = entry.objects.map(copyObject);
+        if (entry.sparklines !== undefined)
+            state.sparklines = entry.sparklines.map(copySparkline);
+        if (entry.pivots !== undefined)
+            state.pivots = entry.pivots.map(copyPivot);
+        if (entry.links !== undefined)
+            state.links = copyLinks(entry.links);
+        if (entry.sheetHidden !== undefined)
+            state.sheetHidden = entry.sheetHidden;
+        if (entry.kind !== undefined)
+            state.kind = entry.kind;
+        if (entry.grid !== undefined)
+            state.grid = copyGridSheet(entry.grid);
+        if (entry.merges !== undefined)
+            state.merges = entry.merges.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]);
+        if (entry.validation !== undefined) {
+            state.validation = entry.validation.map((rule) => ({
+                ...rule,
+                rects: rule.rects.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]),
+                alert: { ...rule.alert },
+            }));
+        }
+        if (entry.conditionalFormats !== undefined) {
+            state.conditionalFormats = entry.conditionalFormats.map((rule) => ({
+                ...rule,
+                rects: rule.rects.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]),
+            }));
+        }
+        if (entry.cellTypes !== undefined)
+            state.cellTypes = entry.cellTypes.map(copyCellType);
+        if (entry.autoFilter !== undefined) {
+            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();
+        }
+    }
+    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.outline = { rows: copyOutline(entry.outline?.rows), cols: copyOutline(entry.outline?.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, copyLine(line)]));
+        state.protected = entry.protected ?? false;
+        state.protection = entry.protection ? copyProtection({ allow: entry.protection.allow ?? {}, ranges: entry.protection.ranges ?? [] }) : defaultProtection();
+        state.pageSetup = entry.pageSetup ? copyPageSetup({ ...defaultPageSetup(), ...entry.pageSetup }) : defaultPageSetup();
+        state.objects = (entry.objects ?? []).map(copyObject);
+        state.sparklines = (entry.sparklines ?? []).map(copySparkline);
+        state.pivots = (entry.pivots ?? []).map(copyPivot);
+        state.links = copyLinks(entry.links ?? {});
+        state.sheetHidden = entry.sheetHidden ?? false;
+        state.kind = entry.kind ?? 'cells';
+        state.grid = entry.grid ? copyGridSheet(entry.grid) : undefined;
+        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]),
+        }));
+        state.cellTypes = (entry.cellTypes ?? []).map(copyCellType);
+        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,
+        patch(name, entry) {
+            patchEntry(get(name), entry);
+            for (const reason of reasonsForEntry(entry))
+                changed(reason);
+        },
+        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));
+        },
+        duplicate(from, to) {
+            const made = workbook.copySheet(from, to);
+            if (made === null)
+                return null;
+            // Through the JSON shape, so nothing is shared between the two.
+            const copy = JSON.parse(JSON.stringify(serializeEntry(get(from))));
+            copy.sheetHidden = false;
+            // The copy's chart, picture, sparkline and pivot are its own, so they
+            // get their own ids the way Excel's Move or Copy does. Sharing them
+            // would mean a shell that tracks the selected object by id following
+            // the copy's one across a sheet switch, and deleting it there.
+            copy.objects = copy.objects?.map((object) => ({ ...object, id: objectId() }));
+            copy.sparklines = copy.sparklines?.map((group) => ({ ...group, id: sparklineId() }));
+            copy.pivots = copy.pivots?.map((pivot) => ({ ...pivot, id: pivotId() }));
+            hydrateEntry(get(made), copy);
+            changed({ kind: 'sheets' });
+            return made;
+        },
+        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.outline = { rows: state.outline.rows, cols: shiftOutline(state.outline.cols, edit.at, edit.count * (edit.kind === 'deleteCols' ? -1 : 1)) };
+                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.cellTypes = shiftCellTypes(state.cellTypes, edit);
+            state.autoFilter = shiftAutoFilter(state.autoFilter, edit);
+            state.pageSetup = shiftPageSetup(state.pageSetup, edit);
+            state.objects = shiftObjects(state.objects, edit);
+            state.sparklines = shiftSparklines(state.sparklines, edit);
+            state.pivots = shiftPivots(state.pivots, edit);
+            state.links = shiftLinks(state.links, edit);
+            state.protection = {
+                allow: state.protection.allow,
+                ranges: state.protection.ranges
+                    .map((range) => ({ ...range, rects: range.rects.map((r) => shiftRect(r, edit)).filter((r) => r !== null) }))
+                    .filter((range) => range.rects.length > 0),
+            };
+        },
+        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 ?? {});
+                // Tables are workbook-wide, and the registry is what a structured
+                // reference resolves through: put back exactly the saved set.
+                workbook.tables.clear();
+                for (const table of state.workbook.tables ?? [])
+                    workbook.tables.define({ ...table });
+                // Iterative calculation is workbook-wide too, and absent in a saved
+                // document that never turned it on, which means off.
+                workbook.setIteration(state.workbook.iteration ?? { enabled: false });
+                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] ?? {});
+                for (const name of workbook.sheets)
+                    releaseFilteredRows(document, 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);
+            for (const name of workbook.sheets)
+                releaseFilteredRows(document, name);
+        });
+    }
+    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/engine.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The seam between the workbook and whatever works a formula out.
+ *
+ * The built-in engine (the tokenizer, parser and evaluator beside this
+ * file) is the one the sheet ships with and the one it is tested against.
+ * The seam is here for an application that has its own evaluator to put
+ * behind the same sheet: `createWorkbook(sheets, { engine: mine })`.
+ *
+ * What an engine is asked for is narrow on purpose: a formula's value in
+ * a cell, and the grid it spills when it has one. The workbook keeps
+ * everything else, because none of it is the engine's to decide. The
+ * dependency graph, the volatile set, the value cache, cycle detection
+ * and the spill ranges are all read off the reference grammar, which is
+ * Excel's whatever evaluates it, so they stay correct for any engine and
+ * an engine cannot get them wrong.
+ *
+ * `load` and `write` are the lifecycle an engine with a copy of the cells
+ * needs: `load` when the workbook is built and whenever its cells change
+ * wholesale (a structural edit, a sheet added or renamed, a restore),
+ * `write` on a single cell. An engine that reads through `host` on demand,
+ * as the built-in does, leaves both off.
+ */
+import type { CellValue, Node } from './ast.js';
+import type { EvalContext } from './evaluate.js';
+import type { SheetData } from './workbook.js';
+/** Where a formula sits. */
+export type SheetEngineCell = {
+    sheet: string;
+    row: number;
+    col: number;
+};
+export type SheetEngineHost = {
+    /**
+     * The context the built-in evaluator uses for this cell: `resolve` reads
+     * through the workbook's cache and cycle detection, so an engine that
+     * wants a precedent's value asks here rather than reading raw text.
+     */
+    context: EvalContext;
+    /** The workbook's parse cache: one parse per distinct formula text, null when it does not parse. */
+    parse(text: string): Node | null;
+};
+export type SheetEngineResult = {
+    value: CellValue;
+    /**
+     * The grid the formula spills, or null / absent for a plain value. The
+     * workbook lays it over the cells below and to the right, refuses it
+     * with `#SPILL!` where something is in the way, and moves it with an
+     * insert or delete.
+     */
+    spill?: CellValue[][] | null;
+};
+export type SheetEngine = {
+    /** For the docs and an error message; the built-in is `'builtin'`. */
+    name?: string;
+    /** Every sheet's raw text, at creation and after a wholesale change. */
+    load?(sheets: ReadonlyArray<SheetData>): void;
+    /** One cell's raw text changed. */
+    write?(sheet: string, row: number, col: number, text: string): void;
+    /** What the formula is worth here. `text` keeps its leading `=`. */
+    evaluate(text: string, at: SheetEngineCell, host: SheetEngineHost): SheetEngineResult;
+};
+/**
+ * The engine the sheet ships with: the parser and evaluator in this
+ * folder, which read the workbook's own cells through the host's context
+ * and so need no copy of anything.
+ */
+export declare function builtinEngine(): SheetEngine;

package/dist/sheet/engine.js

@@ -0,0 +1,19 @@
+import { evaluate, evaluateSpill } from './evaluate.js';
+/**
+ * The engine the sheet ships with: the parser and evaluator in this
+ * folder, which read the workbook's own cells through the host's context
+ * and so need no copy of anything.
+ */
+export function builtinEngine() {
+    return {
+        name: 'builtin',
+        evaluate(text, _at, host) {
+            const ast = host.parse(text);
+            if (!ast)
+                return { value: { error: '#PARSE!' } };
+            const value = evaluate(ast, host.context);
+            const spill = typeof value === 'object' && value !== null && 'error' in value ? null : evaluateSpill(ast, host.context);
+            return { value, spill };
+        },
+    };
+}

package/dist/sheet/entry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { type SheetCulture } from './culture.js';
+export type ParsedEntry = {
+    /** The number, as text the workbook stores. */
+    value: 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.
+ *
+ * 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, culture?: SheetCulture): ParsedEntry | null;