@sheetxl/sdk 0.8.0-beta.14 → 0.8.0-beta.16

package/types/src/.generated/wasm/sdk.d.ts

@@ -1,6 +1,179 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * A pivot table's inputs, allocated here and filled by the host.
+ */
+export class LayoutRequest {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Takes data field `measure`'s values from the host: `cells + 1` values that may hold the
+     * types of `type_mask`, every byte zero, the last what a crossing with no cell shows. The
+     * address of its bytes.
+     */
+    add_calculated(measure: number, cells: number, type_mask: number): number;
+    /**
+     * Adds a field to the rows (`axis` 0) or the columns (1), with `items` item ids and the
+     * options' bits (subtotal 1, on top 2, blank after 4, show all 8, tabular 16). Its buffers,
+     * all zero, are at [`Self::field_ids`], [`Self::field_ranks`] and [`Self::field_flags`].
+     */
+    add_field(axis: number, items: number, options: number): number;
+    /**
+     * Adds a data field: value leaf `values` reduced by `reducer`, an index into `Reducer::ALL`.
+     */
+    add_measure(values: number, reducer: number): void;
+    /**
+     * Adds a page field of `items` item ids: its index for [`Self::page_ids`] and
+     * [`Self::page_keep`].
+     */
+    add_page(items: number): number;
+    /**
+     * Adds a value leaf of `records` values that may hold the types of `type_mask`, every byte
+     * zero: the address of its bytes.
+     */
+    add_values(type_mask: number): number;
+    /**
+     * Adds where the data fields sit, on the rows (`axis` 0) or the columns (1).
+     */
+    add_values_slot(axis: number, tabular: boolean): number;
+    /**
+     * The address of a field's `u8` flags per item id (hidden 1, collapsed 2).
+     */
+    field_flags(axis: number, slot: number): number;
+    /**
+     * The address of a field's `records` `u32` item ids.
+     */
+    field_ids(axis: number, slot: number): number;
+    /**
+     * The address of a field's `u32` rank per item id.
+     */
+    field_ranks(axis: number, slot: number): number;
+    /**
+     * Lays the table out. `div0`, `na` and `null` are the codes of `#DIV/0!`, `#N/A` and
+     * `#NULL!` in the host's error table.
+     */
+    lay_out(div0: number, na: number, _null: number): LayoutResult;
+    /**
+     * A request over `records` records.
+     */
+    constructor(records: number);
+    /**
+     * The rollup alone: what the host's formulas read.
+     */
+    operands(div0: number, na: number, _null: number): OperandsResult;
+    /**
+     * The address of a page field's `records` `u32` item ids.
+     */
+    page_ids(page: number): number;
+    /**
+     * The address of a page field's `u8` per item id, non-zero to keep its records.
+     */
+    page_keep(page: number): number;
+    /**
+     * The address of the `records` `u8` record mask: per record, 1 where the row items keep it,
+     * 2 where the column items do, a value counting it only with both (`Request::record_keep`).
+     * Allocated, every record kept by both, on the first ask. Never asked, every record is kept.
+     */
+    record_keep(): number;
+    /**
+     * Shows a field's subtotal `functions`, in line order, by index into those
+     * [`Self::set_functions`] counted, in place of its automatic subtotal; `across` when the
+     * innermost field's show one line per item across its outer items.
+     */
+    set_field_functions(axis: number, slot: number, functions: Uint32Array, across: boolean): void;
+    /**
+     * Sorts a field's items under each outer item by data field `measure`'s value, largest first
+     * when `descending`: their crossing with the other axis's line at `scope` (its ranks from the
+     * outermost field), or with its grand total when `scope` is empty.
+     */
+    set_field_sort(axis: number, slot: number, measure: number, descending: boolean, scope: Uint32Array): void;
+    /**
+     * How many subtotal functions the fields use: the last `count` × data fields measures are
+     * theirs, by function then data field.
+     */
+    set_functions(count: number): void;
+    /**
+     * Whether the rows' and the columns' grand total lines show.
+     */
+    set_grand(rows: boolean, columns: boolean): void;
+    /**
+     * Marks the last `count` measures as feeding the host's formulas only: no line shows them.
+     */
+    set_operand_measures(count: number): void;
+    /**
+     * Shows data field `measure`'s values as `kind`: normal 0, percent of total 1, of row 2, of
+     * column 3, index 4, percent of parent row 5, of parent column 6, of parent 7, running total
+     * 8, percent of running total 9, rank ascending 10, descending 11, difference 12, percent 13,
+     * percent difference 14. Kinds 7 to 14 compare along the base field at `slot` on the rows
+     * (`axis` 0) or the columns (1); any other axis is a base field on neither, every value
+     * `#N/A`. Kinds 12 to 14 compare with the base item of rank `item`, or the item before
+     * (`u32::MAX - 1`) or after (`u32::MAX`) each.
+     */
+    set_show_as(measure: number, kind: number, axis: number, slot: number, item: number): void;
+}
+
+/**
+ * What a layout produced.
+ */
+export class LayoutResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The column lines, as [`Self::row_lines`].
+     */
+    column_lines(): Uint32Array;
+    /**
+     * The length of every column line's path.
+     */
+    column_stride(): number;
+    /**
+     * The row lines, `7 + row_stride()` `u32`s each: kind (item 0, subtotal 1, grand 2,
+     * blank 3), depth, node (`u32::MAX` for none), data field (`u32::MAX` for none), shows
+     * values (0 or 1), subtotal function (`u32::MAX` for none), across (0 or 1), then the path's
+     * ranks.
+     */
+    row_lines(): Uint32Array;
+    /**
+     * The length of every row line's path.
+     */
+    row_stride(): number;
+    /**
+     * Per crossing, row-major: value 0, empty 1, nothing 2.
+     */
+    states(): Uint8Array;
+    /**
+     * Per crossing, row-major, its value: the result leaf.
+     */
+    values(): ListBuffer;
+}
+
+/**
+ * A `MixedTypedList` in wasm memory: the host views `byte_length` bytes at `ptr`.
+ */
+export class ListBuffer {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The list's bytes.
+     */
+    byte_length(): number;
+    /**
+     * The number of values.
+     */
+    length(): number;
+    /**
+     * The address of the list's first byte; 8-aligned.
+     */
+    ptr(): number;
+    /**
+     * The types the list may hold, as `1 << type`.
+     */
+    type_mask(): number;
+}
+
 /**
  * A face's measures, filled once by the host from a shipped table or a canvas, then wrapped
  * against any number of times (DESIGN-FONTS §6.2, shape C; DESIGN-FONTS §4).
@@ -52,17 +225,158 @@ export class MetricsTable {
     wrap(text: string, px: number, line_height: number, max_width: number, max_height: number, indent: number, letter_spacing: number, super_sub: boolean): Float32Array;
 }
 
+/**
+ * What a request's formulas read: each measure's value per cell.
+ */
+export class OperandsResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The number of cells.
+     */
+    cell_count(): number;
+    /**
+     * A measure's value per cell, in cell order: the result leaf.
+     */
+    values(measure: number): ListBuffer;
+}
+
+/**
+ * A pivot's inputs, allocated here and filled by the host.
+ */
+export class PivotRequest {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Adds a column key field: the address of its `records` `u32` item ids, all `0`.
+     */
+    add_column_field(): number;
+    /**
+     * Keeps only some records: the address of `ceil(records / 64)` `u64` words, all `0`; bit
+     * `i % 64` of word `i / 64` keeps record `i`.
+     */
+    add_filter(): number;
+    /**
+     * Adds a measure: value leaf `values` reduced by `reducer`, an index into `Reducer::ALL`
+     * (Sum, Count, CountA, Average, Min, Max, Product, VarS, VarP, StDevS, StDevP).
+     */
+    add_measure(values: number, reducer: number): void;
+    /**
+     * Adds a row key field: the address of its `records` `u32` item ids, all `0`.
+     */
+    add_row_field(): number;
+    /**
+     * Adds a value leaf of `records` values that may hold the types of `type_mask`, every byte
+     * zero (a run of blanks): the address of its bytes.
+     */
+    add_values(type_mask: number): number;
+    /**
+     * Forgets the measures, keeping every buffer: the next pass reads the same inputs.
+     */
+    clear_measures(): void;
+    /**
+     * Runs the pass. `div0` is the error code a division by zero answers with; `records`
+     * keeps each cell's records.
+     */
+    compute(div0: number, records: boolean): PivotResult;
+    /**
+     * A request over `records` records.
+     */
+    constructor(records: number);
+}
+
+/**
+ * What a pass produced.
+ */
+export class PivotResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The cell of a row node and a column node, or `u32::MAX` (`0xFFFFFFFF`) when no kept record
+     * is in both.
+     */
+    cell(row: number, column: number): number;
+    /**
+     * The number of cells.
+     */
+    cell_count(): number;
+    /**
+     * The column tree, as [`Self::row_nodes`].
+     */
+    column_nodes(): Uint32Array;
+    /**
+     * A cell's records, ascending (empty unless records were kept).
+     */
+    records(cell: number): Uint32Array;
+    /**
+     * Per row node, its cell with column node `column`, `u32::MAX` where it has none.
+     */
+    row_cells(column: number): Uint32Array;
+    /**
+     * The row tree, five `u32`s a node in id order: parent, item, depth, first record, records.
+     */
+    row_nodes(): Uint32Array;
+    /**
+     * A measure's results, one per cell: the result leaf.
+     */
+    values(measure: number): ListBuffer;
+}
+
 /**
  * The number of Unicode scalar values in `text` (not `text.length`, which counts UTF-16 units).
  */
 export function char_count(text: string): number;
 
