@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/entry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ * Anything else, formulas included, is stored as typed.
+ */
+export type ParsedEntry = {
+    /** The number, as text the workbook stores. */
+    value: string;
+    /** The Excel format string the entry implies. */
+    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): ParsedEntry | null;

package/dist/sheet/entry.js

@@ -0,0 +1,76 @@
+const zeros = (n) => (n > 0 ? '.' + '0'.repeat(n) : '');
+/** Digits with optional thousands separators and decimals, as a number. */
+function numberOf(digits) {
+    const plain = digits.replace(/,/g, '');
+    const n = Number(plain);
+    return Number.isFinite(n) ? n : null;
+}
+const decimalsOf = (digits) => digits.split('.')[1]?.length ?? 0;
+/** Round away the binary noise of a division: 33.3% is 0.333, not 0.33299999. */
+const trim = (n, places) => String(Number(n.toFixed(places)));
+const GROUPED = String.raw `(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?`;
+const PERCENT = new RegExp(String.raw `^(-?)(${GROUPED})\s?%$`);
+const CURRENCY = new RegExp(String.raw `^(-?)\$\s?(${GROUPED})$`);
+const CURRENCY_PAREN = new RegExp(String.raw `^\(\$\s?(${GROUPED})\)$`);
+const THOUSANDS = new RegExp(String.raw `^(-?)(\d{1,3}(?:,\d{3})+(?:\.\d+)?)$`);
+/**
+ * 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 function completeEntry(typed, entries) {
+    if (typed === '' || typed.startsWith('=') || typed.includes('\n'))
+        return null;
+    const lower = typed.toLowerCase();
+    let found = null;
+    for (const entry of entries) {
+        if (entry.length <= typed.length || !entry.toLowerCase().startsWith(lower))
+            continue;
+        if (found !== null && found !== entry)
+            return null;
+        found = entry;
+    }
+    return found;
+}
+export function parseEntry(text) {
+    const t = text.trim();
+    if (t === '' || t.startsWith('='))
+        return null;
+    let m = PERCENT.exec(t);
+    if (m) {
+        const n = numberOf(m[2]);
+        if (n === null)
+            return null;
+        const places = decimalsOf(m[2]);
+        return { value: trim((m[1] ? -n : n) / 100, places + 2), numFmt: `0${zeros(places)}%` };
+    }
+    m = CURRENCY.exec(t);
+    const paren = m ? null : CURRENCY_PAREN.exec(t);
+    if (m || paren) {
+        const digits = (m ? m[2] : paren[1]);
+        const n = numberOf(digits);
+        if (n === null)
+            return null;
+        const negative = m ? m[1] === '-' : true;
+        const places = decimalsOf(digits) > 0 ? 2 : 0;
+        const body = `$#,##0${zeros(places)}`;
+        return { value: String(negative ? -n : n), numFmt: `${body};(${body})` };
+    }
+    m = THOUSANDS.exec(t);
+    if (m) {
+        const n = numberOf(m[2]);
+        if (n === null)
+            return null;
+        const places = decimalsOf(m[2]);
+        return { value: String(m[1] ? -n : n), numFmt: `#,##0${zeros(places)}` };
+    }
+    return null;
+}

package/dist/sheet/evaluate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The evaluator.
+ *
+ * Errors travel as VALUES once evaluation finishes, but as thrown
+ * `FormulaError`s while it runs. That split is deliberate: a coercion buried
+ * three calls deep inside a function needs to abort the whole expression, and
+ * threading a result type through every branch of every builtin would swamp the
+ * table. The throw is caught here, at the one boundary, and becomes a value.
+ *
+ * Four functions never reach the table because they must NOT have every
+ * argument evaluated first: IF and IFS pick a branch, IFERROR needs to catch,
+ * and SWITCH matches before evaluating. Evaluating both branches of an IF is
+ * not just wasted work - `=IF(A1=0, 0, 100/A1)` would raise #DIV/0! from the
+ * branch it did not take.
+ */
+import { type CellValue, type Node } from './ast.js';
+import { type SheetFunction } from './functions.js';
+import { type TableRegion } from './tables.js';
+export type EvalContext = {
+    /** Read one cell. Out of bounds should return `{ error: '#REF!' }`. */
+    resolve(sheet: string | null, row: number, col: number): CellValue;
+    /** Last used row of a sheet, for open-ended whole-column ranges. */
+    lastRow(sheet: string | null): number;
+    /**
+     * Resolve a defined name to the reference it stands for, or null when
+     * there is no such name. The node is evaluated in place of the name, so a
+     * name that refers to a range behaves as that range: `=SUM(Sales)` adds
+     * the whole column and `=VLOOKUP(x, Prices, 2)` searches the whole table.
+     * Preferred over `resolveName`, which can only ever produce one value.
+     */
+    resolveNameNode?(name: string): Node | null;
+    /** Resolve a defined name to a single value. Consulted when
+     *  `resolveNameNode` is absent or returns null; undefined is #NAME?. */
+    resolveName?(name: string): CellValue | undefined;
+    functions?: Record<string, SheetFunction>;
+    /** Look a table up by name. */
+    findTable?(name: string): TableRegion | undefined;
+    /** The table containing the cell the formula lives in, which is the only
+     *  way the unqualified `[@Amount]` form can mean anything. */
+    tableAt?(sheet: string | null, row: number, col: number): TableRegion | undefined;
+    /** Where the formula being evaluated sits. Needed for `[@Column]`, which
+     *  is relative to the formula rather than to the table. */
+    currentCell?: {
+        sheet: string | null;
+        row: number;
+        col: number;
+    };
+};
+/**
+ * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
+ * inside becomes the matching error value.
+ */
+/**
+ * The values a node stands for as a grid: a range, a reference (one cell),
+ * or a name that refers to either. Null for anything else, which is how a
+ * caller tells "a list source that is a range" from "a formula".
+ */
+export declare function rangeValues(node: Node, ctx: EvalContext): CellValue[][] | null;
+export declare function evaluate(node: Node, ctx: EvalContext): CellValue;
+/** Render a computed value the way a cell shows it. */
+export declare function formatValue(v: CellValue): string;

