@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/address.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A1 addressing, with absolute and relative parts kept apart.
+ *
+ * Every demo copy of this engine does `part.replace(/\$/g, '')` and then treats
+ * what is left as relative, so `$A$1` parses and evaluates as `A1`. Nothing
+ * notices while nothing translates a formula. The moment fill-down, copy/paste
+ * or insert-row exists, `=$A$1*B2` copied down starts reading the wrong cell
+ * and quietly returns a plausible wrong number, which is the worst failure mode
+ * a spreadsheet has.
+ *
+ * So `$` is structure here, not noise: `parseA1` reports which halves were
+ * pinned, and `refs.ts` is the only module allowed to move the unpinned ones.
+ *
+ * Rows and columns are 0-based internally (`A1` is `{ row: 0, col: 0 }`) and
+ * 1-based on the wire, which is the same convention the grid's selection model
+ * uses so nothing has to convert at the boundary.
+ */
+/** A parsed cell reference. `row: null` means a whole-column ref (`A:A`). */
+export type CellRef = {
+    col: number;
+    colAbs: boolean;
+    /** null for a column-only reference. */
+    row: number | null;
+    rowAbs: boolean;
+    /** null means "the sheet the formula lives on". */
+    sheet: string | null;
+};
+/** 0-based column index to letters: 0 -> A, 25 -> Z, 26 -> AA. */
+export declare function colToLetters(col: number): string;
+/** Letters to a 0-based column index. Returns -1 for anything unparseable. */
+export declare function lettersToCol(letters: string): number;
+/**
+ * Parse one reference part: `A1`, `$A$1`, `A$1`, `$A1`, or a bare column `A`.
+ * Returns null when the text is not a reference at all, which is how the
+ * tokenizer tells a reference from a bare name.
+ */
+export declare function parseA1(text: string, sheet?: string | null): CellRef | null;
+/** Render a reference back to A1, `$` included, sheet prefix and all. */
+export declare function formatA1(ref: CellRef): string;
+/** A sheet name needs quoting unless it is a bare word. */
+export declare function quoteSheet(name: string): string;
+/** True when the reference points outside a sheet of this size. */
+export declare function isOutOfBounds(ref: CellRef, rowCount: number, colCount: number): boolean;

package/dist/sheet/address.js

