@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/tokenize.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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, type SheetError } 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: 'err';
+    v: SheetError;
+} | {
+    t: 'ref';
+    ref: CellRef;
+}
+/** The spilled-range operator `A1#`: the anchor a spill is read from. */
+ | {
+    t: 'spill';
+    ref: CellRef;
+} | {
+    t: 'range';
+    from: CellRef;
+    to: CellRef;
+}
+/** A 3D reference `Sheet1:Sheet3!A1`: the cell or rectangle on every sheet
+ *  in the tab range. `from`/`to` carry no sheet of their own. */
+ | {
+    t: 'range3d';
+    sheetFrom: string;
+    sheetTo: string;
+    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[];

package/dist/sheet/tokenize.js

@@ -0,0 +1,355 @@
+/**
+ * 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',
+};
+/** The error values a formula can name, longest first so #NUM! cannot win
+ *  the prefix of a longer code. */
+const ERROR_LITERAL = /^(#NULL!|#DIV\/0!|#VALUE!|#NAME\?|#NUM!|#N\/A|#REF!|#SPILL!|#CALC!|#CYCLE!)/i;
+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;
+        }
+        // `A1#` is the spilled-range operator: the `#` binds to the reference
+        // right before it, with no space between, and names the whole array the
+        // cell anchors. A `#` that starts an error literal is handled elsewhere;
+        // one sitting immediately after a cell is only ever this.
+        if (src[i] === '#') {
+            i += 1;
+            out.push({ t: 'spill', ref: left });
+            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();
+            // A 3D reference: Sheet1:Sheet3!A1, the same cell on every sheet in the
+            // tab range. The `!` after the second name is what tells it apart from
+            // an ordinary A1:B2 range, so on anything else this backtracks.
+            if (src[i] === ':') {
+                const save = i;
+                i += 1;
+                const second = readWord();
+                if (second !== '' && src[i] === '!') {
+                    i += 1;
+                    const from = parseA1(readWord(), null);
+                    if (!from || from.row === null)
+                        throw new FormulaError('#PARSE!');
+                    let to = from;
+                    if (src[i] === ':') {
+                        i += 1;
+                        const right = parseA1(readWord(), null);
+                        if (!right || right.row === null)
+                            throw new FormulaError('#PARSE!');
+                        to = right;
+                    }
+                    out.push({ t: 'range3d', sheetFrom: word, sheetTo: second, from, to });
+                    continue;
+                }
+                i = save;
+            }
+            // Unquoted sheet name: Orders!A1
+            if (src[i] === '!') {
+                i += 1;
+                pushWord(readWord(), word);
+                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 -
+            // TRUE and FALSE included, since Excel has TRUE() and FALSE() as
+            // functions and that is how LibreOffice writes a boolean cell.
+            if (src[skipSpace()] === '(') {
+                out.push({ t: 'fn', v: upper });
+                continue;
+            }
+            if (upper === 'TRUE') {
+                out.push({ t: 'bool', v: true });
+                continue;
+            }
+            if (upper === 'FALSE') {
+                out.push({ t: 'bool', v: false });
+                continue;
+            }
+            pushWord(word, null);
+            continue;
+        }
+        // An error written into the formula: =#N/A, =IFERROR(A1, #REF!). Excel
+        // reads one as a value, and a file can carry an error cell as a formula
+        // that is nothing else.
+        if (ch === '#') {
+            const code = ERROR_LITERAL.exec(src.slice(i));
+            if (code) {
+                out.push({ t: 'err', v: code[0].toUpperCase() });
+                i += code[0].length;
+                continue;
+            }
+            throw new FormulaError('#PARSE!');
+        }
+        // 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,
+    };
+}