package/dist/sheet/evaluate.js

@@ -0,0 +1,337 @@
+/**
+ * The evaluator.
+ *
+ * Errors travel as VALUES once evaluation finishes, but as thrown
+ * `FormulaError`s while it runs. That split is deliberate: a coercion buried
+ * three calls deep inside a function needs to abort the whole expression, and
+ * threading a result type through every branch of every builtin would swamp the
+ * table. The throw is caught here, at the one boundary, and becomes a value.
+ *
+ * Four functions never reach the table because they must NOT have every
+ * argument evaluated first: IF and IFS pick a branch, IFERROR needs to catch,
+ * and SWITCH matches before evaluating. Evaluating both branches of an IF is
+ * not just wasted work - `=IF(A1=0, 0, 100/A1)` would raise #DIV/0! from the
+ * branch it did not take.
+ */
+import { FormulaError, isError, err, } from './ast.js';
+import { toNumber, toBool, toText, looseEquals, compare } from './coerce.js';
+import { withCustomFunctions } from './functions.js';
+import { resolveTableRange, columnIndexOf, } from './tables.js';
+function rangeGrid(from, to, ctx) {
+    const sheet = from.sheet ?? to.sheet;
+    const r1 = Math.min(from.row ?? 0, to.row ?? from.row ?? 0);
+    const r2 = to.row === null || from.row === null
+        ? ctx.lastRow(sheet)
+        : Math.max(from.row, to.row);
+    const c1 = Math.min(from.col, to.col);
+    const c2 = Math.max(from.col, to.col);
+    const out = [];
+    for (let r = r1; r <= r2; r += 1) {
+        const row = [];
+        for (let c = c1; c <= c2; c += 1)
+            row.push(ctx.resolve(sheet, r, c));
+        out.push(row);
+    }
+    return out;
+}
+function binary(op, l, r) {
+    switch (op) {
+        case '+': return toNumber(l) + toNumber(r);
+        case '-': return toNumber(l) - toNumber(r);
+        case '*': return toNumber(l) * toNumber(r);
+        case '/': {
+            const d = toNumber(r);
+            return d === 0 ? err('#DIV/0!') : toNumber(l) / d;
+        }
+        case '^': return Math.pow(toNumber(l), toNumber(r));
+        case '&': return toText(l) + toText(r);
+        case '=': return looseEquals(l, r);
+        case '<>': return !looseEquals(l, r);
+        case '<': return compare(l, r) < 0;
+        case '>': return compare(l, r) > 0;
+        case '<=': return compare(l, r) <= 0;
+        case '>=': return compare(l, r) >= 0;
+        default: return err('#VALUE!');
+    }
+}
+/** Functions handled before the table, because their arguments must not all
+ *  be evaluated up front. */
+const SHORT_CIRCUIT = new Set(['IF', 'IFS', 'IFERROR', 'IFNA', 'SWITCH']);
+function evalNode(node, ctx) {
+    switch (node.k) {
+        case 'num': return node.v;
+        case 'str': return node.v;
+        case 'bool': return node.v;
+        case 'ref':
+            return ctx.resolve(node.ref.sheet, node.ref.row ?? 0, node.ref.col);
+        case 'range': {
+            // A range in scalar position collapses to its top-left cell, which is
+            // what Excel does outside an array context.
+            const grid = rangeGrid(node.from, node.to, ctx);
+            return grid[0]?.[0] ?? '';
+        }
+        case 'name': {
+            const target = nameTarget(node.name, ctx);
+            if (target)
+                return evalNode(target, ctx);
+            const v = ctx.resolveName?.(node.name);
+            return v === undefined ? err('#NAME?') : v;
+        }
+        case 'unary': {
+            const v = evalNode(node.arg, ctx);
+            if (isError(v))
+                return v;
+            if (node.op === '-')
+                return -toNumber(v);
+            if (node.op === '%')
+                return toNumber(v) / 100;
+            return toNumber(v);
+        }
+        case 'binary': {
+            const l = evalNode(node.left, ctx);
+            if (isError(l))
+                return l;
+            const r = evalNode(node.right, ctx);
+            if (isError(r))
+                return r;
+            return binary(node.op, l, r);
+        }
+        case 'table':
+            return evalTableRef(node, ctx);
+        case 'fn':
+            return evalCall(node, ctx);
+    }
+}
+/**
+ * Turn a structured reference into a rectangle and read it.
+ *
+ * Every failure here is #REF! rather than a throw, because a table reference
+ * naming a column that was renamed is an ordinary thing to find in a sheet,
+ * and one broken total should not take the rest of the workbook with it.
+ */
+function tableRectOf(node, ctx) {
+    const here = ctx.currentCell;
+    const table = node.table
+        ? ctx.findTable?.(node.table)
+        : here
+            ? ctx.tableAt?.(here.sheet, here.row, here.col)
+            : undefined;
+    if (!table)
+        return null;
+    const headerAt = (sheet, row, col) => {
+        const v = ctx.resolve(sheet, row, col);
+        return isError(v) ? '' : toText(v);
+    };
+    let columns = null;
+    if (node.column !== null) {
+        const from = columnIndexOf(table, node.column, headerAt);
+        if (from < 0)
+            return null;
+        const to = node.columnTo != null
+            ? columnIndexOf(table, node.columnTo, headerAt)
+            : from;
+        if (to < 0)
+            return null;
+        columns = { from: Math.min(from, to), to: Math.max(from, to) };
+    }
+    return resolveTableRange(table, node.specifier, columns, here ? here.row : null);
+}
+function evalTableRef(node, ctx) {
+    const rect = tableRectOf(node, ctx);
+    if (!rect)
+        return err('#REF!');
+    // Scalar position collapses to the top-left, the same as an A1 range.
+    return ctx.resolve(rect.sheet, rect.firstRow, rect.firstCol);
+}
+/** Every cell of a structured reference, for the aggregate functions. */
+function tableGrid(node, ctx) {
+    const rect = tableRectOf(node, ctx);
+    if (!rect)
+        return null;
+    const out = [];
+    for (let r = rect.firstRow; r <= rect.lastRow; r += 1) {
+        const line = [];
+        for (let c = rect.firstCol; c <= rect.lastCol; c += 1)
+            line.push(ctx.resolve(rect.sheet, r, c));
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * The reference a defined name stands for, or null.
+ *
+ * A name may be defined as another name (`Sales` -> `Q3Sales`), so this
+ * follows the chain. It stops after a handful of hops rather than walking a
+ * circular definition forever: `A` -> `B` -> `A` is a mistake in the Name
+ * Manager, and the formula that used it reads #NAME? rather than hanging.
+ */
+function nameTarget(name, ctx) {
+    let node = ctx.resolveNameNode?.(name) ?? null;
+    for (let hops = 0; node && node.k === 'name'; hops += 1) {
+        if (hops >= 8)
+            return null;
+        node = ctx.resolveNameNode?.(node.name) ?? null;
+    }
+    return node;
+}
+/** Functions whose arguments must not all be evaluated up front. */
+function evalCall(node, ctx) {
+    const { name, args } = node;
+    // Every short-circuiting function below indexes its arguments directly.
+    // `=IF()` parses fine, so without this the index is undefined and the
+    // TypeError escapes the boundary this module promises never to throw past.
+    if (SHORT_CIRCUIT.has(name) && args.length === 0)
+        return err('#VALUE!');
+    if (name === 'IF') {
+        const cond = evalNode(args[0], ctx);
+        if (isError(cond))
+            return cond;
+        const branch = toBool(cond) ? args[1] : args[2];
+        if (!branch)
+            return toBool(cond);
+        return evalNode(branch, ctx);
+    }
+    if (name === 'IFERROR' || name === 'IFNA') {
+        try {
+            const v = evalNode(args[0], ctx);
+            if (!isError(v))
+                return v;
+            if (name === 'IFNA' && v.error !== '#N/A')
+                return v;
+        }
+        catch (e) {
+            if (!(e instanceof FormulaError))
+                throw e;
+            if (name === 'IFNA' && e.code !== '#N/A')
+                return err(e.code);
+        }
+        return args[1] ? evalNode(args[1], ctx) : err('#N/A');
+    }
+    if (name === 'IFS') {
+        for (let i = 0; i + 1 < args.length; i += 2) {
+            const cond = evalNode(args[i], ctx);
+            if (isError(cond))
+                return cond;
+            if (toBool(cond))
+                return evalNode(args[i + 1], ctx);
+        }
+        return err('#N/A');
+    }
+    if (name === 'SWITCH') {
+        const subject = evalNode(args[0], ctx);
+        if (isError(subject))
+            return subject;
+        let i = 1;
+        for (; i + 1 < args.length; i += 2) {
+            const candidate = evalNode(args[i], ctx);
+            if (isError(candidate))
+                return candidate;
+            if (looseEquals(subject, candidate))
+                return evalNode(args[i + 1], ctx);
+        }
+        // A trailing odd argument is the default.
+        return i < args.length ? evalNode(args[i], ctx) : err('#N/A');
+    }
+    const table = ctx.functions ?? withCustomFunctions(undefined);
+    const fn = table[name];
+    if (!fn)
+        return err('#NAME?');
+    // Evaluate every argument, keeping range shape for the lookups that need it.
+    const perArg = [];
+    const grids = [];
+    for (const given of args) {
+        // A name stands for whatever it was defined as. Substituting the node
+        // here, before the shape check, is what lets `Sales` in =SUM(Sales) be a
+        // whole column rather than the top-left cell a scalar read would give.
+        const arg = given.k === 'name' ? (nameTarget(given.name, ctx) ?? given) : given;
+        if (arg.k === 'range') {
+            const grid = rangeGrid(arg.from, arg.to, ctx);
+            grids.push(grid);
+            perArg.push(grid.flat());
+        }
+        else if (arg.k === 'table') {
+            // A structured reference expands exactly as a range does, which is
+            // what makes =SUM(Orders[Amount]) work.
+            const grid = tableGrid(arg, ctx);
+            if (!grid) {
+                grids.push(null);
+                perArg.push([err('#REF!')]);
+            }
+            else {
+                grids.push(grid);
+                perArg.push(grid.flat());
+            }
+        }
+        else {
+            grids.push(null);
+            perArg.push([evalNode(arg, ctx)]);
+        }
+    }
+    const flat = perArg.flat();
+    // An error anywhere in the arguments propagates, except for the counting
+    // functions, which Excel lets see errors in their range.
+    if (name !== 'COUNTA' && name !== 'COUNTBLANK') {
+        for (const v of flat)
+            if (isError(v))
+                return v;
+    }
+    const payload = { flat, args: perArg, grids };
+    return fn(payload);
+}
+/**
+ * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
+ * inside becomes the matching error value.
+ */
+/**
+ * The values a node stands for as a grid: a range, a reference (one cell),
+ * or a name that refers to either. Null for anything else, which is how a
+ * caller tells "a list source that is a range" from "a formula".
+ */
+export function rangeValues(node, ctx) {
+    try {
+        if (node.k === 'range')
+            return rangeGrid(node.from, node.to, ctx);
+        if (node.k === 'ref')
+            return [[ctx.resolve(node.ref.sheet, node.ref.row ?? 0, node.ref.col)]];
+        if (node.k === 'name') {
+            const target = nameTarget(node.name, ctx);
+            return target ? rangeValues(target, ctx) : null;
+        }
+        return null;
+    }
+    catch (e) {
+        if (e instanceof FormulaError)
+            return [[err(e.code)]];
+        throw e;
+    }
+}
+export function evaluate(node, ctx) {
+    try {
+        return evalNode(node, ctx);
+    }
+    catch (e) {
+        if (e instanceof FormulaError)
+            return err(e.code);
+        if (e instanceof RangeError)
+            return err('#NUM!');
+        // Last resort. This module promises callers it never throws, and a cell
+        // showing #VALUE! is recoverable where an exception out of a render pass
+        // is not.
+        if (e instanceof TypeError)
+            return err('#VALUE!');
+        throw e;
+    }
+}
+/** Render a computed value the way a cell shows it. */
+export function formatValue(v) {
+    if (isError(v))
+        return v.error;
+    if (typeof v === 'boolean')
+        return v ? 'TRUE' : 'FALSE';
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v))
+            return '#NUM!';
+        return String(v);
+    }
+    return String(v);
+}

