@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/tokenize.js

@@ -0,0 +1,304 @@
+/**
+ * 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 { parseA1 } from './address.js';
+import { FormulaError } from './ast.js';
+const WORD = /[A-Za-z0-9$_.]/;
+const SPECIFIERS = {
+    '#all': '#All',
+    '#data': '#Data',
+    '#headers': '#Headers',
+    '#totals': '#Totals',
+    '#this row': '#ThisRow',
+};
+const TWO_CHAR_OPS = new Set(['<=', '>=', '<>']);
+const ONE_CHAR_OPS = '+-*/^%&=<>';
+export function tokenize(src) {
+    const out = [];
+    let i = 0;
+    /** Index of the next non-space character, without consuming anything. */
+    const skipSpace = () => {
+        let j = i;
+        while (j < src.length && /\s/.test(src[j]))
+            j += 1;
+        return j;
+    };
+    const readWord = () => {
+        const start = i;
+        while (i < src.length && WORD.test(src[i]))
+            i += 1;
+        return src.slice(start, i);
+    };
+    /**
+     * Read a structured reference's bracket, having just consumed the `[`.
+     *
+     * The grammar is small but irregular: `[Amount]` is a column, `[@Amount]`
+     * is this row of it, `[#Totals]` is a specifier, and
+     * `[[Qty]:[Amount]]` is a span whose inner brackets are part of the
+     * syntax rather than nesting. Reading it as balanced brackets and then
+     * picking the pieces apart handles all four without a special case each.
+     */
+    const readTableBracket = (table) => {
+        let depth = 1;
+        const start = i;
+        while (i < src.length && depth > 0) {
+            if (src[i] === '[')
+                depth += 1;
+            else if (src[i] === ']')
+                depth -= 1;
+            if (depth > 0)
+                i += 1;
+        }
+        if (depth !== 0)
+            throw new FormulaError('#PARSE!');
+        const body = src.slice(start, i);
+        i += 1; // past the closing ]
+        let specifier = '#Data';
+        let column = null;
+        let columnTo = null;
+        // Split on top-level commas, so [#Data],[Amount] arrives as two parts.
+        const parts = [];
+        let current = '';
+        let inner = 0;
+        for (const ch of body) {
+            if (ch === '[')
+                inner += 1;
+            else if (ch === ']')
+                inner -= 1;
+            if (ch === ',' && inner === 0) {
+                parts.push(current);
+                current = '';
+                continue;
+            }
+            current += ch;
+        }
+        parts.push(current);
+        for (const rawPart of parts) {
+            let part = rawPart.trim();
+            if (part === '')
+                continue;
+            if (part.startsWith('@')) {
+                specifier = '#ThisRow';
+                part = part.slice(1).trim();
+                if (part === '')
+                    continue;
+            }
+            const known = SPECIFIERS[part.toLowerCase()];
+            if (known) {
+                specifier = known;
+                continue;
+            }
+            // A span: [Qty]:[Amount]
+            const span = /^\[([^\]]*)\]\s*:\s*\[([^\]]*)\]$/.exec(part);
+            if (span) {
+                column = span[1].trim();
+                columnTo = span[2].trim();
+                continue;
+            }
+            // A single bracketed part, which is how a name containing a space or a
+            // comma is written - and also how a specifier arrives inside a
+            // multi-part reference like [[#Headers],[Amount]], so unwrap FIRST
+            // and re-check before assuming it names a column.
+            const wrapped = /^\[([^\]]*)\]$/.exec(part);
+            const unwrapped = (wrapped ? wrapped[1] : part).trim();
+            const inner = SPECIFIERS[unwrapped.toLowerCase()];
+            if (inner) {
+                specifier = inner;
+                continue;
+            }
+            if (unwrapped.startsWith('@')) {
+                specifier = '#ThisRow';
+                const rest = unwrapped.slice(1).trim();
+                if (rest !== '')
+                    column = rest;
+                continue;
+            }
+            column = unwrapped;
+        }
+        return columnTo === null
+            ? { t: 'table', table, column, specifier }
+            : { t: 'table', table, column, columnTo, specifier };
+    };
+    /** Turn a word (and possibly `:word` after it) into a ref, range or name. */
+    const pushWord = (word, sheet) => {
+        const left = parseA1(word, sheet);
+        // Excel accepts whitespace around the range colon: `SUM(A1 : B2)`. Look
+        // past it before deciding this is a lone reference, or that formula comes
+        // back unparseable.
+        const afterSpace = skipSpace();
+        if (src[afterSpace] === ':') {
+            i = afterSpace + 1;
+            while (i < src.length && /\s/.test(src[i]))
+                i += 1;
+            const rightWord = readWord();
+            const right = parseA1(rightWord, sheet);
+            if (!left || !right)
+                throw new FormulaError('#PARSE!');
+            out.push({ t: 'range', from: left, to: right });
+            return;
+        }
+        if (!left)
+            throw new FormulaError('#PARSE!');
+        // A word with no row is a whole-column reference (`A:A` written as `A`),
+        // which is a range from row 0 to the end of the sheet.
+        if (left.row === null) {
+            // A bare word on a sheet-qualified ref is still a column. Unqualified,
+            // it could be a defined name - the parser decides using `name` tokens,
+            // so only emit a column range when the text looks like one.
+            if (sheet !== null) {
+                out.push({ t: 'range', from: { ...left, row: 0 }, to: { ...left, row: null } });
+                return;
+            }
+            out.push({ t: 'name', v: word });
+            return;
+        }
+        out.push({ t: 'ref', ref: left });
+    };
+    while (i < src.length) {
+        const ch = src[i];
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === '(') {
+            out.push({ t: 'lparen' });
+            i += 1;
+            continue;
+        }
+        if (ch === ')') {
+            out.push({ t: 'rparen' });
+            i += 1;
+            continue;
+        }
+        if (ch === ',') {
+            out.push({ t: 'comma' });
+            i += 1;
+            continue;
+        }
+        // String literal. Excel escapes a quote by doubling it.
+        if (ch === '"') {
+            i += 1;
+            let value = '';
+            for (;;) {
+                if (i >= src.length)
+                    throw new FormulaError('#PARSE!');
+                if (src[i] === '"') {
+                    if (src[i + 1] === '"') {
+                        value += '"';
+                        i += 2;
+                        continue;
+                    }
+                    i += 1;
+                    break;
+                }
+                value += src[i];
+                i += 1;
+            }
+            out.push({ t: 'str', v: value });
+            continue;
+        }
+        // Quoted sheet name: 'Price list'!A1
+        if (ch === "'") {
+            i += 1;
+            let sheet = '';
+            for (;;) {
+                if (i >= src.length)
+                    throw new FormulaError('#PARSE!');
+                if (src[i] === "'") {
+                    if (src[i + 1] === "'") {
+                        sheet += "'";
+                        i += 2;
+                        continue;
+                    }
+                    i += 1;
+                    break;
+                }
+                sheet += src[i];
+                i += 1;
+            }
+            if (src[i] !== '!')
+                throw new FormulaError('#PARSE!');
+            i += 1;
+            pushWord(readWord(), sheet);
+            continue;
+        }
+        if (/[0-9]/.test(ch) || (ch === '.' && /[0-9]/.test(src[i + 1] ?? ''))) {
+            const start = i;
+            while (i < src.length && /[0-9.]/.test(src[i]))
+                i += 1;
+            // Scientific notation: 1e5, 2.5E-3.
+            if ((src[i] === 'e' || src[i] === 'E') && /[0-9+-]/.test(src[i + 1] ?? '')) {
+                i += 1;
+                if (src[i] === '+' || src[i] === '-')
+                    i += 1;
+                while (i < src.length && /[0-9]/.test(src[i]))
+                    i += 1;
+            }
+            const n = Number(src.slice(start, i));
+            if (!Number.isFinite(n))
+                throw new FormulaError('#PARSE!');
+            out.push({ t: 'num', v: n });
+            continue;
+        }
+        if (/[A-Za-z$_]/.test(ch)) {
+            const word = readWord();
+            const upper = word.toUpperCase();
+            // Unquoted sheet name: Orders!A1
+            if (src[i] === '!') {
+                i += 1;
+                pushWord(readWord(), word);
+                continue;
+            }
+            if (upper === 'TRUE') {
+                out.push({ t: 'bool', v: true });
+                continue;
+            }
+            if (upper === 'FALSE') {
+                out.push({ t: 'bool', v: false });
+                continue;
+            }
+            // A word followed by `[` is a table: Orders[Amount].
+            if (src[i] === '[') {
+                i += 1;
+                out.push(readTableBracket(word));
+                continue;
+            }
+            // A word followed by `(` is a call, whatever else it might look like.
+            if (src[skipSpace()] === '(') {
+                out.push({ t: 'fn', v: upper });
+                continue;
+            }
+            pushWord(word, null);
+            continue;
+        }
+        // A bare `[` is the unqualified form, which only means something in a
+        // formula sitting inside a table: [@Amount].
+        if (ch === '[') {
+            i += 1;
+            out.push(readTableBracket(null));
+            continue;
+        }
+        const two = src.slice(i, i + 2);
+        if (TWO_CHAR_OPS.has(two)) {
+            out.push({ t: 'op', v: two });
+            i += 2;
+            continue;
+        }
+        if (ONE_CHAR_OPS.includes(ch)) {
+            out.push({ t: 'op', v: ch });
+            i += 1;
+            continue;
+        }
+        throw new FormulaError('#PARSE!');
+    }
+    return out;
+}