+/**
+ * The module's `WebAssembly.Memory`, for views over the buffers the exports hand back by address.
+ */
+export function wasm_memory(): any;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_layoutrequest_free: (a: number, b: number) => void;
+    readonly __wbg_layoutresult_free: (a: number, b: number) => void;
+    readonly __wbg_listbuffer_free: (a: number, b: number) => void;
     readonly __wbg_metricstable_free: (a: number, b: number) => void;
+    readonly __wbg_operandsresult_free: (a: number, b: number) => void;
+    readonly __wbg_pivotrequest_free: (a: number, b: number) => void;
+    readonly __wbg_pivotresult_free: (a: number, b: number) => void;
     readonly char_count: (a: number, b: number) => number;
+    readonly layoutrequest_add_calculated: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly layoutrequest_add_field: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly layoutrequest_add_measure: (a: number, b: number, c: number, d: number) => void;
+    readonly layoutrequest_add_page: (a: number, b: number) => number;
+    readonly layoutrequest_add_values: (a: number, b: number, c: number) => void;
+    readonly layoutrequest_add_values_slot: (a: number, b: number, c: number, d: number) => void;
+    readonly layoutrequest_field_flags: (a: number, b: number, c: number, d: number) => void;
+    readonly layoutrequest_field_ids: (a: number, b: number, c: number, d: number) => void;
+    readonly layoutrequest_field_ranks: (a: number, b: number, c: number, d: number) => void;
+    readonly layoutrequest_lay_out: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly layoutrequest_new: (a: number) => number;
+    readonly layoutrequest_operands: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly layoutrequest_page_ids: (a: number, b: number, c: number) => void;
+    readonly layoutrequest_page_keep: (a: number, b: number, c: number) => void;
+    readonly layoutrequest_record_keep: (a: number) => number;
+    readonly layoutrequest_set_field_functions: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly layoutrequest_set_field_sort: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly layoutrequest_set_functions: (a: number, b: number) => void;
+    readonly layoutrequest_set_grand: (a: number, b: number, c: number) => void;
+    readonly layoutrequest_set_operand_measures: (a: number, b: number) => void;
+    readonly layoutrequest_set_show_as: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly layoutresult_column_lines: (a: number, b: number) => void;
+    readonly layoutresult_column_stride: (a: number) => number;
+    readonly layoutresult_row_lines: (a: number, b: number) => void;
+    readonly layoutresult_row_stride: (a: number) => number;
+    readonly layoutresult_states: (a: number, b: number) => void;
+    readonly layoutresult_values: (a: number, b: number) => void;
+    readonly listbuffer_byte_length: (a: number) => number;
+    readonly listbuffer_length: (a: number) => number;
+    readonly listbuffer_ptr: (a: number) => number;
+    readonly listbuffer_type_mask: (a: number) => number;
     readonly metricstable_fill: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly metricstable_fill_hinting: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly metricstable_fill_per_em: (a: number, b: number, c: number, d: number, e: number) => void;
