@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/names.d.ts

@@ -0,0 +1,31 @@
+import type { Node } from './ast.js';
+export type DefinedName = {
+    name: string;
+    /** What it refers to, e.g. `=Sheet1!$B$1` or `=$A$1:$C$9`. */
+    refersTo: string;
+};
+export type SheetNames = {
+    define(name: string, refersTo: string): void;
+    remove(name: string): void;
+    has(name: string): boolean;
+    /** The parsed reference behind a name, or null when undefined or unparseable. */
+    resolve(name: string): Node | null;
+    list(): DefinedName[];
+    serialize(): Record<string, string>;
+    hydrate(entries: Record<string, string>): void;
+    clear(): void;
+};
+/**
+ * Excel's rules, and the ones worth enforcing because a name that looks like a
+ * reference makes every formula containing it ambiguous:
+ *   - starts with a letter or underscore
+ *   - letters, digits, underscores and dots after that
+ *   - not something that reads as a CELL reference (`A1`, `$A$1`)
+ *   - not `R` or `C`, which Excel reserves for R1C1 notation
+ *
+ * A bare word like `Tax` is fine even though `TAX` is a valid column label:
+ * the tokenizer only reads a word as a column when it is qualified by a sheet
+ * or followed by a colon, so `=Tax` is never ambiguous.
+ */
+export declare function isValidName(name: string): boolean;
+export declare function createNames(initial?: Record<string, string>): SheetNames;

package/dist/sheet/names.js

@@ -0,0 +1,87 @@
+/**
+ * Defined names: `Tax` resolving to `Sheet1!$B$1`, so a formula can say
+ * `=Subtotal*Tax` instead of `=D5*$B$1`.
+ *
+ * Names are stored as the TEXT they refer to rather than a parsed reference,
+ * because that is what the user typed and what round-trips to xlsx. Resolution
+ * parses on demand and caches nothing: names change rarely and resolving is
+ * cheap next to evaluating the formula that asked.
+ */
+import { parseFormula } from './parse.js';
+/**
+ * Excel's rules, and the ones worth enforcing because a name that looks like a
+ * reference makes every formula containing it ambiguous:
+ *   - starts with a letter or underscore
+ *   - letters, digits, underscores and dots after that
+ *   - not something that reads as a CELL reference (`A1`, `$A$1`)
+ *   - not `R` or `C`, which Excel reserves for R1C1 notation
+ *
+ * A bare word like `Tax` is fine even though `TAX` is a valid column label:
+ * the tokenizer only reads a word as a column when it is qualified by a sheet
+ * or followed by a colon, so `=Tax` is never ambiguous.
+ */
+export function isValidName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name))
+        return false;
+    if (name.length > 255)
+        return false;
+    // Letters followed by digits is a cell reference, whatever else it spells.
+    if (/^\$?[A-Za-z]{1,3}\$?\d+$/.test(name))
+        return false;
+    if (/^[RC]$/i.test(name))
+        return false;
+    if (/^(TRUE|FALSE)$/i.test(name))
+        return false;
+    return true;
+}
+export function createNames(initial) {
+    // Names are case-insensitive in Excel but keep the case they were defined
+    // with, so the map keys on the uppercase form and the entry holds the
+    // original.
+    const byUpper = new Map();
+    const api = {
+        define(name, refersTo) {
+            if (!isValidName(name)) {
+                throw new Error(`"${name}" is not a valid defined name: it must start with a letter ` +
+                    'or underscore and must not look like a cell reference.');
+            }
+            byUpper.set(name.toUpperCase(), { name, refersTo });
+        },
+        remove(name) {
+            byUpper.delete(name.toUpperCase());
+        },
+        has(name) {
+            return byUpper.has(name.toUpperCase());
+        },
+        resolve(name) {
+            const entry = byUpper.get(name.toUpperCase());
+            if (!entry)
+                return null;
+            try {
+                return parseFormula(entry.refersTo);
+            }
+            catch {
+                return null;
+            }
+        },
+        list() {
+            return [...byUpper.values()].sort((a, b) => a.name.localeCompare(b.name));
+        },
+        serialize() {
+            return Object.fromEntries([...byUpper.values()].map((e) => [e.name, e.refersTo]));
+        },
+        hydrate(entries) {
+            byUpper.clear();
+            for (const [name, refersTo] of Object.entries(entries)) {
+                if (isValidName(name))
+                    byUpper.set(name.toUpperCase(), { name, refersTo });
+            }
+        },
+        clear() {
+            byUpper.clear();
+        },
+    };
+    if (initial)
+        api.hydrate(initial);
+    return api;
+}