@@ -0,0 +1,81 @@
+/**
+ * A1 addressing, with absolute and relative parts kept apart.
+ *
+ * Every demo copy of this engine does `part.replace(/\$/g, '')` and then treats
+ * what is left as relative, so `$A$1` parses and evaluates as `A1`. Nothing
+ * notices while nothing translates a formula. The moment fill-down, copy/paste
+ * or insert-row exists, `=$A$1*B2` copied down starts reading the wrong cell
+ * and quietly returns a plausible wrong number, which is the worst failure mode
+ * a spreadsheet has.
+ *
+ * So `$` is structure here, not noise: `parseA1` reports which halves were
+ * pinned, and `refs.ts` is the only module allowed to move the unpinned ones.
+ *
+ * Rows and columns are 0-based internally (`A1` is `{ row: 0, col: 0 }`) and
+ * 1-based on the wire, which is the same convention the grid's selection model
+ * uses so nothing has to convert at the boundary.
+ */
+/** 0-based column index to letters: 0 -> A, 25 -> Z, 26 -> AA. */
+export function colToLetters(col) {
+    if (!Number.isInteger(col) || col < 0)
+        return '';
+    let n = col;
+    let out = '';
+    while (n >= 0) {
+        out = String.fromCharCode(65 + (n % 26)) + out;
+        n = Math.floor(n / 26) - 1;
+    }
+    return out;
+}
+/** Letters to a 0-based column index. Returns -1 for anything unparseable. */
+export function lettersToCol(letters) {
+    if (!letters || !/^[A-Za-z]+$/.test(letters))
+        return -1;
+    let col = 0;
+    for (const ch of letters.toUpperCase())
+        col = col * 26 + (ch.charCodeAt(0) - 64);
+    return col - 1;
+}
+const REF_RE = /^(\$?)([A-Za-z]+)(?:(\$?)(\d+))?$/;
+/**
+ * Parse one reference part: `A1`, `$A$1`, `A$1`, `$A1`, or a bare column `A`.
+ * Returns null when the text is not a reference at all, which is how the
+ * tokenizer tells a reference from a bare name.
+ */
+export function parseA1(text, sheet = null) {
+    const m = REF_RE.exec(text);
+    if (!m)
+        return null;
+    const col = lettersToCol(m[2]);
+    if (col < 0)
+        return null;
+    const rowText = m[4];
+    if (rowText === undefined) {
+        return { col, colAbs: m[1] === '$', row: null, rowAbs: false, sheet };
+    }
+    const row = Number(rowText) - 1;
+    // Row 0 does not exist in A1 notation; `A0` is a name, not a reference.
+    if (!Number.isInteger(row) || row < 0)
+        return null;
+    return { col, colAbs: m[1] === '$', row, rowAbs: m[3] === '$', sheet };
+}
+/** Render a reference back to A1, `$` included, sheet prefix and all. */
+export function formatA1(ref) {
+    const col = `${ref.colAbs ? '$' : ''}${colToLetters(ref.col)}`;
+    const cell = ref.row === null ? col : `${col}${ref.rowAbs ? '$' : ''}${ref.row + 1}`;
+    if (ref.sheet === null)
+        return cell;
+    return `${quoteSheet(ref.sheet)}!${cell}`;
+}
+/** A sheet name needs quoting unless it is a bare word. */
+export function quoteSheet(name) {
+    return /^[A-Za-z_][A-Za-z0-9_.]*$/.test(name) ? name : `'${name.replace(/'/g, "''")}'`;
+}
+/** True when the reference points outside a sheet of this size. */
+export function isOutOfBounds(ref, rowCount, colCount) {
+    if (ref.col < 0 || ref.col >= colCount)
+        return true;
+    if (ref.row === null)
+        return false;
+    return ref.row < 0 || ref.row >= rowCount;
+}

