@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/validation.js

@@ -239,3 +239,40 @@ export function describeRule(rule) {
         case 'custom': return `Custom: ${v1}`;
     }
 }
+/**
+ * Excel's Circle Invalid Data: every cell under a rule whose current text
+ * breaks it. Blank cells count when the rule says they do. The rectangles
+ * are clipped to `rows` by `cols`, the sheet's used extent, so a rule over
+ * a whole column costs the cells that hold something.
+ */
+export function invalidCells(rules, ctx, rawAt, rows, cols) {
+    const out = [];
+    const seen = new Set();
+    for (const rule of rules) {
+        if (rule.allow === 'any')
+            continue;
+        for (const [r1, c1, r2, c2] of rule.rects) {
+            const rowEnd = Math.min(r2, rows - 1);
+            const colEnd = Math.min(c2, cols - 1);
+            for (let r = Math.max(0, r1); r <= rowEnd; r += 1) {
+                for (let c = Math.max(0, c1); c <= colEnd; c += 1) {
+                    const key = r * 1048576 + c;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    // The rule that applies is the last one covering the cell, which
+                    // may not be this one.
+                    const applies = ruleAt(rules, r, c);
+                    if (!applies || applies.allow === 'any')
+                        continue;
+                    const text = rawAt(r, c);
+                    if (text.trim() === '' && applies.ignoreBlank)
+                        continue;
+                    if (!checkEntry(applies, text, { row: r, col: c }, ctx).ok)
+                        out.push({ row: r, col: c });
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/sheet/workbook.d.ts

@@ -1,12 +1,40 @@
 import { type SheetFunction } from './functions.js';
 import { isError, type CellValue } from './ast.js';
+import { type TableRegion, type TableRegistry } from './tables.js';
 import { type SheetNames } from './names.js';
-import { type StructuralEdit } from './refs.js';
+import { type CellMove, type StructuralEdit } from './refs.js';
+import { type SheetEngine } from './engine.js';
 export type SheetData = {
     name: string;
     /** Row-major raw text. Ragged is fine; a missing cell reads as empty. */
     cells: string[][];
 };
+/**
+ * Excel's Enable iterative calculation, under File > Options > Formulas.
+ *
+ * A circular reference is normally an error: every cell in the loop shows
+ * #CYCLE!. Some models are written as one on purpose, though, because the
+ * answer is a fixed point rather than a mistake: a bonus that is a share of
+ * the profit the bonus is subtracted from, an interest charge on a balance
+ * the charge is added to. Excel solves those by running the loop over and
+ * over from the values it last had, and stopping when either the answer
+ * stops moving or the passes run out.
+ */
+export type IterationSettings = {
+    /** Off by default, which is Excel's default and keeps a cycle an error. */
+    enabled: boolean;
+    /** Passes before the answer is taken as it stands. Excel's default is 100. */
+    maxIterations: number;
+    /** The largest move that still counts as settled. Excel's default is 0.001. */
+    maxChange: number;
+};
+export declare const DEFAULT_ITERATION: IterationSettings;
+/** Excel's text prefix. A cell typed as `'007` holds the text `007`: the
+ *  apostrophe says "what follows is text", and it is not part of the value,
+ *  so it is never displayed, printed, exported or compared. */
+export declare const TEXT_PREFIX = "'";
+/** The value a typed text stands for once the prefix is taken off. */
+export declare const withoutTextPrefix: (text: string) => string;
 export type WorkbookOptions = {
     /** Extra functions merged over the built-ins. */
     functions?: Record<string, SheetFunction>;
@@ -17,6 +45,30 @@ export type WorkbookOptions = {
         col: number;
         value: CellValue;
     }>): void;
+    /**
+     * Fires for every RAW WRITE, with the text as typed rather than the value
+     * it computes: one call per `setRaw` that changed something, and one per
+     * cell a structural edit rewrote. This is the seam a delta stream reads
+     * (`sheet/delta.ts`), since a collaborator has to receive `=SUM(A1:A9)`
+     * rather than 42.
+     */
+    onWrite?(change: {
+        sheet: string;
+        row: number;
+        col: number;
+        text: string;
+    }): void;
+    /**
+     * What works a formula out. The built-in parser and evaluator unless an
+     * application hands over an evaluator of its own. The workbook keeps the
+     * dependency graph, the cache, the cycles and the spills whichever engine
+     * answers.
+     */
+    engine?: SheetEngine;
+    /** Tables the workbook starts with, for a document being restored. */
+    tables?: ReadonlyArray<TableRegion>;
+    /** Iterative calculation, off unless a model needs it. */
+    iteration?: Partial<IterationSettings>;
 };
 /** One cell read as text that has not been written: what a validation rule checks. */
 export type CellOverride = {
@@ -28,11 +80,25 @@ export type Workbook = {
     readonly sheets: ReadonlyArray<string>;
     readonly active: string;
     readonly names: SheetNames;
+    /**
+     * Excel's tables, which is what a structured reference resolves through.
+     * Defining one here is what makes `=SUM(Orders[Amount])` mean anything;
+     * the shell's Insert > Table does it, and a document restores it.
+     */
+    readonly tables: TableRegistry;
     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;
+    /**
+     * Copy a sheet's cells into a new sheet placed right after it, named
+     * `to` or Excel's "Name (2)", and make it active. The new sheet's
+     * formulas read their own sheet where the old ones read theirs, because
+     * an unqualified reference is relative to the sheet it sits on. Returns
+     * the new name, or null when `from` is unknown or `to` is taken.
+     */
+    copySheet(from: string, to?: string): string | null;
     /** 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. */
@@ -45,28 +111,107 @@ export type Workbook = {
      * 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.
+     * bounds and custom rules through this, and conditional formatting its
+     * formula rules, with `at` naming the cell the text is read for.
      */
-    evaluateText(sheet: string, text: string, override?: CellOverride): CellValue;
+    evaluateText(sheet: string, text: string, override?: CellOverride, at?: {
+        row: number;
+        col: number;
+    }): 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;
+    /**
+     * Tell the workbook which rows are folded away, and by what: `'filter'`
+     * for an AutoFilter, `'hand'` for Hide Rows, null for a row on the
+     * screen. Only `SUBTOTAL` reads it, which is how a total under a filtered
+     * list follows the filter. Pass null to forget the source again.
+     */
+    setHiddenRows(source: ((sheet: string, row: number) => 'filter' | 'hand' | null) | null): void;
     /** Apply a structural edit to one sheet, rewriting every formula in the
      *  WORKBOOK that pointed into it. */
     applyStructuralEdit(sheet: string, edit: StructuralEdit): void;
+    /**
+     * A block of cells has been MOVED (cut and pasted, or dragged): point
+     * every reference to those cells at where they now are, across the whole
+     * workbook and the defined names, as Excel does. The cells themselves are
+     * moved by whoever did the moving; this is only the repointing.
+     */
+    repointAfterMove(move: CellMove): void;
+    /**
+     * Excel's Trace Precedents: the cells a formula reads directly, on any
+     * sheet. Empty for a literal. A whole-column reference contributes its
+     * used rows.
+     */
+    precedents(sheet: string, row: number, col: number): Array<{
+        sheet: string;
+        row: number;
+        col: number;
+    }>;
+    /**
+     * Excel's Trace Dependents: the formulas that read a cell directly. Every
+     * formula in the workbook is evaluated first, so a dependent that was
+     * never on screen is found too.
+     */
+    dependents(sheet: string, row: number, col: number): Array<{
+        sheet: string;
+        row: number;
+        col: number;
+    }>;
+    /**
+     * Hear about every raw write, with the text as typed. Returns the
+     * unsubscribe. The delta stream reads this; a mirror of the cells in
+     * another store can too.
+     */
+    subscribeWrites(listener: (change: {
+        sheet: string;
+        row: number;
+        col: number;
+        text: string;
+    }) => void): () => void;
     /** Recompute everything. Rarely needed; `setRaw` keeps itself current. */
     recalculate(): void;
+    /** How circular references are treated, as the Formulas tab sets it. */
+    readonly iteration: IterationSettings;
+    /**
+     * Turn iterative calculation on or off, or change its limits, and
+     * recalculate: the cells in a cycle go from #CYCLE! to their fixed point,
+     * or back.
+     */
+    setIteration(next: Partial<IterationSettings>): void;
+    /**
+     * The spill a cell belongs to: the anchor holding the array formula and
+     * the rectangle its answer covers, for the anchor itself and every cell
+     * it spills into; null for a cell that is neither.
+     */
+    spillOf(sheet: string, row: number, col: number): {
+        anchor: {
+            row: number;
+            col: number;
+        };
+        rect: readonly [number, number, number, number];
+    } | null;
+    /** Every spill on a sheet, anchors computed, for a writer that saves the ranges. */
+    spills(sheet: string): Array<{
+        row: number;
+        col: number;
+        rect: readonly [number, number, number, number];
+    }>;
     rowCount(sheet: string): number;
     colCount(sheet: string): number;
     serialize(): {
         sheets: SheetData[];
         active: string;
         names: Record<string, string>;
+        tables?: TableRegion[];
+        iteration?: IterationSettings;
     };
 };
 /** A name Excel would accept for a sheet. */
 export declare function isValidSheetName(name: string): boolean;
+/** Iteration settings with the defaults filled in and the numbers sane. */
+export declare function cleanIteration(next?: Partial<IterationSettings> | null): IterationSettings;
 export declare function createWorkbook(initial?: ReadonlyArray<SheetData>, options?: WorkbookOptions): Workbook;
 export { isError };