package/dist/sheet/transforms.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Text to Columns and Remove Duplicates: the two one-shot transforms an Excel
+ * user reaches for on arriving data, before any formula work starts.
+ *
+ * Both are pure functions over cell text rather than commands that reach into
+ * a grid, because both are things a consumer may want to run from a button, a
+ * menu, a paste handler or a test, and none of those want a keystroke.
+ */
+export type SplitOptions = {
+    /**
+     * Split on these strings. Excel's dialog offers tab, semicolon, comma, space
+     * and "other"; passing several splits on any of them.
+     */
+    delimiters?: ReadonlyArray<string>;
+    /** Treat runs of delimiters as one. Excel's "treat consecutive delimiters as
+     *  one" checkbox, and what you want for space-separated text. */
+    collapse?: boolean;
+    /** Text inside these is not split, and the quotes come off. */
+    quote?: string;
+    /** Trim surrounding whitespace from each field. */
+    trim?: boolean;
+    /** Stop after this many fields, leaving the rest in the last one. Excel has
+     *  no equivalent; it is here because "name: free text with: colons" is the
+     *  common real case. */
+    limit?: number;
+};
+/**
+ * Split one string into fields.
+ *
+ * A scan rather than `String.split`, because a quoted field may contain a
+ * delimiter and a doubled quote is an escaped one. Splitting first and
+ * repairing afterwards is how CSV parsers get subtly wrong.
+ */
+export declare function splitText(text: string, options?: SplitOptions): string[];
+/**
+ * Split a column of text into a grid, padded so every row is the same width.
+ *
+ * Padding matters: writing a ragged result into a grid leaves whatever was
+ * already in the cell, so a row that split into two fields would keep stale
+ * text in the third column.
+ */
+export declare function textToColumns(column: ReadonlyArray<string>, options?: SplitOptions): {
+    rows: string[][];
+    width: number;
+};
+/** Guess which delimiter a column uses, the way Excel's wizard previews one. */
+export declare function guessDelimiter(column: ReadonlyArray<string>, candidates?: ReadonlyArray<string>): string | null;
+export type DuplicateOptions = {
+    /** Column indexes that decide identity. Default: every column given. */
+    columns?: ReadonlyArray<number>;
+    /** Compare case-sensitively. Excel's Remove Duplicates is case
+     *  INSENSITIVE, which surprises people, so that is the default here too. */
+    matchCase?: boolean;
+    /** Keep the last of each group rather than the first. */
+    keep?: 'first' | 'last';
+};
+export type DuplicateReport = {
+    /** Indexes into the input, in order, of the rows to keep. */
+    keep: number[];
+    /** Indexes of the rows that duplicate another. */
+    remove: number[];
+};
+/**
+ * Which rows are duplicates.
+ *
+ * Reports rather than removes, so the caller decides what removal means for
+ * its data structure, and so a UI can say "3 duplicates found, 5 unique values
+ * remain" before anything is written. That message is most of what Excel's
+ * dialog does.
+ */
+export declare function findDuplicates(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: DuplicateOptions): DuplicateReport;
+/** The rows that survive, in their original order, and how many went. */
+export declare function removeDuplicates<T>(rows: ReadonlyArray<T>, toCells: (row: T) => ReadonlyArray<unknown>, options?: DuplicateOptions): {
+    rows: T[];
+    removed: number;
+};

