@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/evaluate.d.ts

@@ -15,12 +15,26 @@
  */
 import { type CellValue, type Node } from './ast.js';
 import { type SheetFunction } from './functions.js';
+import { type Grid } from './packs/array.js';
 import { type TableRegion } from './tables.js';
 export type EvalContext = {
     /** Read one cell. Out of bounds should return `{ error: '#REF!' }`. */
     resolve(sheet: string | null, row: number, col: number): CellValue;
     /** Last used row of a sheet, for open-ended whole-column ranges. */
     lastRow(sheet: string | null): number;
+    /**
+     * The rectangle a dynamic array anchored at (row, col) currently spills
+     * into, as `[r1, c1, r2, c2]`, or null when that cell is not a spill
+     * anchor. Backs the spilled-range operator `A1#`: without it the operator
+     * reads #REF!, since only the workbook knows how far an array spilled.
+     */
+    spillRect?(sheet: string | null, row: number, col: number): readonly [number, number, number, number] | null;
+    /**
+     * The sheets from `from` to `to` in tab order, inclusive, or null when
+     * either name is unknown. Backs a 3D reference (`Sheet1:Sheet3!A1`), which
+     * reads its cell on each of them.
+     */
+    sheetsBetween?(from: string, to: string): string[] | null;
     /**
      * Resolve a defined name to the reference it stands for, or null when
      * there is no such name. The node is evaluated in place of the name, so a
@@ -45,7 +59,53 @@ export type EvalContext = {
         row: number;
         col: number;
     };
+    /**
+     * Whether a row is folded away, and by what: `'filter'` for an AutoFilter,
+     * `'hand'` for Hide Rows, null for a row on the screen. Only `SUBTOTAL`
+     * asks, and it is what tells its 1-11 codes from its 101-111 ones. A
+     * consumer that hides nothing leaves this out.
+     */
+    hiddenRow?(sheet: string | null, row: number): 'filter' | 'hand' | null;
+    /**
+     * Whether a cell holds a `SUBTOTAL` of its own. Excel's SUBTOTAL skips
+     * those, so a grand total over a column of subtotals counts each row once
+     * rather than twice.
+     */
+    isSubtotal?(sheet: string | null, row: number, col: number): boolean;
+    /**
+     * Names bound INSIDE the formula, by `LET` or by a lambda's parameters.
+     * Looked up before the workbook's own names, which is what makes
+     * `=LET(x, 2, x * 3)` mean 6 on a sheet that also has a name `x`.
+     * Copied rather than chained: a scope holds a handful of names, and a
+     * flat map is faster to read than a chain is to walk.
+     */
+    locals?: ReadonlyMap<string, LocalBinding>;
 };
+/** A lambda, closed over the scope it was written in. */
+export type Lambda = {
+    readonly lambda: true;
+    params: string[];
+    body: Node;
+    scope: ReadonlyMap<string, LocalBinding> | undefined;
+};
+/** What a name bound inside a formula can hold: a value, a grid, a lambda. */
+export type LocalBinding = CellValue | Grid | Lambda;
+/**
+ * Turn a structured reference into a rectangle and read it.
+ *
+ * Every failure here is #REF! rather than a throw, because a table reference
+ * naming a column that was renamed is an ordinary thing to find in a sheet,
+ * and one broken total should not take the rest of the workbook with it.
+ */
+export declare function tableRectOf(node: Extract<Node, {
+    k: 'table';
+}>, ctx: EvalContext): {
+    sheet: string;
+    firstRow: number;
+    lastRow: number;
+    firstCol: number;
+    lastCol: number;
+} | null;
 /**
  * Evaluate a parsed formula. Never throws: a `FormulaError` raised anywhere
  * inside becomes the matching error value.
@@ -56,6 +116,13 @@ export type EvalContext = {
  * caller tells "a list source that is a range" from "a formula".
  */
 export declare function rangeValues(node: Node, ctx: EvalContext): CellValue[][] | null;
+/**
+ * The grid a formula spills, or null when it is a plain value: a range on
+ * its own (`=A1:A5`), a name that refers to one, a reference function's
+ * rectangle, or an array function's answer, when that is more than one
+ * cell. A throw inside is the error the cell shows, and no spill.
+ */
+export declare function evaluateSpill(node: Node, ctx: EvalContext): Grid | null;
 export declare function evaluate(node: Node, ctx: EvalContext): CellValue;
 /** Render a computed value the way a cell shows it. */
 export declare function formatValue(v: CellValue): string;