package/dist/sheet/ast.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The formula AST and the error vocabulary, in their own module so the
+ * tokenizer, parser, evaluator and the reference rewriter can all import the
+ * shapes without importing each other.
+ */
+import type { CellRef } from './address.js';
+export type SheetError = '#REF!' | '#CYCLE!' | '#DIV/0!' | '#VALUE!' | '#NAME?' | '#NUM!' | '#N/A' | '#PARSE!' | '#SPILL!' | '#CALC!'
+/** Excel's empty intersection. Nothing here produces it; a file can
+ *  carry it, and a formula can name it, so it is one of the values. */
+ | '#NULL!';
+/** A computed cell value. Errors are values, not exceptions, once evaluation
+ *  finishes - that is what lets `=IFERROR(A1, 0)` see one. */
+export type CellValue = string | number | boolean | {
+    error: SheetError;
+};
+export declare function isError(v: CellValue): v is {
+    error: SheetError;
+};
+export declare function err(code: SheetError): {
+    error: SheetError;
+};
+/** The error a typed text stands for, or null when it is ordinary text. */
+export declare function typedError(text: string): {
+    error: SheetError;
+} | null;
+/** Thrown during evaluation and caught at the boundary, where it becomes a
+ *  value. Carrying the code on a real Error keeps stack traces useful in dev
+ *  without the evaluator having to thread a result type through every branch. */
+export declare class FormulaError extends Error {
+    readonly code: SheetError;
+    constructor(code: SheetError);
+}
+export type Node = {
+    k: 'num';
+    v: number;
+} | {
+    k: 'str';
+    v: string;
+} | {
+    k: 'bool';
+    v: boolean;
+}
+/** An error written INTO a formula: `=#N/A`, `=IFERROR(A1, #N/A)`. Excel
+ *  takes one as a value, and a file from Excel, Google Sheets or
+ *  LibreOffice can carry an error cell as a formula that is only this. */
+ | {
+    k: 'err';
+    v: SheetError;
+}
+/** A single cell. `ref.row` is never null here; a column-only reference
+ *  parses as a range instead. */
+ | {
+    k: 'ref';
+    ref: CellRef;
+}
+/**
+ * The spilled-range operator, `A1#`: the rectangle a dynamic array
+ * anchored at `ref` currently spills into. Like a table reference, it is
+ * NOT resolved to a range here - the rectangle depends on how far the
+ * array spills right now, which changes as the array grows, so it is
+ * resolved against the workbook at evaluation. `ref.row` is never null.
+ */
+ | {
+    k: 'spill';
+    ref: CellRef;
+}
+/** A rectangle. Either end's row may be null, meaning a whole-column ref
+ *  that runs to the last used row of the sheet. */
+ | {
+    k: 'range';
+    from: CellRef;
+    to: CellRef;
+}
+/**
+ * A 3D reference: `Sheet1:Sheet3!A1` or `Jan:Dec!B5:B10`. The same cell or
+ * rectangle on every sheet from `sheetFrom` to `sheetTo` in tab order,
+ * inclusive. `from`/`to` carry no sheet of their own (the sheets are the
+ * range); resolved against the workbook's sheet order at evaluation, so a
+ * tab inserted between the two joins the sum, as Excel's does. */
+ | {
+    k: 'ref3d';
+    sheetFrom: string;
+    sheetTo: string;
+    from: CellRef;
+    to: CellRef;
+}
+/** A defined name (`=Tax`), resolved against the workbook at evaluation. */
+ | {
+    k: 'name';
+    name: string;
+}
+/**
+ * A structured reference: `Orders[Amount]`, `[@Amount]`, `Orders[#Totals]`.
+ *
+ * Deliberately NOT resolved to a range here. The range a table reference
+ * means depends on how many rows the table has right now, and the AST is
+ * cached across the edits that change that. Resolving at parse time is how
+ * a total silently stops covering rows added after it was typed, which is
+ * the exact problem tables exist to fix.
+ */
+ | {
+    k: 'table';
+    /** null for the unqualified `[Amount]` form, which only means
+     *  something inside a table. */
+    table: string | null;
+    /** null when the reference names no column, e.g. `Orders[#All]`. */
+    column: string | null;
+    /** The far end of a column span: `Orders[[Qty]:[Amount]]`. */
+    columnTo?: string | null;
+    specifier: '#All' | '#Data' | '#Headers' | '#Totals' | '#ThisRow';
+} | {
+    k: 'unary';
+    op: '-' | '+' | '%';
+    arg: Node;
+} | {
+    k: 'binary';
+    op: BinaryOp;
+    left: Node;
+    right: Node;
+} | {
+    k: 'fn';
+    name: string;
+    args: Node[];
+}
+/** An omitted argument: the gap in `PMT(rate, nper, pv, , 1)`. Reads as a
+ *  blank, so a function sees its default the way it does when the
+ *  argument is simply left off the end. */
+ | {
+    k: 'empty';
+};
+export type BinaryOp = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '>' | '<=' | '>=';
+/** Binding power. Comparison loosest, then concat, then arithmetic. */
+export declare const PRECEDENCE: Record<BinaryOp, number>;
+/** Walk every node, parents before children. */
+export declare function visit(node: Node, fn: (n: Node) => void): void;
+/** Rebuild the tree with `fn` applied to every node, deepest first. Used by
+ *  the reference rewriter, which must not mutate a cached AST in place. */
+export declare function mapNode(node: Node, fn: (n: Node) => Node): Node;

package/dist/sheet/ast.js