package/dist/sheet/navigate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Excel's jump-to-edge navigation, as pure functions over a cell-value lookup.
+ *
+ * `Ctrl+Arrow` is not "move a long way". It is a run-boundary search, and the
+ * rule flips depending on what you are standing on:
+ *
+ *   - Standing on a FILLED cell with a filled neighbour: run to the LAST filled
+ *     cell before the next blank. This is how you get from the top of a column
+ *     to its bottom in one press.
+ *   - Standing on a FILLED cell whose neighbour is blank: skip the blank run
+ *     and land on the NEXT filled cell. This is how you hop between blocks.
+ *   - Standing on a BLANK cell: skip to the next filled cell.
+ *   - Nothing filled ahead in either case: land on the last cell of the sheet
+ *     in that direction, which is what Ctrl+Down does on an empty column.
+ *
+ * Getting this wrong in the obvious way (always run to the end of the filled
+ * block) means the shortcut stops working the moment there is a gap, which is
+ * most real spreadsheets.
+ */
+/** What counts as empty. Excel treats a cell holding an empty string as blank
+ *  for navigation, and so does this: a column of `''` should not trap the
+ *  cursor. A zero, a `false` and a whitespace-only string are all content. */
+export declare function isBlankValue(value: unknown): boolean;
+export type Direction = 'up' | 'down' | 'left' | 'right';
+export type Grid = {
+    rowCount: number;
+    colCount: number;
+    isBlank(row: number, col: number): boolean;
+};
+export type Cell = {
+    row: number;
+    col: number;
+};
+/**
+ * Where `Ctrl+Arrow` lands from `from`, going `dir`. Never returns a cell off
+ * the sheet, and returns `from` unchanged when it is already on the edge.
+ */
+export declare function edgeOfRegion(grid: Grid, from: Cell, dir: Direction): Cell;
+export type Rect = readonly [minRow: number, minCol: number, maxRow: number, maxCol: number];
+/**
+ * Excel's `Ctrl+A` first press: the contiguous block of non-blank cells around
+ * `from`, grown outward until every bounding edge is blank.
+ *
+ * Grown as a rectangle rather than flood-filled, because that is what Excel
+ * selects: a block with a notch in it still comes back as the rectangle that
+ * encloses it. Returns the single cell when `from` sits alone in white space.
+ */
+export declare function currentRegion(grid: Grid, from: Cell): Rect;
+/** Whether `rect` already covers every cell, so `Ctrl+A` should stop growing. */
+export declare function isWholeSheet(grid: Grid, rect: Rect): boolean;
+/** The whole sheet as a rectangle. */
+export declare function wholeSheet(grid: Grid): Rect;

package/dist/sheet/navigate.js