package/dist/sheet/transforms.js

@@ -0,0 +1,154 @@
+/**
+ * Text to Columns and Remove Duplicates: the two one-shot transforms an Excel
+ * user reaches for on arriving data, before any formula work starts.
+ *
+ * Both are pure functions over cell text rather than commands that reach into
+ * a grid, because both are things a consumer may want to run from a button, a
+ * menu, a paste handler or a test, and none of those want a keystroke.
+ */
+const DEFAULTS = {
+    delimiters: [','],
+    collapse: false,
+    quote: '"',
+    trim: false,
+};
+/**
+ * Split one string into fields.
+ *
+ * A scan rather than `String.split`, because a quoted field may contain a
+ * delimiter and a doubled quote is an escaped one. Splitting first and
+ * repairing afterwards is how CSV parsers get subtly wrong.
+ */
+export function splitText(text, options = {}) {
+    const { delimiters, collapse, quote, trim } = { ...DEFAULTS, ...options };
+    const limit = options.limit;
+    // Longest first, so ", " wins over "," when both are offered.
+    const seps = [...delimiters].filter((d) => d !== '').sort((a, b) => b.length - a.length);
+    if (seps.length === 0)
+        return [text];
+    const out = [];
+    let current = '';
+    let inQuote = false;
+    let i = 0;
+    const push = () => {
+        out.push(trim ? current.trim() : current);
+        current = '';
+    };
+    while (i < text.length) {
+        const ch = text[i];
+        if (quote && ch === quote) {
+            if (inQuote && text[i + 1] === quote) {
+                current += quote;
+                i += 2;
+                continue;
+            }
+            inQuote = !inQuote;
+            i += 1;
+            continue;
+        }
+        if (!inQuote && (limit === undefined || out.length < limit - 1)) {
+            const hit = seps.find((sep) => text.startsWith(sep, i));
+            if (hit) {
+                push();
+                i += hit.length;
+                if (collapse) {
+                    // Swallow the run that follows, so "a   b" on a space delimiter
+                    // gives two fields rather than four.
+                    for (;;) {
+                        const more = seps.find((sep) => text.startsWith(sep, i));
+                        if (!more)
+                            break;
+                        i += more.length;
+                    }
+                }
+                continue;
+            }
+        }
+        current += ch;
+        i += 1;
+    }
+    push();
+    return out;
+}
+/**
+ * Split a column of text into a grid, padded so every row is the same width.
+ *
+ * Padding matters: writing a ragged result into a grid leaves whatever was
+ * already in the cell, so a row that split into two fields would keep stale
+ * text in the third column.
+ */
+export function textToColumns(column, options = {}) {
+    const rows = column.map((text) => splitText(text, options));
+    const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
+    for (const row of rows) {
+        while (row.length < width)
+            row.push('');
+    }
+    return { rows, width };
+}
+/** Guess which delimiter a column uses, the way Excel's wizard previews one. */
+export function guessDelimiter(column, candidates = ['\t', ';', ',', '|', ' ']) {
+    let best = null;
+    for (const sep of candidates) {
+        // A good delimiter appears in most rows AND the same number of times in
+        // each. A comma in one row out of fifty is prose, not structure.
+        const counts = column.map((text) => text.split(sep).length - 1);
+        const present = counts.filter((n) => n > 0).length;
+        if (present === 0)
+            continue;
+        const first = counts.find((n) => n > 0) ?? 0;
+        const consistent = counts.every((n) => n === 0 || n === first);
+        const score = present * (consistent ? 2 : 1);
+        if (!best || score > best.score)
+            best = { sep, score };
+    }
+    return best ? best.sep : null;
+}
+/**
+ * Which rows are duplicates.
+ *
+ * Reports rather than removes, so the caller decides what removal means for
+ * its data structure, and so a UI can say "3 duplicates found, 5 unique values
+ * remain" before anything is written. That message is most of what Excel's
+ * dialog does.
+ */
+export function findDuplicates(rows, options = {}) {
+    const keepWhich = options.keep ?? 'first';
+    const matchCase = options.matchCase ?? false;
+    const keyOf = (row) => {
+        const cols = options.columns ?? row.map((_v, i) => i);
+        return cols
+            .map((c) => {
+            const v = row[c];
+            const text = v === null || v === undefined ? '' : String(v);
+            return matchCase ? text : text.toLowerCase();
+        })
+            // A separator a cell cannot contain. Joining on a space would make
+            // ["a", "b"] and ["a b"] the same row.
+            .join('\u0000');
+    };
+    const seen = new Map();
+    for (let i = 0; i < rows.length; i += 1) {
+        const key = keyOf(rows[i]);
+        if (!seen.has(key) || keepWhich === 'last')
+            seen.set(key, i);
+    }
+    const kept = new Set(seen.values());
+    const keep = [];
+    const remove = [];
+    for (let i = 0; i < rows.length; i += 1) {
+        if (kept.has(i))
+            keep.push(i);
+        else
+            remove.push(i);
+    }
+    return { keep, remove };
+}
+/** The rows that survive, in their original order, and how many went. */
+export function removeDuplicates(rows, toCells, options = {}) {
+    const report = findDuplicates(rows.map(toCells), options);
+    return {
+        rows: report.keep.map((i) => rows[i]),
+        removed: report.remove.length,
+    };
+}

