@svgrid/enterprise 3.0.1 → 3.0.2

package/dist/sheet/structure.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Insert and delete rows and columns, with every formula on the sheet
+ * rewritten to follow.
+ *
+ * The api half already existed (`addRow`, `removeRow`, `addColumn`,
+ * `removeColumn`). What was missing is the fixup pass: inserting a row above
+ * `=SUM(D2:D11)` without widening the range silently produces the wrong total,
+ * and deleting a referenced row leaves a formula pointing at whatever moved
+ * into its place. Neither shows an error. That is why this waited for the
+ * engine rather than shipping with the other shortcuts.
+ *
+ * A structural edit is three things in order:
+ *   1. rewrite every formula in the sheet, and every defined name
+ *   2. drop format entries for whatever the edit deletes
+ *   3. apply the structural change itself
+ *
+ * Order matters: the first two read the OLD geometry.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+import { type StructuralEdit } from './refs.js';
+import type { SheetNames } from './names.js';
+import type { SheetFormatStore, CellAddressLookup } from './format-store.js';
+/** What a structural command needs beyond the command context. */
+export type StructureTarget = {
+    /** Rewrite one cell's raw text. Called only for cells that changed. */
+    setRaw(rowIndex: number, colIndex: number, text: string): void;
+    /** Read one cell's raw text, formula included. */
+    getRaw(rowIndex: number, colIndex: number): string;
+    /** Apply the structural change to the data itself. */
+    apply(edit: StructuralEdit): void;
+    /**
+     * Set when `apply` rewrites the references itself. A Workbook does, across
+     * every sheet, which is the whole reason a shell routes the edit through
+     * it; rewriting here as well then moved every reference twice, so one
+     * inserted row turned =SUM(A1:A3) into =SUM(A1:A5) and a cycle.
+     */
+    rewritesReferences?: boolean;
+    names?: SheetNames;
+    format?: {
+        store: SheetFormatStore;
+        lookup: CellAddressLookup;
+    };
+    onChange?(): void;
+    /**
+     * Everything a structural edit can touch, as one value, and the way to
+     * put it back. Supplying both makes insert and delete ONE Ctrl+Z: the
+     * command records the state before and after and hands the grid a step
+     * that restores either. Without them the formula rewrites inside the
+     * edit would sit in the history on their own, and undoing those while
+     * the rows stayed inserted would leave the sheet inconsistent.
+     */
+    snapshot?(): unknown;
+    restore?(state: unknown): void;
+    /**
+     * Whether the edit may happen at all. A protected sheet says no to every
+     * insert and delete, as Excel's does; the ribbon greys Insert and Delete
+     * on the same answer, so it must be cheap and must not talk to the user.
+     */
+    canApply?(edit: StructuralEdit): boolean;
+    /** Called when `canApply` refused an edit: the place to say why. */
+    refused?(): void;
+};
+/** Attach what the insert / delete commands operate on. */
+export declare function setStructureTarget(next: StructureTarget | null): void;
+export declare function getStructureTarget(): StructureTarget | null;
+/**
+ * Rewrite every formula on the sheet for one structural edit.
+ *
+ * Walks the whole grid rather than consulting the dependency graph, because
+ * the graph indexes what a formula READS and this needs every formula that
+ * MENTIONS a moved coordinate, including ones whose precedents were never
+ * resolved (a `#REF!` today may become valid after an insert).
+ */
+export declare function rewriteFormulas(cmd: GridCommandContext, t: StructureTarget, edit: StructuralEdit): number;
+export declare function insertRows(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function deleteRows(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function insertColumns(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function deleteColumns(cmd: GridCommandContext, at?: number, count?: number): boolean;
+/**
+ * Which axis a bare Ctrl+Plus / Ctrl+Minus acts on.
+ *
+ * Excel opens a dialog when the selection is not a whole row or column. That
+ * dialog is a design decision, so this reports what it would ask about and
+ * lets the consumer decide: a selection spanning every column is a row
+ * operation, every row is a column operation, anything else is ambiguous.
+ */
+export declare function axisForSelection(cmd: GridCommandContext): 'rows' | 'cols' | 'ambiguous';

package/dist/sheet/structure.js

@@ -0,0 +1,166 @@
+import { fixupReferences } from './refs.js';
+let target = null;
+/** Attach what the insert / delete commands operate on. */
+export function setStructureTarget(next) {
+    target = next;
+}
+export function getStructureTarget() {
+    return target;
+}
+/**
+ * Rewrite every formula on the sheet for one structural edit.
+ *
+ * Walks the whole grid rather than consulting the dependency graph, because
+ * the graph indexes what a formula READS and this needs every formula that
+ * MENTIONS a moved coordinate, including ones whose precedents were never
+ * resolved (a `#REF!` today may become valid after an insert).
+ */
+export function rewriteFormulas(cmd, t, edit) {
+    let changed = 0;
+    for (let r = 0; r < cmd.rowCount; r += 1) {
+        for (let c = 0; c < cmd.colCount; c += 1) {
+            const text = t.getRaw(r, c);
+            if (!text.startsWith('='))
+                continue;
+            const next = fixupReferences(text, edit);
+            if (typeof next === 'string' && next !== text) {
+                t.setRaw(r, c, next);
+                changed += 1;
+            }
+        }
+    }
+    if (t.names) {
+        for (const entry of t.names.list()) {
+            const next = fixupReferences(entry.refersTo, edit);
+            if (typeof next === 'string' && next !== entry.refersTo) {
+                t.names.define(entry.name, next);
+                changed += 1;
+            }
+        }
+    }
+    return changed;
+}
+/**
+ * Drop format entries for rows or columns the edit removes.
+ *
+ * Nothing needs SHIFTING. The store keys on row and column IDS, and an id
+ * travels with the thing it names: inserting a column at B does not rename
+ * what was B, it just puts a new id before it, so every existing entry still
+ * points at the right cell. That is the payoff for keying on ids instead of
+ * indices, and it is the same property that makes the store survive a sort.
+ *
+ * A DELETE is different: those ids are gone, and their entries would sit in
+ * the map for the life of the session. Hence this.
+ */
+function forgetDeleted(t, edit, cmd) {
+    const format = t.format;
+    if (!format)
+        return;
+    const rows = edit.kind === 'deleteRows';
+    const cols = edit.kind === 'deleteCols';
+    if (!rows && !cols)
+        return;
+    const limit = rows ? cmd.rowCount : cmd.colCount;
+    for (let i = edit.at; i < Math.min(edit.at + edit.count, limit); i += 1) {
+        const id = rows ? format.lookup.rowIdAt(i) : format.lookup.columnIdAt(i);
+        if (id === null)
+            continue;
+        if (rows)
+            format.store.forgetRow(id);
+        else
+            format.store.forgetColumn(id);
+    }
+}
+function run(cmd, edit) {
+    const t = target;
+    if (!t)
+        return false;
+    if (edit.count <= 0)
+        return false;
+    if (t.canApply?.(edit) === false) {
+        t.refused?.();
+        return false;
+    }
+    return cmd.batch(() => {
+        const before = t.snapshot?.();
+        // Order matters: the rewrite and the cleanup both read the OLD geometry.
+        if (!t.rewritesReferences)
+            rewriteFormulas(cmd, t, edit);
+        forgetDeleted(t, edit, cmd);
+        t.apply(edit);
+        t.onChange?.();
+        // Recorded LAST, so undo runs it first: the whole state comes back, and
+        // the rewrite steps recorded above then re-apply their own "before"
+        // texts, which the snapshot already holds. Redo runs them the other way
+        // round to the same end.
+        const restore = t.restore;
+        if (before !== undefined && restore) {
+            const after = t.snapshot?.();
+            cmd.recordUndo?.(() => { restore(before); t.onChange?.(); }, () => { restore(after); t.onChange?.(); });
+        }
+        return true;
+    });
+}
+/** The span the active selection covers, as whole rows or whole columns. */
+function spanOf(cmd, axis) {
+    const rect = cmd.ranges[cmd.ranges.length - 1];
+    if (rect) {
+        const [minRow, minCol, maxRow, maxCol] = rect;
+        return axis === 'rows'
+            ? { at: minRow, count: maxRow - minRow + 1 }
+            : { at: minCol, count: maxCol - minCol + 1 };
+    }
+    const active = cmd.activeCell;
+    if (!active)
+        return null;
+    return axis === 'rows'
+        ? { at: active.rowIndex, count: 1 }
+        : { at: active.colIndex, count: 1 };
+}
+export function insertRows(cmd, at, count = 1) {
+    const span = at === undefined ? spanOf(cmd, 'rows') : { at, count };
+    if (!span)
+        return false;
+    return run(cmd, { kind: 'insertRows', at: span.at, count: span.count });
+}
+export function deleteRows(cmd, at, count = 1) {
+    const span = at === undefined ? spanOf(cmd, 'rows') : { at, count };
+    if (!span)
+        return false;
+    return run(cmd, { kind: 'deleteRows', at: span.at, count: span.count });
+}
+export function insertColumns(cmd, at, count = 1) {
+    const span = at === undefined ? spanOf(cmd, 'cols') : { at, count };
+    if (!span)
+        return false;
+    return run(cmd, { kind: 'insertCols', at: span.at, count: span.count });
+}
+export function deleteColumns(cmd, at, count = 1) {
+    const span = at === undefined ? spanOf(cmd, 'cols') : { at, count };
+    if (!span)
+        return false;
+    return run(cmd, { kind: 'deleteCols', at: span.at, count: span.count });
+}
+/**
+ * Which axis a bare Ctrl+Plus / Ctrl+Minus acts on.
+ *
+ * Excel opens a dialog when the selection is not a whole row or column. That
+ * dialog is a design decision, so this reports what it would ask about and
+ * lets the consumer decide: a selection spanning every column is a row
+ * operation, every row is a column operation, anything else is ambiguous.
+ */
+export function axisForSelection(cmd) {
+    const rect = cmd.ranges[cmd.ranges.length - 1];
+    if (!rect)
+        return 'rows';
+    const [minRow, minCol, maxRow, maxCol] = rect;
+    const spansAllCols = minCol === 0 && maxCol >= cmd.colCount - 1;
+    const spansAllRows = minRow === 0 && maxRow >= cmd.rowCount - 1;
+    if (spansAllCols && !spansAllRows)
+        return 'rows';
+    if (spansAllRows && !spansAllCols)
+        return 'cols';
+    if (spansAllCols && spansAllRows)
+        return 'rows';
+    return 'ambiguous';
+}

package/dist/sheet/tables.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tables: a named region with a header row, so a formula can say
+ * `Orders[Amount]` instead of `D2:D57` and keep meaning it after rows are
+ * added.
+ *
+ * The point is not shorter text. A1 references are positional, so a total
+ * under a table has to be re-pointed every time the table grows, and a
+ * reference typed against 57 rows silently stops covering row 58. A
+ * structured reference names the COLUMN, and the range it resolves to is
+ * whatever the table currently is.
+ *
+ * This module is the model; the grammar that reads `Orders[Amount]` lives in
+ * the tokenizer, and resolving one to a range happens at evaluation, because
+ * the range depends on the table's size at that moment rather than at parse
+ * time.
+ */
+export type TableRegion = {
+    name: string;
+    sheet: string;
+    /** Row of the header. The data starts on the next one. */
+    headerRow: number;
+    /** First and last column, inclusive. */
+    firstCol: number;
+    lastCol: number;
+    /** Last row of the DATA, not counting a totals row. */
+    lastRow: number;
+    /** Whether the row after `lastRow` is a totals row. */
+    hasTotals: boolean;
+};
+/** Which part of a table a structured reference asks for. */
+export type TableSpecifier = '#All' | '#Data' | '#Headers' | '#Totals' | '#ThisRow';
+export type TableRange = {
+    sheet: string;
+    firstRow: number;
+    lastRow: number;
+    firstCol: number;
+    lastCol: number;
+};
+export type TableRegistry = {
+    define(table: TableRegion): void;
+    remove(name: string): boolean;
+    get(name: string): TableRegion | undefined;
+    list(): TableRegion[];
+    /** The table containing a cell, if any. This is what makes an unqualified
+     *  `[@Amount]` work: it only means something inside a table. */
+    at(sheet: string, row: number, col: number): TableRegion | undefined;
+    /** Grow a table to include a row written just below it, the way Excel's
+     *  auto-expand does. Returns whether anything changed. */
+    growToInclude(sheet: string, row: number, col: number): boolean;
+    clear(): void;
+};
+/** Excel's rules for a table name are the same as for a defined name. */
+export declare function isValidTableName(name: string): boolean;
+export declare function createTableRegistry(initial?: ReadonlyArray<TableRegion>): TableRegistry;
+/** Column index for a header name, or -1. Case-insensitive, as Excel is. */
+export declare function columnIndexOf(table: TableRegion, header: string, headerAt: (sheet: string, row: number, col: number) => string): number;
+/**
+ * Resolve a structured reference to a rectangle.
+ *
+ * `currentRow` is where the formula lives, which is the only way `[@Amount]`
+ * can mean anything: "this row" is relative to the formula, not the table.
+ * A `#ThisRow` reference from outside the table has no answer, so it returns
+ * null and the evaluator reports #VALUE!, which is what Excel does.
+ */
+export declare function resolveTableRange(table: TableRegion, specifier: TableSpecifier, columns: {
+    from: number;
+    to: number;
+} | null, currentRow: number | null): TableRange | null;
+/** How many data rows a table holds. */
+export declare function rowCountOf(table: TableRegion): number;

package/dist/sheet/tables.js

@@ -0,0 +1,147 @@
+/**
+ * Tables: a named region with a header row, so a formula can say
+ * `Orders[Amount]` instead of `D2:D57` and keep meaning it after rows are
+ * added.
+ *
+ * The point is not shorter text. A1 references are positional, so a total
+ * under a table has to be re-pointed every time the table grows, and a
+ * reference typed against 57 rows silently stops covering row 58. A
+ * structured reference names the COLUMN, and the range it resolves to is
+ * whatever the table currently is.
+ *
+ * This module is the model; the grammar that reads `Orders[Amount]` lives in
+ * the tokenizer, and resolving one to a range happens at evaluation, because
+ * the range depends on the table's size at that moment rather than at parse
+ * time.
+ */
+/** Excel's rules for a table name are the same as for a defined name. */
+export function isValidTableName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name))
+        return false;
+    if (name.length > 255)
+        return false;
+    if (/^\$?[A-Za-z]{1,3}\$?\d+$/.test(name))
+        return false;
+    if (/^[RC]$/i.test(name))
+        return false;
+    return true;
+}
+export function createTableRegistry(initial = []) {
+    const byName = new Map();
+    const registry = {
+        define(table) {
+            if (!isValidTableName(table.name)) {
+                throw new Error(`"${table.name}" is not a valid table name`);
+            }
+            byName.set(table.name.toLowerCase(), { ...table });
+        },
+        remove(name) {
+            return byName.delete(name.toLowerCase());
+        },
+        get(name) {
+            return byName.get(name.toLowerCase());
+        },
+        list() {
+            return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+        },
+        at(sheet, row, col) {
+            for (const table of byName.values()) {
+                if (table.sheet !== sheet)
+                    continue;
+                if (col < table.firstCol || col > table.lastCol)
+                    continue;
+                const bottom = table.hasTotals ? table.lastRow + 1 : table.lastRow;
+                if (row < table.headerRow || row > bottom)
+                    continue;
+                return table;
+            }
+            return undefined;
+        },
+        growToInclude(sheet, row, col) {
+            for (const table of byName.values()) {
+                if (table.sheet !== sheet)
+                    continue;
+                if (col < table.firstCol || col > table.lastCol)
+                    continue;
+                // Only the row immediately after the data extends it. A write five
+                // rows below is a separate thing the user put there, and swallowing
+                // it would be worse than not expanding.
+                if (row !== table.lastRow + 1)
+                    continue;
+                // A totals row occupies that slot already; Excel inserts above it,
+                // which is a structural edit rather than a grow.
+                if (table.hasTotals)
+                    continue;
+                table.lastRow = row;
+                return true;
+            }
+            return false;
+        },
+        clear() {
+            byName.clear();
+        },
+    };
+    for (const table of initial)
+        registry.define(table);
+    return registry;
+}
+/** Column index for a header name, or -1. Case-insensitive, as Excel is. */
+export function columnIndexOf(table, header, headerAt) {
+    const wanted = header.trim().toLowerCase();
+    for (let c = table.firstCol; c <= table.lastCol; c += 1) {
+        if (headerAt(table.sheet, table.headerRow, c).trim().toLowerCase() === wanted)
+            return c;
+    }
+    return -1;
+}
+/**
+ * Resolve a structured reference to a rectangle.
+ *
+ * `currentRow` is where the formula lives, which is the only way `[@Amount]`
+ * can mean anything: "this row" is relative to the formula, not the table.
+ * A `#ThisRow` reference from outside the table has no answer, so it returns
+ * null and the evaluator reports #VALUE!, which is what Excel does.
+ */
+export function resolveTableRange(table, specifier, columns, currentRow) {
+    const firstCol = columns ? columns.from : table.firstCol;
+    const lastCol = columns ? columns.to : table.lastCol;
+    if (firstCol < 0 || lastCol < 0)
+        return null;
+    const totalsRow = table.hasTotals ? table.lastRow + 1 : null;
+    switch (specifier) {
+        case '#Headers':
+            return { sheet: table.sheet, firstRow: table.headerRow, lastRow: table.headerRow, firstCol, lastCol };
+        case '#Totals':
+            return totalsRow === null
+                ? null
+                : { sheet: table.sheet, firstRow: totalsRow, lastRow: totalsRow, firstCol, lastCol };
+        case '#All':
+            return {
+                sheet: table.sheet,
+                firstRow: table.headerRow,
+                lastRow: totalsRow ?? table.lastRow,
+                firstCol, lastCol,
+            };
+        case '#ThisRow': {
+            if (currentRow === null)
+                return null;
+            // Outside the table's data rows, "this row" is meaningless.
+            if (currentRow <= table.headerRow || currentRow > table.lastRow)
+                return null;
+            return { sheet: table.sheet, firstRow: currentRow, lastRow: currentRow, firstCol, lastCol };
+        }
+        case '#Data':
+        default: {
+            const firstRow = table.headerRow + 1;
+            // An empty table has no data rows. Returning the header row instead
+            // would make =SUM(Orders[Amount]) add the word "Amount".
+            if (firstRow > table.lastRow)
+                return null;
+            return { sheet: table.sheet, firstRow, lastRow: table.lastRow, firstCol, lastCol };
+        }
+    }
+}
+/** How many data rows a table holds. */
+export function rowCountOf(table) {
+    return Math.max(0, table.lastRow - table.headerRow);
+}

