@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/validation.js

@@ -0,0 +1,241 @@
+/**
+ * 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 { isError } from './ast.js';
+import { toText } from './coerce.js';
+import { parseEntry } from './entry.js';
+import { translateFormula } from './refs.js';
+import { rectContains, shiftRects, subtractRect, rectsIntersect } from './rects.js';
+/** Excel's own words when a rule has no message of its own. */
+export const DEFAULT_ALERT_MESSAGE = "This value doesn't match the data validation restrictions defined for this cell.";
+export const OPERATOR_LABELS = {
+    between: 'between',
+    notBetween: 'not between',
+    equal: 'equal to',
+    notEqual: 'not equal to',
+    greater: 'greater than',
+    less: 'less than',
+    greaterOrEqual: 'greater than or equal to',
+    lessOrEqual: 'less than or equal to',
+};
+let nextId = 1;
+export function validationId() {
+    nextId += 1;
+    return `v${Date.now().toString(36)}${nextId}`;
+}
+/** The rule that applies to (r, c): the last one covering it. */
+export function ruleAt(rules, r, c) {
+    for (let i = rules.length - 1; i >= 0; i -= 1) {
+        const rule = rules[i];
+        if (rule.rects.some((rect) => rectContains(rect, r, c)))
+            return rule;
+    }
+    return undefined;
+}
+/** The rules touching any of the rectangles. */
+export function rulesIn(rules, rects) {
+    return rules.filter((rule) => rule.rects.some((a) => rects.some((b) => rectsIntersect(a, b))));
+}
+/** What the typed text is worth: a formula's result, or the literal coerced. */
+function entered(text, ctx) {
+    const t = text.trim();
+    if (t.startsWith('='))
+        return ctx.evaluate(t);
+    const parsed = parseEntry(t);
+    const plain = parsed ? parsed.value : t;
+    const n = Number(plain);
+    if (plain !== '' && Number.isFinite(n))
+        return n;
+    const upper = plain.toUpperCase();
+    if (upper === 'TRUE')
+        return true;
+    if (upper === 'FALSE')
+        return false;
+    return plain;
+}
+/** A date as milliseconds: an ISO text, or an Excel serial. Null otherwise. */
+export function dateValue(v) {
+    if (typeof v === 'number')
+        return Date.UTC(1899, 11, 30) + v * 86400000;
+    if (typeof v !== 'string' || !v.trim())
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}/.test(v.trim()))
+        return null;
+    const ms = Date.parse(v.trim().length === 10 ? `${v.trim()}T00:00:00Z` : v.trim());
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * A bound or a source, moved from the rule's top-left cell to the cell being
+ * checked, as Excel moves a relative reference in a rule: `=A2` as the
+ * minimum of G2:G17 reads A5 on G5, while `=$B$1` stays put.
+ */
+function relative(text, rule, at) {
+    if (text === undefined || !text.trim().startsWith('='))
+        return text;
+    const origin = rule.rects[0];
+    if (!origin)
+        return text;
+    return String(translateFormula(text.trim(), at.row - origin[0], at.col - origin[1]));
+}
+function bound(text, ctx, as) {
+    if (text === undefined || text.trim() === '')
+        return null;
+    const v = ctx.evaluate(text);
+    if (isError(v))
+        return null;
+    if (as === 'date')
+        return dateValue(v);
+    if (typeof v === 'boolean')
+        return null;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function compareTo(x, op, a, b) {
+    if (a === null)
+        return false;
+    switch (op) {
+        case 'between': return b !== null && x >= Math.min(a, b) && x <= Math.max(a, b);
+        case 'notBetween': return b !== null && (x < Math.min(a, b) || x > Math.max(a, b));
+        case 'equal': return x === a;
+        case 'notEqual': return x !== a;
+        case 'greater': return x > a;
+        case 'less': return x < a;
+        case 'greaterOrEqual': return x >= a;
+        case 'lessOrEqual': return x <= a;
+    }
+}
+/**
+ * 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 function listChoices(rule, ctx) {
+    const source = (rule.value1 ?? '').trim();
+    if (!source)
+        return [];
+    if (source.startsWith('=')) {
+        const grid = ctx.range(source);
+        if (grid) {
+            const out = [];
+            for (const row of grid)
+                for (const v of row) {
+                    if (v === '' || v == null)
+                        continue;
+                    out.push(isError(v) ? v.error : toText(v));
+                }
+            return out;
+        }
+        const v = ctx.evaluate(source);
+        return isError(v) ? [] : [toText(v)];
+    }
+    return source.split(',').map((s) => s.trim()).filter((s) => s !== '');
+}
+/**
+ * Whether `text`, typed into (row, col), passes the rule. The verdict
+ * carries the alert to show when it does not.
+ */
+export function checkEntry(rule, text, at, ctx) {
+    const fail = () => ({
+        ok: false,
+        style: rule.alert.style,
+        title: rule.alert.title?.trim() || 'Data validation',
+        message: rule.alert.message?.trim() || DEFAULT_ALERT_MESSAGE,
+    });
+    if (rule.allow === 'any')
+        return { ok: true };
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return rule.ignoreBlank ? { ok: true } : fail();
+    const op = rule.operator ?? 'between';
+    switch (rule.allow) {
+        case 'whole':
+        case 'decimal': {
+            const v = entered(text, ctx);
+            if (typeof v !== 'number' || !Number.isFinite(v))
+                return fail();
+            if (rule.allow === 'whole' && !Number.isInteger(v))
+                return fail();
+            return compareTo(v, op, bound(relative(rule.value1, rule, at), ctx, 'number'), bound(relative(rule.value2, rule, at), ctx, 'number')) ? { ok: true } : fail();
+        }
+        case 'date': {
+            const ms = dateValue(entered(text, ctx));
+            if (ms === null)
+                return fail();
+            return compareTo(ms, op, bound(relative(rule.value1, rule, at), ctx, 'date'), bound(relative(rule.value2, rule, at), ctx, 'date')) ? { ok: true } : fail();
+        }
+        case 'textLength': {
+            const v = entered(text, ctx);
+            const length = isError(v) ? 0 : toText(v).length;
+            return compareTo(length, op, bound(relative(rule.value1, rule, at), ctx, 'number'), bound(relative(rule.value2, rule, at), ctx, 'number')) ? { ok: true } : fail();
+        }
+        case 'list': {
+            // Excel matches a list entry without regard to case.
+            const v = entered(text, ctx);
+            const shown = isError(v) ? v.error : toText(v);
+            const needle = shown.toLowerCase();
+            return listChoices(rule, ctx).some((choice) => choice.toLowerCase() === needle) ? { ok: true } : fail();
+        }
+        case 'custom': {
+            const formula = (rule.value1 ?? '').trim();
+            if (!formula)
+                return fail();
+            // The formula is written for the rule's top-left cell and moves with
+            // the cell it checks, as a copied formula would.
+            const origin = rule.rects[0];
+            const source = formula.startsWith('=') ? formula : `=${formula}`;
+            const moved = origin
+                ? String(translateFormula(source, at.row - origin[0], at.col - origin[1]))
+                : source;
+            const v = ctx.evaluate(moved, { row: at.row, col: at.col, text });
+            if (isError(v))
+                return fail();
+            const truthy = typeof v === 'boolean' ? v : typeof v === 'number' ? v !== 0 : false;
+            return truthy ? { ok: true } : fail();
+        }
+        default:
+            return { ok: true };
+    }
+}
+/** The rules after an insert or delete. */
+export function shiftValidation(rules, edit) {
+    return shiftRects(rules, edit);
+}
+/** The rules with the rectangles cut out of them: Excel's Clear All. */
+export function removeValidation(rules, rects) {
+    const out = [];
+    for (const rule of rules) {
+        let kept = [...rule.rects];
+        for (const hole of rects)
+            kept = kept.flatMap((rect) => subtractRect(rect, hole));
+        if (kept.length)
+            out.push({ ...rule, rects: kept });
+    }
+    return out;
+}
+/** A short description for a rule, the way Excel's dialog title reads it. */
+export function describeRule(rule) {
+    const op = OPERATOR_LABELS[rule.operator ?? 'between'];
+    const v1 = rule.value1 ?? '';
+    const v2 = rule.value2 ?? '';
+    const range = (rule.operator ?? 'between') === 'between' || rule.operator === 'notBetween'
+        ? `${v1} and ${v2}`
+        : v1;
+    switch (rule.allow) {
+        case 'any': return 'Any value';
+        case 'whole': return `Whole number ${op} ${range}`;
+        case 'decimal': return `Decimal ${op} ${range}`;
+        case 'date': return `Date ${op} ${range}`;
+        case 'textLength': return `Text length ${op} ${range}`;
+        case 'list': return `List: ${v1}`;
+        case 'custom': return `Custom: ${v1}`;
+    }
+}

package/dist/sheet/workbook.d.ts

@@ -0,0 +1,72 @@
+import { type SheetFunction } from './functions.js';
+import { isError, type CellValue } from './ast.js';
+import { type SheetNames } from './names.js';
+import { type StructuralEdit } from './refs.js';
+export type SheetData = {
+    name: string;
+    /** Row-major raw text. Ragged is fine; a missing cell reads as empty. */
+    cells: string[][];
+};
+export type WorkbookOptions = {
+    /** Extra functions merged over the built-ins. */
+    functions?: Record<string, SheetFunction>;
+    /** Fires after a recalculation, with the cells whose value changed. */
+    onRecalc?(changed: ReadonlyArray<{
+        sheet: string;
+        row: number;
+        col: number;
+        value: CellValue;
+    }>): void;
+};
+/** One cell read as text that has not been written: what a validation rule checks. */
+export type CellOverride = {
+    row: number;
+    col: number;
+    text: string;
+};
+export type Workbook = {
+    readonly sheets: ReadonlyArray<string>;
+    readonly active: string;
+    readonly names: SheetNames;
+    setActive(name: string): void;
+    addSheet(name?: string, at?: number): string;
+    removeSheet(name: string): boolean;
+    renameSheet(from: string, to: string): boolean;
+    moveSheet(name: string, to: number): boolean;
+    /** The raw text of a cell: the formula as typed, or the literal. */
+    getRaw(sheet: string, row: number, col: number): string;
+    /** Write raw text and recalculate whatever depends on it. */
+    setRaw(sheet: string, row: number, col: number, text: string): void;
+    /** The computed value. */
+    getValue(sheet: string, row: number, col: number): CellValue;
+    /** Every cell of a sheet, computed. */
+    snapshot(sheet: string): CellValue[][];
+    /**
+     * What `text` would be worth in a cell of `sheet`, without putting it in
+     * one: a formula is evaluated there (names and other sheets included), a
+     * literal is coerced the way a typed one is. Data validation checks its
+     * bounds and custom rules through this.
+     */
+    evaluateText(sheet: string, text: string, override?: CellOverride): CellValue;
+    /**
+     * The values of a range reference, or of a name that refers to one, as a
+     * grid; null when `text` is not a reference. A list source.
+     */
+    evaluateRange(sheet: string, text: string): CellValue[][] | null;
+    /** Apply a structural edit to one sheet, rewriting every formula in the
+     *  WORKBOOK that pointed into it. */
+    applyStructuralEdit(sheet: string, edit: StructuralEdit): void;
+    /** Recompute everything. Rarely needed; `setRaw` keeps itself current. */
+    recalculate(): void;
+    rowCount(sheet: string): number;
+    colCount(sheet: string): number;
+    serialize(): {
+        sheets: SheetData[];
+        active: string;
+        names: Record<string, string>;
+    };
+};
+/** A name Excel would accept for a sheet. */
+export declare function isValidSheetName(name: string): boolean;
+export declare function createWorkbook(initial?: ReadonlyArray<SheetData>, options?: WorkbookOptions): Workbook;
+export { isError };