@pixerate/editor 0.25.0 → 0.26.0

package/dist/{controller-BIJiNoVs.d.cts → controller-CxXGOEmy.d.cts}

@@ -654,6 +654,11 @@ interface FormulaNameDefinition {
     /** A key identifying the name (for cycle detection), e.g. `Data!RATE`. Defaults to the name. */
     key?: string;
 }
+/** Hints for `EvaluationContext.resolveRange`. */
+interface RangeResolveOptions {
+    /** The values are only aggregated by a function that ignores blank cells. */
+    skipBlanks?: boolean;
+}
 interface EvaluationContext {
     /**
      * Value of a cell. `sheet` is set for sheet-qualified references
@@ -665,8 +670,11 @@ interface EvaluationContext {
      * Values of a rectangular range, column by column (all rows of the first
      * column, then the next column). Lookup functions rely on this order.
      * `sheet` as in `resolveCell`; return an error code for a missing sheet.
+     * `options.skipBlanks` is a hint that the caller ignores blank cells
+     * (SUM, COUNT, AVERAGE, …): a resolver may then leave them out, so sparse
+     * ranges cost no array slots. Returning every value is always correct.
      */
-    resolveRange?: (startCol: string, startRow: number, endCol: string, endRow: number, sheet?: string) => any[] | string;
+    resolveRange?: (startCol: string, startRow: number, endCol: string, endRow: number, sheet?: string, options?: RangeResolveOptions) => any[] | string;
     resolveProperty?: (property: string) => any;
     /**
      * The spilled array anchored at a cell, for `A1#` references: its shape and
@@ -760,6 +768,10 @@ declare class FormulaEvaluator {
     private evaluateRange;
     private callFunction;
     private finishCall;
+    /**
+     * Arguments evaluated on first use. With `skipBlanks` (the function ignores
+     * blank cells), range arguments may come back without their blanks.
+     */
     private lazyArguments;
     /**
      * Applies a scalar function element by element when it receives arrays
@@ -843,19 +855,107 @@ declare function extractNameDependencies(node: ASTNode): NameDep[];
  */
 declare const columnDependencyKey: (col: string) => string;
 declare function extractCellDependencies(node: ASTNode): CellDep[];
+/**
+ * A reference a formula reads, without expanding ranges: a single cell or
+ * a rectangle (`A1:B9`; a whole column `A:A` runs to `WHOLE_COLUMN_END_ROW`).
+ * Columns are letters, rows are 1-based; ranges are normalised (start ≤ end).
+ */
+type ReferenceDep = ({
+    kind: 'cell';
+    col: string;
+    row: number;
+} & Pick<CellDep, 'sheet' | 'sheetEnd'>) | ({
+    kind: 'range';
+    startCol: string;
+    startRow: number;
+    endCol: string;
+    endRow: number;
+} & Pick<CellDep, 'sheet' | 'sheetEnd'>);
+/**
+ * The cells and ranges a formula reads, ranges kept whole (unlike
+ * `extractCellDependencies`, which lists every cell of a range). `A1#`
+ * depends on its anchor `A1`.
+ */
+declare function extractReferenceDependencies(node: ASTNode): ReferenceDep[];
+/**
+ * Dependency key of a rectangle (`A1:B9`, or `SHEET!A1:B9` with a sheet
+ * prefix), for `DependencyGraph.setCellDependencies`. The graph stores it as
+ * one range, however many cells it covers.
+ */
+declare function rangeDependencyKey(startCol: string, startRow: number, endCol: string, endRow: number, sheetPrefix?: string): string;
+interface IntervalEntry<T> {
+    r0: number;
+    r1: number;
+    id: string;
+    payload: T;
+}
+/**
+ * Row intervals `[r0, r1]` with payloads, answering "which intervals overlap
+ * rows `a..b`?" in O(log n + k). Entries are sorted by start, with an
+ * implicit segment tree of the largest end below each node, so a query only
+ * descends into subtrees holding a match. Removals mark entries dead;
+ * insertions wait in a small pending set. Both are merged in (on the next
+ * query) once either grows, so mutations cost O(log n) amortised.
+ */
+declare class IntervalIndex<T> {
+    private items;
+    private dead;
+    private deadCount;
+    private maxEnd;
+    private leaves;
+    private position;
+    private pending;
+    /** Live entries. */
+    get size(): number;
+    /** Adds (or revives) the entry `id`. An id always names the same interval. */
+    insert(r0: number, r1: number, id: string, payload: T): void;
+    remove(id: string): void;
+    /** Merges pending insertions and drops dead entries when there are enough of them. */
+    private settle;
+    /** Calls `fn` for every live interval overlapping rows `a..b` (`r0 <= b && r1 >= a`). */
+    query(a: number, b: number, fn: (payload: T, entry: IntervalEntry<T>) => void): void;
+    private walk;
+}
+/** Sizes of the dependency index (see `DependencyGraph.getIndexStats`). */
+interface DependencyIndexStats {
+    /** Cells with registered dependencies (formulas). */
+    formulas: number;
+    /** Single-cell edges (formula → cell it reads). */
+    cellEdges: number;
+    /** Range entries: one per range (per column for ranges up to 64 columns wide), however many cells it covers. */
+    rangeEntries: number;
+    /** Formulas that use a volatile function. */
+    volatile: number;
+}
 declare class DependencyGraph {
-    private dependencies;
-    private dependents;
+    private nodes;
+    private cellDependents;
+    private rangeIndex;
+    private volatile;
     private spillDependencies;
     private spillDependents;
     private spillEdges;
-    /**
-     * Sets the cells `cellKey` depends on directly (keys such as `B2`, or a
-     * column key from `columnDependencyKey`), replacing its previous
-     * dependencies. Used by spreadsheets whose keys carry more than A1 text
-     * (e.g. sheet-qualified keys); `setCellFormula` derives them from a formula.
+    private blockingEdges;
+    private parsed;
+    private parse;
+    private sheetIndex;
+    private removeNode;
+    /**
+     * Sets what `cellKey` depends on directly, replacing its previous
+     * dependencies. Keys are single cells (`B2`), rectangles (`A1:B9`) or
+     * whole columns (`A:`, see `columnDependencyKey`), each optionally
+     * sheet-qualified (`SHEET!A1:A9`). Ranges are stored whole in an interval
+     * index, never expanded cell by cell. `setCellFormula` derives the keys
+     * from a formula.
      */
     setCellDependencies(cellKey: string, dependencyKeys: Iterable<string>): void;
+    /**
+     * Marks `cellKey` as volatile (its formula uses NOW, RAND, …): it is
+     * recalculated by every plan made with `includeVolatile`, whatever changed.
+     */
+    setVolatile(cellKey: string, volatile: boolean): void;
+    /** Cells whose formulas are volatile. */
+    getVolatileKeys(): string[];
     setCellFormula(cellKey: string, formulaStr: string | null): void;
     /** Removes every registered formula and dependency. */
     clear(): void;
@@ -867,12 +967,34 @@ declare class DependencyGraph {
      * the anchor's edges.
      */
     setSpillEdges(anchorKey: string, spilledKeys: Iterable<string>, blockingKeys?: Iterable<string>): void;
+    /**
+     * Drops the edge from a spilled cell to the anchor whose values it holds,
+     * for a cell that just got input of its own: its value no longer comes
+     * from the anchor (which recalculates and becomes `#SPILL!`), and the
+     * stale edge could otherwise close a false cycle with the cell's new
+     * formula before the anchor is evaluated again.
+     */
+    detachSpilledCell(cellKey: string): void;
     /** The spilled cells registered for `anchorKey` by `setSpillEdges`. */
     getSpilledKeys(anchorKey: string): string[];
-    /** Formula dependencies plus dynamic-array (spill) dependencies of a cell. */
+    /**
+     * What a cell depends on directly: single cells, ranges (as registered,
+     * e.g. `A1:A9` or `A:`, not expanded) and dynamic-array (spill) edges.
+     */
     getDependencies(cellKey: string): string[];
-    /** Cells depending on `cellKey`, through formulas or spills. */
+    /**
+     * Whether the formula in `formulaKey` reads `cellKey` directly: as a cell,
+     * inside one of its ranges, or through a spill edge.
+     */
+    dependsOn(formulaKey: string, cellKey: string): boolean;
+    /**
+     * Formulas (and spilled cells) reading `cellKey` directly, through formulas
+     * or spills. Found in O(log n + k) through the range index.
+     */
     getDependents(cellKey: string): string[];
+    private collectDependents;
+    /** Sizes of the index: ranges count once (per column), not once per cell. */
+    getIndexStats(): DependencyIndexStats;
     /**
      * Detects if there is a cycle containing cellKey.
      */
@@ -886,13 +1008,19 @@ declare class DependencyGraph {
     };
     /**
      * Plans a recalculation over `cellKeys` (and, with `includeDependents`, every
-     * cell that transitively depends on them). Returns the keys in evaluation
+     * cell that transitively depends on them; with `includeVolatile`, every
+     * volatile formula and its dependents too). Returns the keys in evaluation
      * order (dependencies first) and the set of keys that are part of a cycle,
      * which must be marked `#CYCLE!` instead of evaluated. Every member of a
      * cycle is reported, not just the cell that closed it.
+     *
+     * Only the planned cells are ordered: a range a formula reads becomes one
+     * node whose edges are the planned cells inside it (found by binary
+     * search), so a range shared by many formulas is resolved once.
      */
     getEvaluationPlan(cellKeys: Iterable<string>, options?: {
         includeDependents?: boolean;
+        includeVolatile?: boolean;
     }): {
         order: string[];
         cyclic: Set<string>;
@@ -1234,6 +1362,15 @@ interface SpreadsheetControllerOptions {
      */
     maxHistoryBytes?: number;
 }
+/** Work done by a recalculation (see `SpreadsheetController.getRecalculationStats`). */
+interface SpreadsheetRecalculationStats {
+    /** Formulas evaluated. */
+    evaluated: number;
+    /** Cells in the evaluation plans: formulas, their dependents and spilled cells. */
+    planned: number;
+    /** Evaluation passes (another pass runs when spill ranges change). */
+    passes: number;
+}
 /** A defined name as listed by `getNames()`. */
 interface SpreadsheetNameInfo extends SpreadsheetDefinedName {
     /** Name of the sheet a sheet-scoped name belongs to; unset for workbook scope. */
@@ -1273,6 +1410,9 @@ declare class SpreadsheetController {
     private evaluatingRowIndex;
     private evaluatingCell;
     private spillChanges;
+    private recalcStats;
+    private astCache;
+    private rangeCache;
     /** The active sheet's document (the sheet the editor shows). */
     get document(): SpreadsheetDocument;
     set document(doc: SpreadsheetDocument);
@@ -1358,7 +1498,17 @@ declare class SpreadsheetController {
     private recomputeRowIndices;
     getColumn(colIdOrKey: string): SpreadsheetColumn | undefined;
     getRow(rowIdOrIndex: string | number): SpreadsheetRow | undefined;
+    /** The row with this id on the current sheet (constant time, see `PositionCache`). */
+    private findRow;
+    /** The column with this id on the current sheet. */
+    private findColumn;
+    /** The column whose key is `key` (`A`, `B`, …): keys follow column positions. */
+    private columnByKey;
     getCell(rowId: string, colId: string): CellData;
+    /** `getCell` for a row and column already looked up. */
+    private cellOf;
+    /** A cell with no value of its own: derived (bound, column formula, blank), keeping an explicit number format. */
+    private finishCell;
     /** Value of a cell with no stored data: bound record value, column formula, or blank. */
     private getDerivedCell;
     setCellValue(rowId: string, colId: string, raw: string): void;
@@ -1375,7 +1525,26 @@ declare class SpreadsheetController {
      * span) and, through defined names, the cells those names refer to.
      */
     private registerFormula;
-    /** Adds the qualified keys `ast` depends on, with unqualified references on `home`. */
+    /**
+     * Spill edges made stale by new input in `cellKey`: the edges of the array
+     * it anchored (its new formula re-spills when evaluated; spill changes
+     * are recalculated in a further pass) and, when it now holds input, its
+     * edge to the anchor whose values it held. Left in place they can close
+     * false cycles with the new formulas before the anchors are evaluated.
+     */
+    private dropStaleSpillEdges;
+    /**
+     * The parsed formula, shared by dependency registration and evaluation (so
+     * a load parses each formula once). ASTs are never mutated.
+     */
+    private parseCached;
+    /**
+     * Adds the qualified keys `ast` depends on, with unqualified references on
+     * `home`: cells, and ranges kept whole (`SHEETID!A1:A50000`), which the
+     * graph indexes as intervals instead of one key per cell. Sets
+     * `volatile.found` when a volatile function (NOW, RAND, …) is used,
+     * directly or through a defined name.
+     */
     private collectDependencies;
     /**
      * Recalculates `keys` (and, with `includeDependents`, their dependents) in
@@ -1385,12 +1554,31 @@ declare class SpreadsheetController {
      * another pass, until nothing changes.
      */
     private recalculateKeys;
+    /**
+     * Recalculates cells of the current sheet whose stored input changed (their
+     * formulas already registered), with their dependents, in one plan.
+     */
+    private recalculateWrittenCells;
+    /**
+     * Work done by the last recalculation (an edit, paste, import, load or
+     * full recalculation): formulas evaluated, cells planned (formulas, their
+     * dependents and spilled cells) and passes (more than one when spill
+     * ranges changed). Deterministic, unlike timings: use it to check that an
+     * edit only recalculates what depends on it.
+     */
+    getRecalculationStats(): SpreadsheetRecalculationStats;
     /**
      * Rebuilds the dependency graph from scratch and recalculates every formula
      * in dependency order.
      */
     recalculateAll(): void;
     private runEvaluationPlan;
+    /**
+     * Drops cached ranges of `sheetId` that cover column `col` (whose cell was
+     * just evaluated), or all of the sheet's when `col` is null (spilled
+     * values moved or changed).
+     */
+    private invalidateRangeCache;
     private locateCellKey;
     private markCycle;
     private evalSingleCellByKey;
@@ -1415,6 +1603,11 @@ declare class SpreadsheetController {
     /** Whether `range` overlaps a spilled array (its anchor or spilled cells). */
     private intersectsSpill;
     private resolveCellByCoord;
+    /**
+     * Values of a range, column by column. With `skipBlanks` (functions that
+     * ignore blank cells: SUM, COUNT, AVERAGE, …) blank cells are left out, so
+     * a sparse column costs one lookup per row and no array slot.
+     */
     private resolveRangeByCoords;
     private resolveCurrentRowProperty;
     selectCell(row: number, col: number, extendSelection?: boolean): void;
@@ -1735,6 +1928,9 @@ declare class SpreadsheetController {
         sheet?: string;
     }): FormulaEvaluationResult;
     private recordSnapshot;
+    /** Records the stored state of one cell, for undoing a single-cell edit. */
+    private recordCellSnapshot;
+    private cellHistory;
     private recordWorkbookSnapshot;
     private pushUndo;
     /** Drops the oldest snapshots beyond `maxHistoryBytes`, always keeping the newest. */
@@ -1839,4 +2035,4 @@ declare class SpreadsheetController {
     isInvalidDataCircled(row: number, col: number): boolean;
 }
 
-export { type GroupSummary as $, type ASTNode as A, type BinaryOpNode as B, type CellCoordinate as C, DEFAULT_COLUMN_WIDTH as D, type DataValidationResult as E, type DataValidationRule as F, type DataValidationSheet as G, type DataValidationType as H, DependencyGraph as I, type EvaluationContext as J, FORMULA_ERRORS as K, type FilterOperator as L, type FilterRule as M, type FormulaDiagnostic as N, type FormulaErrorCode as O, type FormulaEvaluationResult as P, FormulaEvaluator as Q, type FormulaNameDefinition as R, SpreadsheetController as S, FormulaParser as T, type FormulaRange as U, type FormulaReferenceFilter as V, type FormulaReferenceInfo as W, type FormulaToken as X, type FormulaTokenType as Y, type FunctionCallNode as Z, type GroupAggregate as _, type CellData as a, getTableSections as a$, type InvokeNode as a0, type LiteralNode as a1, MAX_FORMULA_ARRAY_SIZE as a2, type MissingNode as a3, type NameDep as a4, type NameNode as a5, type NewConditionalFormatRule as a6, type NewDataValidationRule as a7, type NewFilterRule as a8, type ParsedSpreadsheetClipboard as a9, type SpreadsheetRowSection as aA, type SpreadsheetSheetInfo as aB, type SpreadsheetSpill as aC, type SpreadsheetTableSettings as aD, type SpreadsheetValidationAction as aE, type SpreadsheetValidationPrompt as aF, type SpreadsheetViewColumn as aG, type SpreadsheetViewModel as aH, type SpreadsheetViewRow as aI, type SpreadsheetWorkbook as aJ, type StructuralChange as aK, type UnaryOpNode as aL, WHOLE_COLUMN_END_ROW as aM, buildSpreadsheetView as aN, colNameToIndex as aO, columnDependencyKey as aP, compareNumbers as aQ, compareValues as aR, computeRowGroups as aS, createSpreadsheetClipboardData as aT, deleteSheetInFormula as aU, describeFormulaError as aV, extractCellDependencies as aW, extractNameDependencies as aX, formatSheetPrefix as aY, formulaIdentifiers as aZ, getRowSection as a_, type PropertyRefNode as aa, type RangeNode as ab, type RowType as ac, SPREADSHEET_CLIPBOARD_MIME as ad, type SheetQualifier as ae, type SortDirection as af, type SortKey as ag, type SpillRefNode as ah, type SpreadsheetCellSpan as ai, type SpreadsheetClipboardCell as aj, type SpreadsheetClipboardData as ak, type SpreadsheetClipboardPayload as al, type SpreadsheetClipboardSource as am, type SpreadsheetColumn as an, type SpreadsheetCommitResult as ao, type SpreadsheetControllerOptions as ap, type SpreadsheetDataSource as aq, type SpreadsheetDataSourceField as ar, type SpreadsheetDefinedName as as, type SpreadsheetDocument as at, type SpreadsheetFilterState as au, type SpreadsheetGrouping as av, type SpreadsheetNameInfo as aw, type SpreadsheetNameScope as ax, type SpreadsheetRow as ay, type SpreadsheetRowGroup as az, type CellDep as b, indexToColName as b0, isFormulaError as b1, mapFormulaReferences as b2, numberToText as b3, offsetFormulaReferences as b4, parseCellReference as b5, parseFormula as b6, parseHtmlTable as b7, parseRange as b8, quoteSheetName as b9, readSpreadsheetClipboard as ba, rebaseClipboardRows as bb, remapFormulaReferences as bc, renameNameInFormula as bd, renameSheetInFormula as be, rowPassesFilters as bf, serializeHtmlTable as bg, sheetNameNeedsQuotes as bh, shiftFormulaReferences as bi, sortCompareValues as bj, tokenizeFormula as bk, type CellFormat as c, type CellPosition as d, type CellRange as e, type CellRefNode as f, type CellValueReader as g, type ColumnBinding as h, type ColumnType as i, type ConditionalCellFormat as j, type ConditionalFormatCondition as k, type ConditionalFormatIconSet as l, type ConditionalFormatOperator as m, type ConditionalFormatOverlay as n, type ConditionalFormatRule as o, type ConditionalFormatSheet as p, type ConditionalFormatStyle as q, type ConditionalFormatTimePeriod as r, type ConditionalFormatType as s, type ConditionalFormatValue as t, type CsvExportOptions as u, type CsvImportOptions as v, DEFAULT_ROW_HEIGHT as w, DataSourceBinder as x, type DataValidationErrorStyle as y, type DataValidationOperator as z };
+export { type GroupAggregate as $, type ASTNode as A, type BinaryOpNode as B, type CellCoordinate as C, DEFAULT_COLUMN_WIDTH as D, type DataValidationResult as E, type DataValidationRule as F, type DataValidationSheet as G, type DataValidationType as H, DependencyGraph as I, type DependencyIndexStats as J, type EvaluationContext as K, FORMULA_ERRORS as L, type FilterOperator as M, type FilterRule as N, type FormulaDiagnostic as O, type FormulaErrorCode as P, type FormulaEvaluationResult as Q, FormulaEvaluator as R, SpreadsheetController as S, type FormulaNameDefinition as T, FormulaParser as U, type FormulaRange as V, type FormulaReferenceFilter as W, type FormulaReferenceInfo as X, type FormulaToken as Y, type FormulaTokenType as Z, type FunctionCallNode as _, type CellData as a, extractCellDependencies as a$, type GroupSummary as a0, IntervalIndex as a1, type InvokeNode as a2, type LiteralNode as a3, MAX_FORMULA_ARRAY_SIZE as a4, type MissingNode as a5, type NameDep as a6, type NameNode as a7, type NewConditionalFormatRule as a8, type NewDataValidationRule as a9, type SpreadsheetNameInfo as aA, type SpreadsheetNameScope as aB, type SpreadsheetRecalculationStats as aC, type SpreadsheetRow as aD, type SpreadsheetRowGroup as aE, type SpreadsheetRowSection as aF, type SpreadsheetSheetInfo as aG, type SpreadsheetSpill as aH, type SpreadsheetTableSettings as aI, type SpreadsheetValidationAction as aJ, type SpreadsheetValidationPrompt as aK, type SpreadsheetViewColumn as aL, type SpreadsheetViewModel as aM, type SpreadsheetViewRow as aN, type SpreadsheetWorkbook as aO, type StructuralChange as aP, type UnaryOpNode as aQ, WHOLE_COLUMN_END_ROW as aR, buildSpreadsheetView as aS, colNameToIndex as aT, columnDependencyKey as aU, compareNumbers as aV, compareValues as aW, computeRowGroups as aX, createSpreadsheetClipboardData as aY, deleteSheetInFormula as aZ, describeFormulaError as a_, type NewFilterRule as aa, type ParsedSpreadsheetClipboard as ab, type PropertyRefNode as ac, type RangeNode as ad, type RangeResolveOptions as ae, type ReferenceDep as af, type RowType as ag, SPREADSHEET_CLIPBOARD_MIME as ah, type SheetQualifier as ai, type SortDirection as aj, type SortKey as ak, type SpillRefNode as al, type SpreadsheetCellSpan as am, type SpreadsheetClipboardCell as an, type SpreadsheetClipboardData as ao, type SpreadsheetClipboardPayload as ap, type SpreadsheetClipboardSource as aq, type SpreadsheetColumn as ar, type SpreadsheetCommitResult as as, type SpreadsheetControllerOptions as at, type SpreadsheetDataSource as au, type SpreadsheetDataSourceField as av, type SpreadsheetDefinedName as aw, type SpreadsheetDocument as ax, type SpreadsheetFilterState as ay, type SpreadsheetGrouping as az, type CellDep as b, extractNameDependencies as b0, extractReferenceDependencies as b1, formatSheetPrefix as b2, formulaIdentifiers as b3, getRowSection as b4, getTableSections as b5, indexToColName as b6, isFormulaError as b7, mapFormulaReferences as b8, numberToText as b9, offsetFormulaReferences as ba, parseCellReference as bb, parseFormula as bc, parseHtmlTable as bd, parseRange as be, quoteSheetName as bf, rangeDependencyKey as bg, readSpreadsheetClipboard as bh, rebaseClipboardRows as bi, remapFormulaReferences as bj, renameNameInFormula as bk, renameSheetInFormula as bl, rowPassesFilters as bm, serializeHtmlTable as bn, sheetNameNeedsQuotes as bo, shiftFormulaReferences as bp, sortCompareValues as bq, tokenizeFormula as br, type CellFormat as c, type CellPosition as d, type CellRange as e, type CellRefNode as f, type CellValueReader as g, type ColumnBinding as h, type ColumnType as i, type ConditionalCellFormat as j, type ConditionalFormatCondition as k, type ConditionalFormatIconSet as l, type ConditionalFormatOperator as m, type ConditionalFormatOverlay as n, type ConditionalFormatRule as o, type ConditionalFormatSheet as p, type ConditionalFormatStyle as q, type ConditionalFormatTimePeriod as r, type ConditionalFormatType as s, type ConditionalFormatValue as t, type CsvExportOptions as u, type CsvImportOptions as v, DEFAULT_ROW_HEIGHT as w, DataSourceBinder as x, type DataValidationErrorStyle as y, type DataValidationOperator as z };