@@ -0,0 +1,70 @@
+export function isError(v) {
+    return typeof v === 'object' && v !== null && 'error' in v;
+}
+export function err(code) {
+    return { error: code };
+}
+/** The error codes a user can type into a cell. Excel stores what is typed
+ *  as the error itself, so =ISNA(A1) over a cell holding #N/A is TRUE.
+ *  #PARSE! is ours, not Excel's, and no one types it. */
+const TYPED_ERRORS = [
+    '#REF!', '#DIV/0!', '#VALUE!', '#NAME?', '#NUM!', '#N/A', '#SPILL!', '#CALC!', '#CYCLE!', '#NULL!',
+];
+/** The error a typed text stands for, or null when it is ordinary text. */
+export function typedError(text) {
+    if (!text.startsWith('#'))
+        return null;
+    const upper = text.toUpperCase();
+    const found = TYPED_ERRORS.find((code) => code === upper);
+    return found ? { error: found } : null;
+}
+/** Thrown during evaluation and caught at the boundary, where it becomes a
+ *  value. Carrying the code on a real Error keeps stack traces useful in dev
+ *  without the evaluator having to thread a result type through every branch. */
+export class FormulaError extends Error {
+    constructor(code) {
+        super(code);
+        this.name = 'FormulaError';
+        this.code = code;
+    }
+}
+/** Binding power. Comparison loosest, then concat, then arithmetic. */
+export const PRECEDENCE = {
+    '=': 1, '<>': 1, '<': 1, '>': 1, '<=': 1, '>=': 1,
+    '&': 2,
+    '+': 3, '-': 3,
+    '*': 4, '/': 4,
+    '^': 5,
+};
+/** Walk every node, parents before children. */
+export function visit(node, fn) {
+    fn(node);
+    switch (node.k) {
+        case 'unary':
+            visit(node.arg, fn);
+            break;
+        case 'binary':
+            visit(node.left, fn);
+            visit(node.right, fn);
+            break;
+        case 'fn':
+            for (const a of node.args)
+                visit(a, fn);
+            break;
+        default: break;
+    }
+}
+/** Rebuild the tree with `fn` applied to every node, deepest first. Used by
+ *  the reference rewriter, which must not mutate a cached AST in place. */
+export function mapNode(node, fn) {
+    switch (node.k) {
+        case 'unary':
+            return fn({ ...node, arg: mapNode(node.arg, fn) });
+        case 'binary':
+            return fn({ ...node, left: mapNode(node.left, fn), right: mapNode(node.right, fn) });
+        case 'fn':
+            return fn({ ...node, args: node.args.map((a) => mapNode(a, fn)) });
+        default:
+            return fn(node);
+    }
+}