package/dist/sheet/find-replace.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Find and Replace.
+ *
+ * The grid already has find: a Ctrl+F overlay over displayed values, with
+ * next/prev. What it has no notion of is replacing, and the two differ in more
+ * than direction.
+ *
+ * Finding looks at what the user SEES. Replacing has to write what the user
+ * TYPED, which for a formula cell is the formula, not its result. Replacing
+ * "100" inside a cell showing `100` that actually holds `=B2*C2` would either
+ * do nothing or destroy the formula, depending on which text you reached for.
+ * Hence `lookIn`, and hence replace always writing through the raw text.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+export type FindOptions = {
+    matchCase?: boolean;
+    /** The cell must equal the search text, not merely contain it. */
+    matchEntireCell?: boolean;
+    /** Search the formula source, or the value a cell displays. Default 'values'. */
+    lookIn?: 'values' | 'formulas';
+    /** Restrict to the current selection. Default the whole sheet. */
+    scope?: 'sheet' | 'selection';
+};
+export type FindHit = {
+    rowIndex: number;
+    colIndex: number;
+};
+/** How a cell's text is obtained for each `lookIn` mode. */
+export type FindTarget = {
+    /** The raw text the user typed, formula included. */
+    getRaw(rowIndex: number, colIndex: number): string;
+    /** What the cell displays. Defaults to the raw text when not supplied. */
+    getDisplay?(rowIndex: number, colIndex: number): string;
+    setRaw(rowIndex: number, colIndex: number, text: string): void;
+    /** Whether a cell may be written. Read-only cells are skipped by replace
+     *  but still reported by find. */
+    isEditable?(rowIndex: number, colIndex: number): boolean;
+    onChange?(): void;
+};
+export declare function setFindTarget(next: FindTarget | null): void;
+export declare function getFindTarget(): FindTarget | null;
+/** Does `haystack` match `needle` under these options? */
+export declare function cellMatches(haystack: string, needle: string, opts?: FindOptions): boolean;
+/** Every cell matching, in reading order. */
+export declare function findAll(cmd: GridCommandContext, needle: string, opts?: FindOptions): FindHit[];
+/** The next hit after the active cell, wrapping. Null when there are none. */
+export declare function findNext(cmd: GridCommandContext, needle: string, opts?: FindOptions, direction?: 1 | -1): FindHit | null;
+/** Replace inside one string, honouring case sensitivity and whole-cell. */
+export declare function replaceInText(haystack: string, needle: string, replacement: string, opts?: FindOptions): string;
+/**
+ * Replace the active cell if it matches, then move to the next hit. Returns
+ * whether anything was written.
+ */
+export declare function replaceOne(cmd: GridCommandContext, needle: string, replacement: string, opts?: FindOptions): boolean;
+/**
+ * Replace every match. Returns how many cells changed.
+ *
+ * Runs inside `cmd.batch`, so a hundred replacements are ONE Ctrl+Z. Without
+ * that this would be the single worst thing in the feature set for undo: it is
+ * the one command that routinely writes more cells than the history can hold.
+ */
+export declare function replaceAll(cmd: GridCommandContext, needle: string, replacement: string, opts?: FindOptions): number;