package/dist/sheet/tokenize.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Formula lexer.
+ *
+ * The awkward part of spreadsheet lexing is that `A1`, `A1:B2`, `Sheet1!A1`,
+ * `'Price list'!A1:B2`, `SUM(` and `TRUE` all start life as the same run of
+ * letters and digits. Rather than guess, the lexer reads the whole word plus
+ * whatever qualifies it (a `!` before, a `:` after, a `(` after) and decides
+ * once, with all of it in hand.
+ *
+ * `$` is part of a word here and stays in the text handed to `parseA1`, which
+ * is what keeps absolute references absolute.
+ */
+import { type CellRef } from './address.js';
+import { type BinaryOp } from './ast.js';
+export type TableRefToken = {
+    t: 'table';
+    table: string | null;
+    column: string | null;
+    columnTo?: string | null;
+    specifier: '#All' | '#Data' | '#Headers' | '#Totals' | '#ThisRow';
+};
+export type Token = TableRefToken | {
+    t: 'num';
+    v: number;
+} | {
+    t: 'str';
+    v: string;
+} | {
+    t: 'bool';
+    v: boolean;
+} | {
+    t: 'ref';
+    ref: CellRef;
+} | {
+    t: 'range';
+    from: CellRef;
+    to: CellRef;
+} | {
+    t: 'name';
+    v: string;
+} | {
+    t: 'fn';
+    v: string;
+} | {
+    t: 'op';
+    v: BinaryOp;
+} | {
+    t: 'lparen';
+} | {
+    t: 'rparen';
+} | {
+    t: 'comma';
+};
+export declare function tokenize(src: string): Token[];