package/dist/sheet/auto-filter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Excel's AutoFilter: arrows on the header row of a region, each opening a
+ * menu of the column's values to tick and untick, or a condition (equals,
+ * greater than, contains, between...), and the rows that fail fold away.
+ * The rows are hidden through the grid's collapsed rows, kept apart from
+ * the rows the user hid by hand so Unhide and the saved document see
+ * only those.
+ *
+ * This module is the pure part: the state, the values a column offers,
+ * which rows a state hides, and how the state moves with an insert or
+ * delete. Conditions run through the grid's own Excel-filter compiler, so
+ * the operator semantics are the ones the grid's filter row has.
+ */
+import { type ExcelFilterOperator } from '@svgrid/grid/filtering';
+import { type CellValue } from './ast.js';
+import type { StructuralEdit } from './refs.js';
+import { type Rect } from './rects.js';
+export type FilterCondition = {
+    op: ExcelFilterOperator;
+    value?: string;
+    valueTo?: string;
+};
+/** Excel's Date Filters: a period around today, or a bound typed as a date. */
+export type DatePeriod = 'equals' | 'before' | 'after' | 'between' | 'tomorrow' | 'today' | 'yesterday' | 'nextWeek' | 'thisWeek' | 'lastWeek' | 'nextMonth' | 'thisMonth' | 'lastMonth' | 'nextQuarter' | 'thisQuarter' | 'lastQuarter' | 'nextYear' | 'thisYear' | 'lastYear' | 'yearToDate';
+export type ColumnFilter = {
+    kind: 'values';
+    /** Display texts left unticked; '' stands for the blanks. */
+    excluded: string[];
+    /** The texts ticked, from a file that lists what is IN (Excel and ODF
+     *  both do): wins over `excluded` while set. The menu writes the
+     *  exclusion form back the next time the filter is applied. */
+    included?: string[];
+} | {
+    kind: 'condition';
+    first: FilterCondition;
+    join?: 'and' | 'or';
+    second?: FilterCondition;
+}
+/** A date period; `value` and `valueTo` are `yyyy-mm-dd` for the typed bounds. */
+ | {
+    kind: 'date';
+    period: DatePeriod;
+    value?: string;
+    valueTo?: string;
+}
+/** Excel's Filter by Color: the cell's fill, or null for the cells with none. */
+ | {
+    kind: 'color';
+    fill: string | null;
+}
+/** Excel's Top 10: the `count` largest (or smallest) values, or that percent of the rows. */
+ | {
+    kind: 'top';
+    top: boolean;
+    count: number;
+    percent?: boolean;
+};
+/** What a filter reads beside the cell's value and text. */
+export type FilterContext = {
+    /** The cell's fill, its own or a conditional format's; null when none. */
+    fillAt?: (r: number, c: number) => string | null;
+    /** The day the date periods count from. */
+    today?: Date;
+};
+export type AutoFilterState = {
+    /** The region, header row first. */
+    range: Rect;
+    /** Filters by column index; a column absent here shows every row. */
+    filters: Record<number, ColumnFilter>;
+};
+export type FilterValue = {
+    text: string;
+    count: number;
+    numeric: number | null;
+};
+/**
+ * The values a column offers, each once with its count: numbers first
+ * in order, then text A to Z, the blanks last. `rowVisible` leaves out the
+ * rows other columns' filters hide, as Excel's list does.
+ */
+export declare function distinctValues(state: AutoFilterState, col: number, valueAt: (r: number, c: number) => CellValue, displayAt: (r: number, c: number) => string, rowVisible?: (r: number) => boolean): FilterValue[];
+/**
+ * The first and last day of a period, as UTC day-start milliseconds,
+ * counted from `today`. Weeks run Sunday to Saturday; quarters are the
+ * calendar's. The typed periods read `value` and `valueTo`.
+ */
+export declare function datePeriodBounds(filter: Extract<ColumnFilter, {
+    kind: 'date';
+}>, today?: Date): [from: number, to: number] | null;
+/**
+ * Whether a row passes one column's filter. A Top 10 filter needs the
+ * whole column to know its threshold, which `hiddenRowsFor` works out and
+ * passes as `topPasses`; on its own the filter passes everything.
+ */
+export declare function passesFilter(filter: ColumnFilter, value: CellValue, display: string, extra?: {
+    fill?: string | null;
+    today?: Date;
+    topPasses?: (value: CellValue) => boolean;
+}): boolean;
+/**
+ * The rows the state hides: every row of the region under the header
+ * that fails a column's filter. Blanks past the region's edge are not in
+ * it, as Excel's region is what was filtered.
+ */
+export declare function hiddenRowsFor(state: AutoFilterState | null, valueAt: (r: number, c: number) => CellValue, displayAt: (r: number, c: number) => string, ctx?: FilterContext): Set<number>;
+/** The fills a column's cells carry, each once, first seen first; null
+ *  stands for the cells with none. Excel's Filter by Color list. */
+export declare function distinctFills(state: AutoFilterState, col: number, fillAt: (r: number, c: number) => string | null): Array<string | null>;
+/** Whether a column reads as dates: every cell with something in it holds one. */
+export declare function isDateColumn(values: ReadonlyArray<FilterValue>): boolean;
+/** Whether any column is filtered. */
+export declare function isFiltering(state: AutoFilterState | null): boolean;
+/** The state with one column's filter set, or cleared with null. */
+export declare function withColumnFilter(state: AutoFilterState, col: number, filter: ColumnFilter | null): AutoFilterState;
+/** A values filter from the ticked list, or null when everything is ticked. */
+export declare function valuesFilter(all: ReadonlyArray<string>, ticked: ReadonlySet<string>): ColumnFilter | null;
+/** The state after an insert or delete: the region moves, the filters follow their columns. */
+export declare function shiftAutoFilter(state: AutoFilterState | null, edit: StructuralEdit): AutoFilterState | null;
+/** A filter in words, for the menu's heading. */
+export declare function describeFilter(filter: ColumnFilter): string;