@@ -0,0 +1,135 @@
+/**
+ * Excel's jump-to-edge navigation, as pure functions over a cell-value lookup.
+ *
+ * `Ctrl+Arrow` is not "move a long way". It is a run-boundary search, and the
+ * rule flips depending on what you are standing on:
+ *
+ *   - Standing on a FILLED cell with a filled neighbour: run to the LAST filled
+ *     cell before the next blank. This is how you get from the top of a column
+ *     to its bottom in one press.
+ *   - Standing on a FILLED cell whose neighbour is blank: skip the blank run
+ *     and land on the NEXT filled cell. This is how you hop between blocks.
+ *   - Standing on a BLANK cell: skip to the next filled cell.
+ *   - Nothing filled ahead in either case: land on the last cell of the sheet
+ *     in that direction, which is what Ctrl+Down does on an empty column.
+ *
+ * Getting this wrong in the obvious way (always run to the end of the filled
+ * block) means the shortcut stops working the moment there is a gap, which is
+ * most real spreadsheets.
+ */
+/** What counts as empty. Excel treats a cell holding an empty string as blank
+ *  for navigation, and so does this: a column of `''` should not trap the
+ *  cursor. A zero, a `false` and a whitespace-only string are all content. */
+export function isBlankValue(value) {
+    return value === null || value === undefined || value === '';
+}
+const STEP = {
+    up: { row: -1, col: 0 },
+    down: { row: 1, col: 0 },
+    left: { row: 0, col: -1 },
+    right: { row: 0, col: 1 },
+};
+function inBounds(grid, row, col) {
+    return row >= 0 && row < grid.rowCount && col >= 0 && col < grid.colCount;
+}
+/** The last cell in `dir` that is still on the sheet. */
+function lastInDirection(grid, from, dir) {
+    switch (dir) {
+        case 'up': return { row: 0, col: from.col };
+        case 'down': return { row: Math.max(grid.rowCount - 1, 0), col: from.col };
+        case 'left': return { row: from.row, col: 0 };
+        case 'right': return { row: from.row, col: Math.max(grid.colCount - 1, 0) };
+    }
+}
+/**
+ * Where `Ctrl+Arrow` lands from `from`, going `dir`. Never returns a cell off
+ * the sheet, and returns `from` unchanged when it is already on the edge.
+ */
+export function edgeOfRegion(grid, from, dir) {
+    if (grid.rowCount === 0 || grid.colCount === 0)
+        return from;
+    const step = STEP[dir];
+    const first = { row: from.row + step.row, col: from.col + step.col };
+    if (!inBounds(grid, first.row, first.col))
+        return from;
+    const startFilled = !grid.isBlank(from.row, from.col);
+    const nextFilled = !grid.isBlank(first.row, first.col);
+    if (startFilled && nextFilled) {
+        // Run to the last filled cell before the next blank.
+        let cur = first;
+        for (;;) {
+            const ahead = { row: cur.row + step.row, col: cur.col + step.col };
+            if (!inBounds(grid, ahead.row, ahead.col) || grid.isBlank(ahead.row, ahead.col))
+                return cur;
+            cur = ahead;
+        }
+    }
+    // Otherwise skip ahead to the next filled cell.
+    let cur = first;
+    for (;;) {
+        if (!grid.isBlank(cur.row, cur.col))
+            return cur;
+        const ahead = { row: cur.row + step.row, col: cur.col + step.col };
+        // Nothing filled the whole way: Excel parks you on the last cell.
+        if (!inBounds(grid, ahead.row, ahead.col))
+            return lastInDirection(grid, from, dir);
+        cur = ahead;
+    }
+}
+/**
+ * Excel's `Ctrl+A` first press: the contiguous block of non-blank cells around
+ * `from`, grown outward until every bounding edge is blank.
+ *
+ * Grown as a rectangle rather than flood-filled, because that is what Excel
+ * selects: a block with a notch in it still comes back as the rectangle that
+ * encloses it. Returns the single cell when `from` sits alone in white space.
+ */
+export function currentRegion(grid, from) {
+    if (grid.rowCount === 0 || grid.colCount === 0)
+        return [0, 0, 0, 0];
+    let minRow = from.row;
+    let maxRow = from.row;
+    let minCol = from.col;
+    let maxCol = from.col;
+    const edgeHasContent = (r0, r1, c0, c1) => {
+        for (let r = r0; r <= r1; r += 1) {
+            for (let c = c0; c <= c1; c += 1) {
+                if (inBounds(grid, r, c) && !grid.isBlank(r, c))
+                    return true;
+            }
+        }
+        return false;
+    };
+    // Keep growing while any bounding edge still touches content. One side
+    // growing can expose content on another, so this repeats until stable.
+    for (let grew = true; grew;) {
+        grew = false;
+        if (minRow > 0 && edgeHasContent(minRow - 1, minRow - 1, minCol, maxCol)) {
+            minRow -= 1;
+            grew = true;
+        }
+        if (maxRow < grid.rowCount - 1 && edgeHasContent(maxRow + 1, maxRow + 1, minCol, maxCol)) {
+            maxRow += 1;
+            grew = true;
+        }
+        if (minCol > 0 && edgeHasContent(minRow, maxRow, minCol - 1, minCol - 1)) {
+            minCol -= 1;
+            grew = true;
+        }
+        if (maxCol < grid.colCount - 1 && edgeHasContent(minRow, maxRow, maxCol + 1, maxCol + 1)) {
+            maxCol += 1;
+            grew = true;
+        }
+    }
+    return [minRow, minCol, maxRow, maxCol];
+}
+/** Whether `rect` already covers every cell, so `Ctrl+A` should stop growing. */
+export function isWholeSheet(grid, rect) {
+    return (rect[0] === 0 && rect[1] === 0 &&
+        rect[2] === Math.max(grid.rowCount - 1, 0) &&
+        rect[3] === Math.max(grid.colCount - 1, 0));
+}
+/** The whole sheet as a rectangle. */
+export function wholeSheet(grid) {
+    return [0, 0, Math.max(grid.rowCount - 1, 0), Math.max(grid.colCount - 1, 0)];
+}