package/dist/sheet/validation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Data validation, Excel's: a rule over some cells says what may be typed
+ * into them, and an entry that breaks it is stopped (or warned about)
+ * before it lands. Only typed entries are checked, as in Excel: paste, fill
+ * and the commands write what they are given.
+ *
+ * Rules keep their rectangles by position and move with an insert or
+ * delete; the last rule that covers a cell is the one that applies, which
+ * is what lets a later rule over a smaller block override an earlier one.
+ * Bounds and custom rules are text (a literal or a formula) evaluated in
+ * the sheet through the context the shell supplies, so `=$B$1` as a
+ * maximum follows B1.
+ */
+import { type CellValue } from './ast.js';
+import type { StructuralEdit } from './refs.js';
+import { type Rect } from './rects.js';
+export type ValidationAllow = 'any' | 'whole' | 'decimal' | 'list' | 'date' | 'textLength' | 'custom';
+export type ValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greater' | 'less' | 'greaterOrEqual' | 'lessOrEqual';
+/** Everything a rule is but where it applies: what the dialog hands back. */
+export type ValidationSpec = Omit<ValidationRule, 'id' | 'rects'>;
+export type ValidationRule = {
+    id: string;
+    rects: ReadonlyArray<Rect>;
+    allow: ValidationAllow;
+    /** For whole, decimal, date and textLength. Default between. */
+    operator?: ValidationOperator;
+    /** The bound, the value, the list source or the custom formula: a
+     *  literal, a comma list, or a formula starting with '='. */
+    value1?: string;
+    /** The upper bound of between / notBetween. */
+    value2?: string;
+    ignoreBlank: boolean;
+    /** List rules: show the arrow and the picker on the cell. */
+    inCellDropdown: boolean;
+    alert: {
+        style: 'stop' | 'warning';
+        title?: string;
+        message?: string;
+    };
+};
+/** How a rule reads the sheet: the shell wires the workbook in. */
+export type ValidationContext = {
+    /**
+     * A formula or a literal, evaluated in the sheet. With `entry`, the
+     * cell being checked reads as that text: Excel's custom rules refer to
+     * the cell they guard (`=A1>B1` on A1), and the entry is not written yet.
+     */
+    evaluate(text: string, entry?: {
+        row: number;
+        col: number;
+        text: string;
+    }): CellValue;
+    /** The values of a range reference or a name for one; null otherwise. */
+    range(text: string): CellValue[][] | null;
+};
+export type ValidationVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    style: 'stop' | 'warning';
+    title: string;
+    message: string;
+};
+/** Excel's own words when a rule has no message of its own. */
+export declare const DEFAULT_ALERT_MESSAGE = "This value doesn't match the data validation restrictions defined for this cell.";
+export declare const OPERATOR_LABELS: Record<ValidationOperator, string>;
+export declare function validationId(): string;
+/** The rule that applies to (r, c): the last one covering it. */
+export declare function ruleAt(rules: ReadonlyArray<ValidationRule>, r: number, c: number): ValidationRule | undefined;
+/** The rules touching any of the rectangles. */
+export declare function rulesIn(rules: ReadonlyArray<ValidationRule>, rects: ReadonlyArray<Rect>): ValidationRule[];
+/** A date as milliseconds: an ISO text, or an Excel serial. Null otherwise. */
+export declare function dateValue(v: CellValue): number | null;
+/**
+ * The choices a list rule offers: a comma list as written, or the cells of
+ * a range (or a name for one), blanks left out, as text.
+ */
+export declare function listChoices(rule: ValidationRule, ctx: ValidationContext): string[];
+/**
+ * Whether `text`, typed into (row, col), passes the rule. The verdict
+ * carries the alert to show when it does not.
+ */
+export declare function checkEntry(rule: ValidationRule, text: string, at: {
+    row: number;
+    col: number;
+}, ctx: ValidationContext): ValidationVerdict;
+/** The rules after an insert or delete. */
+export declare function shiftValidation(rules: ReadonlyArray<ValidationRule>, edit: StructuralEdit): ValidationRule[];
+/** The rules with the rectangles cut out of them: Excel's Clear All. */
+export declare function removeValidation(rules: ReadonlyArray<ValidationRule>, rects: ReadonlyArray<Rect>): ValidationRule[];
+/** A short description for a rule, the way Excel's dialog title reads it. */
+export declare function describeRule(rule: ValidationRule): string;