@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/deps.js

@@ -0,0 +1,274 @@
+/**
+ * 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, 
+/**
+ * The rectangle behind a structured reference (`Orders[Amount]`,
+ * `[@Qty]`). Without it a formula over a table records no precedents, so
+ * editing a cell in the table leaves every total reading it stale until
+ * something forces a full recalculation.
+ */
+resolveTable, 
+/**
+ * The rectangle a spilled-range operator (`A1#`) currently covers. The
+ * anchor cell is always recorded regardless, so a formula reading `A1#`
+ * recalculates whenever the array is re-typed and picks up the new extent;
+ * the covered cells are added on top so a change anywhere in the spill
+ * reaches it too.
+ */
+resolveSpill, 
+/** The sheets a 3D reference spans, so it recalculates when the cell on any
+ *  of them changes. */
+resolveSheets, 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, resolveTable, resolveSpill, resolveSheets, depth + 1));
+            return;
+        }
+        if (n.k === 'ref3d') {
+            const sheets = resolveSheets?.(n.sheetFrom, n.sheetTo);
+            if (!sheets)
+                return;
+            const r1 = Math.min(n.from.row ?? 0, n.to.row ?? 0);
+            const r2 = Math.max(n.from.row ?? 0, n.to.row ?? 0);
+            const c1 = Math.min(n.from.col, n.to.col);
+            const c2 = Math.max(n.from.col, n.to.col);
+            for (const s of sheets) {
+                for (let r = r1; r <= r2; r += 1) {
+                    for (let c = c1; c <= c2; c += 1)
+                        out.push(cellKey(s, r, c));
+                }
+            }
+            return;
+        }
+        if (n.k === 'spill') {
+            // The anchor always: retyping the array changes the anchor cell, so
+            // this makes the reader recalculate and re-derive the extent below.
+            out.push(cellKey(n.ref.sheet ?? self.sheet, n.ref.row ?? 0, n.ref.col));
+            const rect = resolveSpill?.(n);
+            if (rect) {
+                for (let r = rect.r1; r <= rect.r2; r += 1) {
+                    for (let c = rect.c1; c <= rect.c2; c += 1)
+                        out.push(cellKey(rect.sheet ?? self.sheet, r, c));
+                }
+            }
+            return;
+        }
+        if (n.k === 'table') {
+            const rect = resolveTable?.(n);
+            if (!rect)
+                return;
+            for (let r = rect.firstRow; r <= rect.lastRow; r += 1) {
+                for (let c = rect.firstCol; c <= rect.lastCol; c += 1)
+                    out.push(cellKey(rect.sheet, r, c));
+            }
+            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;
+}
+/**
+ * Functions whose result can change without any precedent changing: a
+ * reference built from text, a range built from arithmetic, the clock, a
+ * random number. A cell holding one is recomputed on every edit, as Excel
+ * recomputes its volatile cells, rather than trusting the graph.
+ */
+export const VOLATILE_FUNCTIONS = new Set(['INDIRECT', 'OFFSET', 'RAND', 'RANDBETWEEN', 'NOW', 'TODAY']);
+export function isVolatile(ast) {
+    let found = false;
+    visit(ast, (n) => {
+        if (n.k === 'fn' && VOLATILE_FUNCTIONS.has(n.name))
+            found = true;
+    });
+    return found;
+}
+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;
+        },
+        precedentsOf(cell) {
+            return [...(precedents.get(cell) ?? [])];
+        },
+        dependentsOf(cell) {
+            return [...(dependents.get(cell) ?? [])];
+        },
+        clear() {
+            precedents.clear();
+            dependents.clear();
+        },
+    };
+}