package/dist/sheet/number-format.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Excel number-format strings, compiled once and applied many times.
+ *
+ * The grammar is small but full of traps, so this file is explicit about the
+ * ones that bite:
+ *
+ *   - A pattern has up to four sections separated by `;`:
+ *     positive;negative;zero;text. With two, the second covers negatives AND
+ *     zero. With one, it covers everything. A negative rendered by section two
+ *     uses its ABSOLUTE value, which is why `0.00;(0.00)` shows `(1.50)` and
+ *     not `(-1.50)`.
+ *   - `,` means two different things. Between placeholders it is a thousands
+ *     separator; immediately before the decimal point (or at the end) it scales
+ *     the number down by a thousand per comma.
+ *   - `%` scales UP by 100 and prints a literal percent.
+ *   - `0` prints a digit or a zero, `#` prints a digit or nothing, `?` prints a
+ *     digit or a space. They can be mixed: `#,##0.0#` keeps one decimal always
+ *     and a second only when it is there.
+ *   - Anything in quotes, after a backslash, or in the set of always-literal
+ *     characters is emitted as-is.
+ *   - `[Red]` and friends set a colour rather than printing.
+ *   - `@` is the text placeholder and only appears in the fourth section.
+ *
+ * Dates are detected rather than configured: a pattern containing date tokens
+ * outside quotes is a date pattern. `m` is minutes when it follows an hour
+ * token and months otherwise, which is the one piece of context the token
+ * scanner has to carry.
+ */
+export type CompiledFormat = {
+    /** Render a value. `color` is set when the matching section named one. */
+    format(value: unknown): {
+        text: string;
+        color?: string;
+    };
+    /** The pattern this was compiled from, for round-tripping to xlsx. */
+    readonly pattern: string;
+};
+/**
+ * The marks a rendered number carries.
+ *
+ * The PATTERN is always written the invariant way, `#,##0.00`, whatever
+ * the locale: that is how Excel stores one and how the file carries it.
+ * These are what the pattern's `,` and `.` come out AS.
+ */
+export type NumberMarks = {
+    decimal: string;
+    group: string;
+};
+export declare const INVARIANT_MARKS: NumberMarks;
+export declare function compileNumberFormat(pattern: string, marks?: NumberMarks): CompiledFormat;
+/** Format one value against a pattern. Convenience over compile-then-call. */
+export declare function formatWithPattern(value: unknown, pattern: string): string;
+/** The presets behind Ctrl+Shift+1 through 6 and the ribbon's $ % , buttons.
+ *  Percent is Excel's Percent Style, no decimals: 0.425 reads 43%. */
+export declare const FORMAT_PRESETS: {
+    readonly general: "General";
+    readonly number: "#,##0.00";
+    readonly time: "h:mm AM/PM";
+    readonly date: "yyyy-mm-dd";
+    readonly currency: "$#,##0.00;($#,##0.00)";
+    readonly accounting: "_($* #,##0.00_);_($* (#,##0.00);_($* \"-\"??_);_(@_)";
+    readonly percent: "0%";
+    readonly scientific: "0.00E+00";
+};
+/** What the ribbon's Number Format combo applies for a category. Excel's
+ *  "Percentage" there carries two decimals where its % button carries none;
+ *  the other entries are the presets. */
+export declare const FORMAT_CATEGORY_PATTERNS: Record<keyof typeof FORMAT_PRESETS, string>;
+/** Excel's Special category: fixed-shape numbers laid into a mask. */
+export declare const SPECIAL_FORMATS: {
+    readonly zip: {
+        readonly label: "Zip Code";
+        readonly pattern: "00000";
+    };
+    readonly zip4: {
+        readonly label: "Zip Code + 4";
+        readonly pattern: "00000-0000";
+    };
+    readonly phone: {
+        readonly label: "Phone Number";
+        readonly pattern: "[<=9999999]###-####;(###) ###-####";
+    };
+    readonly ssn: {
+        readonly label: "Social Security Number";
+        readonly pattern: "000-00-0000";
+    };
+};
+export type SpecialFormatName = keyof typeof SPECIAL_FORMATS;
+/** The pattern Excel's Accounting category spells for a symbol and a
+ *  number of decimals; an empty symbol is its "None". */
+export declare function accountingPattern(symbol: string, decimals: number): string;
+/** The symbol and decimals an accounting pattern was built from, or null
+ *  when the pattern is not one `accountingPattern` would spell. */
+export declare function accountingParts(fmt: string | undefined): {
+    symbol: string;
+    decimals: number;
+} | null;
+export type FormatPresetName = keyof typeof FORMAT_PRESETS;
+/**
+ * Which of Excel's categories a pattern belongs to, with the decimals and
+ * separator it carries, so the ribbon's combo can say "Percentage" for a
+ * cell holding `0%` (a typed 12%) as well as for the combo's `0.00%`, and
+ * Format Cells can open on the right category. A pattern that is none of
+ * them is 'custom'.
+ */
+export declare function formatCategory(fmt: string | undefined): {
+    category: FormatPresetName | 'special' | 'custom';
+    decimals: number;
+    thousands: boolean;
+};