@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/deps.js

@@ -0,0 +1,199 @@
+/**
+ * Dependency graph, so a recalc costs what the edit actually affects.
+ *
+ * The demo engines call `computeSheet`, which resolves every cell on every
+ * keystroke. On a small budget sheet nobody notices; on demo 211's 360-row
+ * amortisation schedule, typing one digit in an input cell walks every cell in
+ * the sheet and re-parses every formula among them.
+ *
+ * This tracks which cells each formula reads, inverts that into "who reads
+ * me", and walks forward from an edit in topological order.
+ *
+ * Cycles are reported rather than thrown. A cycle is a normal thing to type on
+ * the way to something correct, and every cell in one shows #CYCLE! while the
+ * rest of the sheet keeps working.
+ */
+import { visit } from './ast.js';
+/**
+ * Cells are keyed "row col sheet", in that order deliberately.
+ *
+ * Row and column are numbers and contain no separator, so the first two fields
+ * are unambiguous and EVERYTHING after the second space is the sheet name.
+ * Putting the sheet first would let a name like `Price list` collide with a
+ * different cell, and a ':' or '!' separator has the same problem the moment
+ * someone names a sheet after a range.
+ */
+export function cellKey(sheet, row, col) {
+    return `${row} ${col} ${sheet ?? ''}`;
+}
+export function parseCellKey(key) {
+    const firstGap = key.indexOf(' ');
+    const secondGap = key.indexOf(' ', firstGap + 1);
+    const sheet = key.slice(secondGap + 1);
+    return {
+        sheet: sheet === '' ? null : sheet,
+        row: Number(key.slice(0, firstGap)),
+        col: Number(key.slice(firstGap + 1, secondGap)),
+    };
+}
+/**
+ * Every cell a formula reads. A range contributes each cell inside it, which
+ * is why `lastRow` is needed: a whole-column reference has no upper bound of
+ * its own.
+ */
+export function precedentsOf(ast, self, lastRow, 
+/**
+ * The reference behind a defined name. Without it a formula that reads
+ * `=Subtotal*Tax` records no precedents at all, so editing the cell behind
+ * `Tax` leaves the formula showing its old value until something else
+ * forces a recalculation.
+ */
+resolveName, depth = 0) {
+    const out = [];
+    visit(ast, (n) => {
+        if (n.k === 'name') {
+            // A name defined as another name is followed; a circular chain is cut
+            // after a few hops rather than recursing forever.
+            const target = depth < 8 ? resolveName?.(n.name) : null;
+            if (target)
+                out.push(...precedentsOf(target, self, lastRow, resolveName, depth + 1));
+            return;
+        }
+        if (n.k === 'ref' && n.ref.row !== null) {
+            out.push(cellKey(n.ref.sheet ?? self.sheet, n.ref.row, n.ref.col));
+            return;
+        }
+        if (n.k === 'range') {
+            const sheet = n.from.sheet ?? n.to.sheet ?? self.sheet;
+            const r1 = Math.min(n.from.row ?? 0, n.to.row ?? n.from.row ?? 0);
+            const r2 = n.to.row === null || n.from.row === null
+                ? lastRow(sheet)
+                : Math.max(n.from.row, n.to.row);
+            const c1 = Math.min(n.from.col, n.to.col);
+            const c2 = Math.max(n.from.col, n.to.col);
+            for (let r = r1; r <= r2; r += 1) {
+                for (let c = c1; c <= c2; c += 1)
+                    out.push(cellKey(sheet, r, c));
+            }
+        }
+    });
+    return out;
+}
+export function createDependencyGraph() {
+    /** cell -> what it reads. */
+    const precedents = new Map();
+    /** cell -> who reads it. The index that makes dirtyFrom cheap. */
+    const dependents = new Map();
+    function unlink(cell) {
+        const old = precedents.get(cell);
+        if (!old)
+            return;
+        for (const p of old) {
+            const set = dependents.get(p);
+            if (!set)
+                continue;
+            set.delete(cell);
+            if (set.size === 0)
+                dependents.delete(p);
+        }
+        precedents.delete(cell);
+    }
+    return {
+        setPrecedents(cell, next) {
+            unlink(cell);
+            if (!next || next.length === 0)
+                return;
+            // A self-reference is a cycle of one; it is kept so `cycles()` sees it.
+            const set = new Set(next);
+            precedents.set(cell, set);
+            for (const p of set) {
+                let back = dependents.get(p);
+                if (!back) {
+                    back = new Set();
+                    dependents.set(p, back);
+                }
+                back.add(cell);
+            }
+        },
+        dirtyFrom(changed) {
+            // Collect everything reachable downstream, then order it so a cell only
+            // recomputes once its own inputs have. Kahn's algorithm over that
+            // subgraph, not over the whole sheet.
+            const affected = new Set();
+            const stack = [...changed];
+            while (stack.length) {
+                const cur = stack.pop();
+                for (const d of dependents.get(cur) ?? []) {
+                    if (affected.has(d))
+                        continue;
+                    affected.add(d);
+                    stack.push(d);
+                }
+            }
+            if (affected.size === 0)
+                return [];
+            const indegree = new Map();
+            for (const cell of affected) {
+                let n = 0;
+                for (const p of precedents.get(cell) ?? [])
+                    if (affected.has(p))
+                        n += 1;
+                indegree.set(cell, n);
+            }
+            const ready = [...affected].filter((c) => (indegree.get(c) ?? 0) === 0);
+            const order = [];
+            const placed = new Set();
+            while (ready.length) {
+                const cur = ready.shift();
+                order.push(cur);
+                placed.add(cur);
+                for (const d of dependents.get(cur) ?? []) {
+                    if (!affected.has(d))
+                        continue;
+                    const n = (indegree.get(d) ?? 0) - 1;
+                    indegree.set(d, n);
+                    if (n === 0)
+                        ready.push(d);
+                }
+            }
+            // Anything left never reached indegree zero, so it sits in a cycle.
+            // Append it rather than dropping it: those cells still need evaluating
+            // so they can report #CYCLE! instead of keeping a stale value.
+            for (const cell of affected)
+                if (!placed.has(cell))
+                    order.push(cell);
+            return order;
+        },
+        cycles() {
+            // A cell is in a cycle when it can reach itself through its precedents.
+            const out = [];
+            for (const start of precedents.keys()) {
+                const seen = new Set();
+                const stack = [...(precedents.get(start) ?? [])];
+                let found = false;
+                while (stack.length) {
+                    const cur = stack.pop();
+                    if (cur === start) {
+                        found = true;
+                        break;
+                    }
+                    if (seen.has(cur))
+                        continue;
+                    seen.add(cur);
+                    for (const p of precedents.get(cur) ?? [])
+                        stack.push(p);
+                }
+                if (found)
+                    out.push(start);
+            }
+            return out;
+        },
+        dependentsOf(cell) {
+            return [...(dependents.get(cell) ?? [])];
+        },
+        clear() {
+            precedents.clear();
+            dependents.clear();
+        },
+    };
+}

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;
+}