package/dist/sheet/document.d.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 Rect } from './rects.js';
+import type { CommentsMap } from './comments.js';
+import { type SheetProtection } from './protection.js';
+import { type PageSetup } from './page-setup.js';
+import { type SheetObject } from './objects.js';
+import { type SparklineGroup } from './sparklines.js';
+import { type SheetPivot } from './pivot-range.js';
+import { type LinksMap } from './links.js';
+import { type ValidationRule } from './validation.js';
+import { type CfRule } from './conditional-formats.js';
+import { type AutoFilterState } from './auto-filter.js';
+import { type CellTypeRegion } from './cell-types.js';
+import { type GridSheetSpec, type SheetKind } from './sheet-kinds.js';
+import { type OutlineState } from './outline.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: 'page-setup';
+} | {
+    kind: 'objects';
+} | {
+    kind: 'sparklines';
+} | {
+    kind: 'pivots';
+} | {
+    kind: 'links';
+} | {
+    kind: 'tables';
+}
+/**
+ * The workbook's own parts rather than a sheet's: its defined names and
+ * its calculation settings. They belong to no sheet, so nothing keyed by
+ * sheet can carry them, and a listener that mirrors a document elsewhere
+ * has to hear about them separately.
+ */
+ | {
+    kind: 'workbook';
+} | {
+    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>;
+    };
+    /** Data > Group: the outline level of each row and column, and which
+     *  summary lines are collapsed. Lines a collapsed group hides are kept
+     *  apart from `hidden`, so expanding a group does not un-hide a row the
+     *  user hid by hand. */
+    outline: {
+        rows: OutlineState;
+        cols: OutlineState;
+    };
+    freeze: FreezeState;
+    /** Cell comments keyed like the grid's `notes`: `r4` -> `B` -> a note's text or a thread. */
+    notes: CommentsMap;
+    protected: boolean;
+    /** What stays allowed while protected, and the ranges that take an edit anyway. */
+    protection: SheetProtection;
+    /** Page Layout: orientation, paper, margins, print area, title rows, gridlines, headings, scale. */
+    pageSetup: PageSetup;
+    /** Charts and pictures anchored over the cells, back to front. */
+    objects: SheetObject[];
+    sparklines: SparklineGroup[];
+    pivots: SheetPivot[];
+    /** Hyperlinks by cell, keyed like the comments: `r4` -> `B` -> the link. */
+    links: LinksMap;
+    /** Excel's Hide Sheet: the tab is not shown and the shortcuts skip it. */
+    sheetHidden: boolean;
+    /**
+     * What this tab is: a cell grid, or a table bound to records.
+     *
+     * A `grid` sheet keeps its records in `grid` and projects them into the
+     * workbook's cells, so a formula on any other sheet reads it the way it
+     * reads a cell sheet. See `sheet-kinds.ts`.
+     */
+    kind: SheetKind;
+    /** The records and columns of a `grid` sheet; absent on a cell sheet. */
+    grid?: GridSheetSpec;
+    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[];
+    /** Cells drawn as a control rather than as text: a checkbox, a button,
+     *  a radio group. The cell's value stays the truth. */
+    cellTypes: CellTypeRegion[];
+    /** 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[];
+    };
+    /** Absent in documents saved before outlining existed. */
+    outline?: {
+        rows: OutlineState;
+        cols: OutlineState;
+    };
+    freeze: FreezeState;
+    /** `r4` -> `B` -> a note's text, or a thread with its author, replies and state. */
+    comments: CommentsMap;
+    protected: boolean;
+    /** Absent in documents saved before the allow list and edit ranges existed. */
+    protection?: SheetProtection;
+    /** Absent in documents saved before Page Layout existed. */
+    pageSetup?: PageSetup;
+    /** Absent in documents saved before objects existed. */
+    objects?: SheetObject[];
+    /** Absent in documents saved before sparklines existed. */
+    sparklines?: SparklineGroup[];
+    /** Absent in documents saved before pivots existed. */
+    pivots?: SheetPivot[];
+    /** Absent in documents saved before hyperlinks existed. */
+    links?: LinksMap;
+    /** Absent in documents saved before hidden sheets existed. */
+    sheetHidden?: boolean;
+    /** Absent in documents saved before sheet kinds existed; reads as 'cells'. */
+    kind?: SheetKind;
+    grid?: GridSheetSpec;
+    merges: Array<[number, number, number, number]>;
+    validation: ValidationRule[];
+    conditionalFormats: CfRule[];
+    /** Absent in documents saved before cell types existed. */
+    cellTypes?: CellTypeRegion[];
+    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;
+    /**
+     * Excel's Move or Copy > Create a copy: a new sheet after `from` with
+     * its cells and everything this document keeps beside them, named `to`
+     * or "Name (2)". Returns the new name, or null when it could not.
+     */
+    duplicate(from: string, to?: string): string | null;
+    /** 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;
+    /**
+     * Put back only the parts `entry` names, leaving the rest of the sheet as
+     * it is: what a delta from another user applies, and what a host that
+     * wants to set one feature calls. Reports the change, so the shell
+     * repaints; wrap it in `mute` where it should not.
+     */
+    patch(name: string, entry: Partial<SheetStateEntry>): 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;