@@ -71,6 +385,24 @@ export interface InitOutput {
     readonly metricstable_new: (a: number, b: number) => number;
     readonly metricstable_text_width: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
     readonly metricstable_wrap: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly operandsresult_cell_count: (a: number) => number;
+    readonly operandsresult_values: (a: number, b: number, c: number) => void;
+    readonly pivotrequest_add_column_field: (a: number) => number;
+    readonly pivotrequest_add_filter: (a: number) => number;
+    readonly pivotrequest_add_measure: (a: number, b: number, c: number, d: number) => void;
+    readonly pivotrequest_add_row_field: (a: number) => number;
+    readonly pivotrequest_add_values: (a: number, b: number, c: number) => void;
+    readonly pivotrequest_clear_measures: (a: number) => void;
+    readonly pivotrequest_compute: (a: number, b: number, c: number, d: number) => void;
+    readonly pivotrequest_new: (a: number) => number;
+    readonly pivotresult_cell: (a: number, b: number, c: number) => number;
+    readonly pivotresult_cell_count: (a: number) => number;
+    readonly pivotresult_column_nodes: (a: number, b: number) => void;
+    readonly pivotresult_records: (a: number, b: number, c: number) => void;
+    readonly pivotresult_row_cells: (a: number, b: number, c: number) => void;
+    readonly pivotresult_row_nodes: (a: number, b: number) => void;
+    readonly pivotresult_values: (a: number, b: number, c: number) => void;
+    readonly wasm_memory: () => number;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;

package/types/src/calculation/Calculation.d.ts

@@ -416,6 +416,14 @@ export declare class Calculation extends AbstractModel<AbstractModel.State, ICal
      * @internal
      */
     protected _evaluateOver(options: Calculation.EvaluateOverOptions): Promise<IRange>;
+    /**
+     * A host's values once its pass has landed. Each cell's async calls are waited for as `evaluate`
+     * waits for a formula's: until each has delivered, through the settle passes that land them.
+     * A clone, sharing storage until the grid writes, so it outlives the host.
+     */
+    private _settledValuesOf;
+    /** {@inheritDoc ICalculation.evaluateBatch} */
+    evaluateBatch(request: ICalculation.BatchRequest): Promise<IRange[]>;
     _createCalcGrid(options: Calculation.CalcGridOptions): CalcGrid;
     /** What a `create` for a model grid carries: its description. */
     protected _specOf(front: CalcGrid): CalcGridSpec;

package/types/src/calculation/ICalculation.d.ts

@@ -1,3 +1,4 @@
+import { Tuple } from '../collections';
 import { IRange, Scalar, IRuntime } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
@@ -168,6 +169,35 @@ export interface ICalculation extends IModel {
      * The expression is read as storage text unless `options.target` is `'display'`.
      */
     evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
+    /**
+     * Evaluates several formulas over values of the caller's, in one request.
+     *
+     * @param request The values and the formulas.
+     * @returns One range per {@link ICalculation.BatchRequest.formulas | formula}, in the order given,
+     * the shape of its `coords` (a single cell included), read with local coordinates:
+     * `getValueAt(0, 0)` is the top-left of `coords`.
+     *
+     * @remarks
+     * - The values and formulas sit on a grid of their own, on no sheet, kept for this request only.
+     *   Nothing in the workbook changes, and it is never an undo step.
+     * - A formula reads the values by address and may read another formula's cells; the engine
+     *   orders them. Each is filled across its `coords`, relative references moving with it.
+     * - A cell that errors carries its error; the others are unaffected.
+     *
+     * @example
+     * ```typescript
+     * const [margin, doubled] = await calculation.evaluateBatch({
+     *   values: [[0, [[0, [100, 60]]]], [1, [[0, [50, 40]]]]],
+     *   formulas: [
+     *     { expression: 'A1-B1', coords: { rowStart: 0, colStart: 2, rowEnd: 1, colEnd: 2 } },
+     *     { expression: 'C1*2', coords: { rowStart: 0, colStart: 3, rowEnd: 1, colEnd: 3 } }
+     *   ]
+     * });
+     * margin.getValueAt(1, 0); // 10
+     * doubled.getValueAt(1, 0); // 20
+     * ```
+     */
+    evaluateBatch(request: ICalculation.BatchRequest): Promise<IRange[]>;
     /**
      * When the engine recalculates on its own — Excel's Calculation Options.
      *
@@ -1066,6 +1096,27 @@ export declare namespace ICalculation {
     /**
      * Options for evaluating a formula.
      */
+    /** What {@link ICalculation.evaluateBatch} evaluates. */
+    interface BatchRequest {
+        /** The values the formulas read, by row: `[row, [[column, values]]]`, A1 at row 0, column 0. */
+        values: Tuple.GridTuple<Scalar>;
+        /** The formulas. One over cells that hold a value replaces it. */
+        formulas: readonly BatchFormula[];
+        /**
+         * How long to wait, in milliseconds, for the answers of async functions; a cell still waiting
+         * then answers a `#TIMEOUT!` error.
+         *
+         * @defaultValue `30000`
+         */
+        timeout?: number;
+    }
+    /** One formula of a {@link BatchRequest}. */
+    interface BatchFormula {
+        /** The expression, with or without a leading `=`, written for the top-left of {@link coords}. */
+        expression: string;
+        /** The cells it is filled across. */
+        coords: IRange.Coords;
+    }
     interface EvaluateOptions {
         /**
          * If specified, evaluates only the token span associated with this index.

package/types/src/calculation/compiler/Types.d.ts

@@ -247,6 +247,11 @@ export interface CompiledFormula {
      */
     symbolIds: string[];
     hasTotals: boolean;
+    /**
+     * Whether the formula calls `GETPIVOTDATA` anywhere in its tree: what is recalculated when the
+     * pivot tables it reads change (`ICalcGrid.setPivots`). Resolved as {@link hasTotals} is.
+     */
+    hasPivotData: boolean;
     hasDataTable: boolean;
     hasVolatile: boolean;
     isBlankCacheable: boolean;

package/types/src/calculation/executor/CalcExecutorUtils.d.ts

@@ -119,6 +119,6 @@ export declare function discoverDependencyBlock(depEntry: ISpatialMap.Entry<Prec
  * the anchor is inside the entry at all, since an entry that does not cover the anchor was never
  * in the anchor's dependents to begin with.
  */
-export declare function visitSpillBodyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, anchorRow: number, anchorCol: number, extentRowEnd: number, extentColEnd: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
+export declare function visitSpillBodyBlock(depEntry: ISpatialMap.Entry<PrecedentSpatialValue>, anchorRow: number, anchorCol: number, extentRowStart: number, extentColStart: number, extentRowEnd: number, extentColEnd: number, callbackFn: (calc: CalcNode) => void, mint?: MintWindow | null): void;
 export declare function valueCompareValues(a: ISpatialMap.Entry<FormulaSpatialValue>, removing: ISpatialMap.Entry<FormulaSpatialValue>): boolean;
 //# sourceMappingURL=CalcExecutorUtils.d.ts.map

package/types/src/calculation/formula/FormulaBlock.d.ts

@@ -80,6 +80,8 @@ export declare class FormulaBlock implements IFormulaBlock {
     getReferencedSymbolIds(): string[];
     /** @inheritdoc IFormulaBlock.hasTotals */
     hasTotals(): boolean;
+    /** @inheritdoc IFormulaBlock.hasPivotData */
+    hasPivotData(): boolean;
     /** @inheritdoc IFormulaBlock.hasDataTable */
     hasDataTable(): boolean;
     /** @inheritdoc IFormulaBlock.hasVolatile */

package/types/src/calculation/formula/IFormulaBlock.d.ts

@@ -334,6 +334,11 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * either all of them call a total function or none do.
      */
     hasTotals(): boolean;
+    /**
+     * Whether the formula calls `GETPIVOTDATA` anywhere in its tree; read off the compiled cache as
+     * {@link hasTotals} is. What is recalculated when the pivot tables change.
+     */
+    hasPivotData(): boolean;
     /**
      * Whether the formula calls `TABLE`, the what-if data table, anywhere in its tree. Read off the
      * compiled cache (`CompiledFormula.hasDataTable`).
@@ -380,5 +385,18 @@ export interface IFormulaBlock extends IFormulaBlockView {
      * @param other The other formula block to compare to.
      */
     isEquals(other: IFormulaBlock): boolean;
+    /**
+     * How far above and left of its cell a spilled result starts; absent, or `null`, for a result
+     * that spills from its cell, as every formula's does. An engine-only block placing a pivot
+     * table's cells answers the rows of its page fields.
+     */
+    getSpillOrigin?(): IFormulaBlock.SpillOrigin | null;
+}
+export declare namespace IFormulaBlock {
+    /** Rows above and columns left of the anchor where a spill's extent starts; never negative. */
+    interface SpillOrigin {
+        rows: number;
+        columns: number;
+    }
 }
 //# sourceMappingURL=IFormulaBlock.d.ts.map

package/types/src/calculation/grid/CalcGrid.d.ts

@@ -244,11 +244,13 @@ export declare class CalcGrid implements ICalcGrid {
     setHidden(axis: IRange.Axis, runs: readonly RunCoords[], options?: ICalcGrid.RequestOptions): void;
     /** {@inheritDoc ICalcGrid.setFiltered} */
     setFiltered(filtered: boolean, options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.setPivots} */
+    setPivots(pivots: readonly ICalcGrid.PivotJSON[], options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
     /**
      * Holds what the owner says of itself - its size, what it hides, whether it is filtered - in the
      * caller's operation: an undo restores it with whatever changed it.
      */
-    protected _holdOwnerState(update: Pick<Partial<CalcGrid.State>, 'hiddenRows' | 'hiddenColumns' | 'filtered' | 'entireCoords'>): void;
+    protected _holdOwnerState(update: Pick<Partial<CalcGrid.State>, 'hiddenRows' | 'hiddenColumns' | 'filtered' | 'pivots' | 'entireCoords'>): void;
     /** {@inheritDoc ICalcGrid.getId} */
     getId(): string;
     /** {@inheritDoc ICalcGrid.toJSON} */
@@ -362,6 +364,8 @@ export declare namespace CalcGrid {
         hiddenColumns: readonly RunCoords[] | null;
         /** Whether the owner is filtered. See {@link ICalcGrid.setFiltered}. */
         filtered: boolean;
+        /** The pivot tables on the grid; `null` for none. See {@link ICalcGrid.setPivots}. */
+        pivots: readonly ICalcGrid.PivotJSON[] | null;
         /** The grid's size; `null` for one that has the size of its {@link ConstructorOptions.sizeOf} grid. See {@link ICalcGrid.resize}. */
         entireCoords: IRange.Coords | null;
     }

package/types/src/calculation/grid/CalcGridBackend.d.ts

@@ -50,6 +50,8 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     protected _hiddenColumns: readonly RunCoords[] | null;
     /** Whether the owner is filtered ({@link ICalcGrid.setFiltered}). Versioned with the maps. */
     protected _filtered: boolean;
+    /** The pivot tables on the grid ({@link ICalcGrid.setPivots}); `null` for none. Versioned with the maps. */
+    protected _pivots: readonly ICalcGrid.PivotJSON[] | null;
     /**
      * @see CalcGridBackend.ConstructorOptions.unanchored
      */
@@ -164,6 +166,11 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * ({@link ICalcGrid.setFiltered}). Engine-side: not on {@link ICalcGrid}.
      */
     isFiltered(): boolean;
+    /**
+     * The pivot tables on the grid ({@link ICalcGrid.setPivots}); `null` for none. Engine-side: not
+     * on {@link ICalcGrid}.
+     */
+    getPivots(): readonly ICalcGrid.PivotJSON[] | null;
     /**
      * A range's skip (`IRange.IteratorOptions.processRowSkip`) over the rows or columns the owner
      * hides, for a range starting at `origin` on that axis; `null` when the hidden set does not
@@ -188,8 +195,28 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
     protected _setHiddenNow(axis: IRange.Axis, runs: readonly RunCoords[]): void;
     /** What a `filtered` request carries, held; as {@link _setHiddenNow}, the totals are owed a pass. */
     protected _setFilteredNow(filtered: boolean): void;
+    /**
+     * What a `pivots` request carries, held; every formula that calls `GETPIVOTDATA` is owed a
+     * pass, on every grid, as a total is ({@link _setHiddenNow}): a pivot changes no cell the graph
+     * reaches.
+     */
+    protected _setPivotsNow(pivots: readonly ICalcGrid.PivotJSON[] | null, cloneKey?: string | null): void;
+    /**
+     * Each laid-out pivot table's extent, anchored at its location's top-left: the grid's pivot
+     * extents are removed and those of `next` placed. The extents are found where they are now, not
+     * at `previous`'s anchors: a shift since the last request has moved them.
+     *
+     * @remarks
+     * The cells are the sheet's stored values: an extent owns none of them, so placing or removing
+     * one writes no value. It refuses a shift that would move part of the table
+     * ({@link SpillEntry.checkShift}), and a write inside it neither demotes nor removes it
+     * (`applyContentful`). A blocked table stores `#SPILL!` at its anchor and has no extent.
+     */
+    protected _placePivots(_previous: readonly ICalcGrid.PivotJSON[] | null, next: readonly ICalcGrid.PivotJSON[] | null, _cloneKey?: string | null): void;
     /** Mark every formula that calls a total function, on every grid, and ask for a pass. */
     protected _markTotals(): void;
+    /** Mark every formula `select` picks, on every grid, and ask for a pass. */
+    protected _markFormulas(select: (value: FormulaSpatialValue) => boolean): void;
     /** @inheritdoc ICalcGrid.getId */
     getShadowOf(): string | null;
     /** @inheritdoc ICalcGrid.isArrayFirstCell */
@@ -342,7 +369,13 @@ export declare class CalcGridBackend extends CalcGridProxy implements ICalcGrid.
      * Will update absolute precedents from precedentEntries relative precedents get shifted
      */
     protected _moveTo(snapshot: CalcGridSnapshot, from: IRange.Coords, to: IRange.Coords): void;
-    protected _notifyCalculated(cycleId: number, options: ICalculation.CalculateOptions | boolean): Promise<CalcResponse>;
+    /**
+     * Drain what is owed to the owner as one record, pushed through `onCalculated` and answered.
+     *
+     * @param commitId The snapshot the record answers for; `null` for none, the operation in
+     * progress; by default the last one a pass applied.
+     */
+    protected _notifyCalculated(cycleId: number, options: ICalculation.CalculateOptions | boolean, commitId?: string | null): Promise<CalcResponse>;
     /**
      * The write itself, on a `Running` engine. Records what it minted and removed for the vend rather
      * than taking it, so the engine's own callers (a reference edit, `recompileNamed`) leave the
@@ -484,6 +517,8 @@ export interface CalcGridMaps {
     hiddenColumns?: readonly RunCoords[] | null;
     /** Whether the owner is filtered. */
     filtered?: boolean;
+    /** The pivot tables on the grid. */
+    pivots?: readonly ICalcGrid.PivotJSON[] | null;
 }
 interface CalcGridSnapshot {
     calcGrid: CalcGridBackend;

package/types/src/calculation/grid/CalcGridProxy.d.ts

@@ -29,6 +29,8 @@ export declare class CalcGridProxy implements ICalcGrid.Backend {
     setHidden(axis: IRange.Axis, runs: readonly RunCoords[], options?: ICalcGrid.RequestOptions): void;
     /** {@inheritDoc ICalcGrid.setFiltered} */
     setFiltered(filtered: boolean, options?: ICalcGrid.RequestOptions): void;
+    /** {@inheritDoc ICalcGrid.setPivots} */
+    setPivots(pivots: readonly ICalcGrid.PivotJSON[], options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
     /** {@inheritDoc ICalcGrid.addListeners} */
     addListeners(listeners: ICalcGrid.IListeners, options?: IListener.Options): IListener.Remove;
     /** @inheritdoc ICalcGrid.setInputs */

package/types/src/calculation/grid/CalcGridUtils.d.ts

@@ -216,9 +216,11 @@ export declare function checkFixedSpillsShift(spillSpatial: ISpatialMap<SpillEnt
 /**
  * Finds all spills that intersect a range and removes them for operations.
  *
- * restore will behave differently depending on the top/left.
+ * restore will behave differently depending on the anchor.
  *
- * Outside of intersect: restore will put back to original location.
+ * Outside of intersect: restore will put back to original location, unless the anchor is past the
+ * intersect on the shifted axis (a spill whose extent starts above or left of its anchor, a pivot
+ * table's page fields): the shift moves that anchor, so the spill moves with it.
  * Inside intersect: Restore will either discard to move to restore Location if provided
  *
  * @returns a `restore` function or `null` that will restore spills.

package/types/src/calculation/grid/FormulaHost.d.ts

@@ -1,5 +1,5 @@
 import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
-import { ISparseGrid } from '../../collections';
+import { ISparseGrid, ISpatialMap, Tuple } from '../../collections';
 import { ITransaction } from '../../transaction';
 import { IFormulaBlockView } from '../formula';
 import { ICalcGrid } from './ICalcGrid';
@@ -242,6 +242,8 @@ export declare class FormulaHost {
      * longer exists), then the grid.
      */
     dispose(): void;
+    /** Values and formulas written together, inside the operation that makes them. */
+    setInputs(values: Tuple.Region<Scalar> | null, formulas: readonly ISpatialMap.Entry<string>[]): Promise<ICalcGrid.Results>;
     /**
      * A write to the model's grid, inside the operation that makes it; one made while no operation
      * is open - a name wired as the engine comes up - is folded into the commit the store is at,