@sheetxl/sdk 0.8.0-beta.15 → 0.8.0-beta.17

package/types/src/pivot/kernel/KernelPivot.d.ts

@@ -0,0 +1,63 @@
+import { IFormulaContext, IFunction, IRange, Scalar } from '@sheetxl/primitives';
+import { MemberColumnFactory } from './_PivotAxisTree';
+/**
+ * Records grouped by rows and by columns, by the Rust pivot kernel (`crates/sheetxl-pivot`) in the
+ * sdk's WebAssembly: one pass numbers every prefix of each axis and every crossing of the two, and
+ * each built-in aggregate asked for is one more pass over a value leaf.
+ *
+ * @remarks
+ * ### Not public API
+ *
+ * Reached as `IFormulaContext.createPivot`; a started engine has the WebAssembly. The keys become
+ * item ids on the host, by `UNIQUE`'s rule ({@link Items}), and a value column is written once
+ * into a leaf in the WebAssembly's memory. Members, for a function the kernel does not compute,
+ * come from a pass that keeps each crossing's records, run the first time one is asked for.
+ */
+export declare class KernelPivot implements IFormulaContext.Pivot {
+    private readonly _wasm;
+    private readonly _request;
+    private readonly _result;
+    private readonly _createColumn;
+    private readonly _recordCount;
+    /** The records, kept or not: every key and value column is this tall. */
+    private readonly _n;
+    private readonly _rows;
+    private readonly _columns;
+    /** Per column group, each row group's crossing with it; `Unset` where no record is in both. */
+    private readonly _cellsByColumn;
+    private readonly _errors;
+    private readonly _values;
+    private _leafCount;
+    /** The pass that kept each crossing's records, once members were asked for. */
+    private _withRecords;
+    /**
+     * The kernel's pivot of the keys.
+     *
+     * @throws `#VALUE!` when the kernel refuses them: more than {@link MaxFields} key columns on an
+     * axis, or more records, groups or crossings than it holds.
+     */
+    static create(rows: IRange | null, columns: IRange | null, createColumn: MemberColumnFactory, options?: IFormulaContext.PivotOptions): KernelPivot;
+    private static _addFields;
+    private static _fillFields;
+    private constructor();
+    /** @inheritdoc IFormulaContext.Pivot.getRecordCount */
+    getRecordCount(): number;
+    /** @inheritdoc IFormulaContext.Pivot.getRows */
+    getRows(): IFormulaContext.PivotAxis;
+    /** @inheritdoc IFormulaContext.Pivot.getColumns */
+    getColumns(): IFormulaContext.PivotAxis;
+    /** @inheritdoc IFormulaContext.Pivot.getMembers */
+    getMembers(values: IRange, row?: IFormulaContext.PivotGroup, column?: IFormulaContext.PivotGroup): IRange | null;
+    /** @inheritdoc IFormulaContext.Pivot.getAggregate */
+    getAggregate(values: IRange, fn: IFunction, row?: IFormulaContext.PivotGroup, column?: IFormulaContext.PivotGroup): Scalar | null | undefined;
+    /** The crossing of a row group and a column group, `Unset` where no record is in both. */
+    private _cell;
+    private _buffer;
+    private _addValues;
+    /**
+     * One pass for one reducer: per crossing its result. The kernel numbers the crossings the same
+     * way on every pass over the same keys, so they index the first pass's.
+     */
+    private _run;
+}
+//# sourceMappingURL=KernelPivot.d.ts.map

package/types/src/pivot/kernel/_KernelLeaves.d.ts

@@ -0,0 +1,100 @@
+import { FormulaError, IRange, Scalar } from '@sheetxl/primitives';
+import { MixedTypedArrayList } from '../../collections/MixedTypedArrayList';
+import { SdkWasmExports } from '../../wasm/sdkWasm';
+export type Request = InstanceType<SdkWasmExports['PivotRequest']>;
+export declare const Type: {
+    readonly Blank: 0;
+    readonly False: 1;
+    readonly True: 2;
+    readonly Int32: 3;
+    readonly Float64: 4;
+    readonly String: 5;
+    readonly Error: 6;
+    readonly Rich: 7;
+};
+/** Every type a value leaf may hold: width 8 and a type byte per value. */
+export declare const AllTypes = 127;
+export declare const Unset = 4294967295;
+/** The words of one node in the binding's flattened tree: parent, item, depth, first record, records. */
+export declare const NodeStride = 5;
+/** The kernel's reducer (its index in `Reducer::ALL`) for each built-in it computes. */
+export declare const ReducerOf: Readonly<Record<string, number>>;
+/** The variances read a column of numbers only: their sdk functions coerce a logical or text member. */
+export declare const FirstVariance = 7;
+/** The error code a division by zero is stored as: the first entry of every error table. */
+export declare const Div0Code = 0;
+/**
+ * Item ids for one key field, by the rule {@link defaultFrequencyKey} keys a group by (`UNIQUE`'s):
+ * equal ids, equal keys. Id 0 is the blank, so an unwritten id reads as one.
+ */
+export declare class Items {
+    private _next;
+    private readonly _numbers;
+    private readonly _keys;
+    /** Per codec, a string id's item, so a pool string is folded once, not once per record. */
+    private readonly _strings;
+    /** Each id's value, as first met; id 0 is the blank. */
+    readonly values: Scalar[];
+    of(value: Scalar | undefined): number;
+    /** Writes the ids of a range's values into `ids`, one per record. */
+    fill(range: IRange, ids: Uint32Array): void;
+    private _number;
+    private _run;
+}
+/** The errors a value leaf stores by code; code 0 is `#DIV/0!`. */
+export declare class Errors {
+    readonly table: FormulaError.Known[];
+    private readonly _codes;
+    codeOf(error: FormulaError.Known): number;
+}
+/** A value column in the request: its leaf, what it holds, and the results asked of it so far. */
+export interface ValueColumn {
+    readonly leaf: number;
+    /** No member is text or a logical. */
+    readonly numeric: boolean;
+    /** Per reducer, per group, then the grand total last. */
+    readonly results: (Scalar[] | undefined)[];
+}
+/**
+ * The views a value leaf of every type is written through: width 8, so an `int32` is the low word
+ * of its slot.
+ */
+export interface LeafViews {
+    readonly doubles: Float64Array;
+    readonly ints: Int32Array;
+    readonly types: Uint8Array;
+}
+/**
+ * Writes a range's values into a value leaf, or answers `false` at the first one a leaf cannot
+ * hold (a rich value, a lambda).
+ */
+export declare const writeValues: (range: IRange, views: LeafViews, errors: Errors) => {
+    ok: boolean;
+    numeric: boolean;
+};
+/**
+ * Writes one value into a value leaf at record `r`, clearing `written.ok` for a value a leaf
+ * cannot hold (a rich value, a lambda) and `written.numeric` for text or a logical.
+ */
+export declare const writeValue: (views: LeafViews, r: number, value: Scalar | undefined, errors: Errors, written: {
+    ok: boolean;
+    numeric: boolean;
+}) => void;
+/**
+ * The handle of a leaf the kernel allocated: its layout follows from its length and type mask, as
+ * `MixedTypedArrayList` lays one out.
+ */
+export declare const handleOf: (buffer: ArrayBufferLike, byteOffset: number, length: number, typeMask: number) => MixedTypedArrayList.Handle;
+/** A result leaf the kernel returned: where it is and what it holds. */
+export interface ResultLeaf {
+    ptr(): number;
+    length(): number;
+    type_mask(): number;
+}
+/**
+ * A reader of a result leaf, read in place in the WebAssembly's memory: valid until the leaf is
+ * freed or the memory grows. A number past the double range is `#NUM!`, as any function's
+ * non-finite result is.
+ */
+export declare const readLeaf: (buffer: ArrayBufferLike, leaf: ResultLeaf, errors: Errors) => (index: number) => Scalar;
+//# sourceMappingURL=_KernelLeaves.d.ts.map

package/types/src/pivot/kernel/_PivotAxisTree.d.ts

@@ -0,0 +1,71 @@
+import { IFormulaContext, IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * Builds the column a group's members come back in: `size` rows, with `values[i]` at `rows[i]`
+ * and every other row blank.
+ * @internal
+ */
+export type MemberColumnFactory = (size: number, rows: ArrayLike<number>, values: ArrayLike<Scalar>, count: number) => IRange;
+/**
+ * One axis of a pivot, from the arrays its builder filled: per group its parent, level, first
+ * record and size. Group objects are made on first ask; keys are read from the key columns then.
+ * @internal
+ */
+export declare class PivotAxisTree implements IFormulaContext.PivotAxis {
+    private readonly _keys;
+    private readonly _parents;
+    private readonly _levels;
+    private readonly _firsts;
+    private readonly _sizes;
+    private readonly _groups;
+    private _children;
+    private readonly _keyRows;
+    constructor(keys: IRange | null, parents: ArrayLike<number>, levels: ArrayLike<number>, firsts: ArrayLike<number>, sizes: ArrayLike<number>);
+    /** @inheritdoc IFormulaContext.PivotAxis.getRoot */
+    getRoot(): IFormulaContext.PivotGroup;
+    /** @inheritdoc IFormulaContext.PivotAxis.getGroupCount */
+    getGroupCount(): number;
+    /** The group numbered `id`, the root being `0`. */
+    group(id: number): PivotTreeGroup;
+    levelOf(id: number): number;
+    parentOf(id: number): PivotTreeGroup | null;
+    childrenOf(id: number): readonly PivotTreeGroup[];
+    keysOf(id: number): readonly Scalar[];
+    sizeOf(id: number): number;
+    firstRecordOf(id: number): number;
+}
+/**
+ * A group of a {@link PivotAxisTree}, by its number.
+ * @internal
+ */
+export declare class PivotTreeGroup implements IFormulaContext.PivotGroup {
+    private readonly _tree;
+    /** The group's number on its axis, the root being `0`. */
+    readonly id: number;
+    constructor(_tree: PivotAxisTree, 
+    /** The group's number on its axis, the root being `0`. */
+    id: number);
+    /** @inheritdoc IFormulaContext.PivotGroup.getLevel */
+    getLevel(): number;
+    /** @inheritdoc IFormulaContext.PivotGroup.getParent */
+    getParent(): IFormulaContext.PivotGroup | null;
+    /** @inheritdoc IFormulaContext.PivotGroup.getChildren */
+    getChildren(): readonly IFormulaContext.PivotGroup[];
+    /** @inheritdoc IFormulaContext.PivotGroup.getKeys */
+    getKeys(): readonly Scalar[];
+    /** @inheritdoc IFormulaContext.PivotGroup.getSize */
+    getSize(): number;
+    /** @inheritdoc IFormulaContext.PivotGroup.getFirstRecord */
+    getFirstRecord(): number;
+}
+/**
+ * The number of a group passed to a pivot: `0`, the root, when omitted.
+ * @internal
+ */
+export declare const groupId: (group: IFormulaContext.PivotGroup | undefined) => number;
+/**
+ * The members of `values` at `records`, one row per record, as {@link MemberColumnFactory}
+ * builds a column: only the non-blank ones are written.
+ * @internal
+ */
+export declare const membersAt: (values: IRange, records: ArrayLike<number>, createColumn: MemberColumnFactory) => IRange;
+//# sourceMappingURL=_PivotAxisTree.d.ts.map

package/types/src/primitives/Range.d.ts

@@ -1,5 +1,5 @@
 import { IRange, FormulaError, ScalarType, MaybeError, Scalar, IRangeStats, IRuntime } from '@sheetxl/primitives';
-import { Tuple, IGrid, ISparseGrid, ISpatialMap } from '../collections';
+import { Tuple, IGrid, ISparseGrid, ISpatialMap, IListLike } from '../collections';
 export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     protected _runtime: IRuntime;
     protected _values: ISparseGrid<Scalar>;
@@ -66,6 +66,17 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
      * @internal
      */
     _materializeEmpty(): this;
+    /**
+     * Visits a one-column range's stored values leaf by leaf, for a reader that loops typed leaves
+     * rather than entries: `visit(row, list, from, to)` covers the range's rows `row` to
+     * `row + to - from` with `list.at(from)` to `list.at(to)`, where `list` is never an
+     * `ImmutableList` (its leaves are visited instead). A row no leaf covers is blank.
+     *
+     * @returns `false`, having visited nothing, when the range is not one column of a column-major
+     * grid or reads with skips; read its entries instead.
+     * @internal
+     */
+    _visitColumnRuns(visit: (row: number, list: IListLike<Scalar>, from: number, to: number) => void): boolean;
     /** @inheritdoc IRange.filter */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): this;
     /** @inheritdoc IRange.firstError */

package/types/src/sheet/IWorksheet.d.ts

@@ -28,6 +28,7 @@ import { IModule, IModuleCollection } from '../scripting';
 import { IChartCollection } from '../chart';
 import { INamedCollection } from '../named';
 import { ICalculation } from '../calculation';
+import { IFontCollection } from '../font';
 import { IWorksheetView } from '../sheetView';
 import { ISheetHeader } from '../sheetHeader';
 import { IWorksheetProtection } from '../sheetProtection';
@@ -578,6 +579,14 @@ export interface IWorksheet extends ISheet, ITransaction.ITransactional, IListen
      * own sheet).
      */
     getCalculation(): ICalculation;
+    /**
+     * Returns the {@link IFontCollection} the sheet measures text with.
+     *
+     * @remarks
+     * Fonts are shared: every sheet, with or without a workbook, returns the same collection, so a
+     * face loaded for one is loaded for all.
+     */
+    getFonts(): IFontCollection;
     /**
      * Recalculates THIS sheet — Excel's "Calculate Sheet" (Shift+F9) / `Worksheet.Calculate`.
      *
@@ -614,6 +623,25 @@ export interface IWorksheet extends ISheet, ITransaction.ITransactional, IListen
      *   it has not been started.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /**
+     * Returns when every font the sheet measures with has loaded and every autofit that was taken
+     * with a stand-in meanwhile has been taken again.
+     *
+     * @remarks
+     * Measuring never waits: a style naming a face not yet loaded measures with a related or
+     * built-in one and the lookup starts the load, the way a browser paints with a fallback until
+     * a web font arrives. This is the point after which sizes are final. Fonts are shared, so this
+     * also waits for faces other sheets and workbooks started loading; a load that fails leaves its
+     * stand-in and still settles.
+     *
+     * The same point as {@link IWorkbook.whenFontsReady}; a sheet without a workbook has it here.
+     */
+    whenFontsReady(): Promise<void>;
+    /**
+     * Returns when the sheet is settled: {@link whenCalculationReady} and {@link whenFontsReady}
+     * both hold.
+     */
+    whenReady(): Promise<void>;
     /**
      * Returns the {@link IWorkbook} for the sheet.
      *
@@ -952,6 +980,13 @@ export declare namespace IWorksheet {
          * Called when any table are added or removed.
          */
         onTablesChange?(source: IWorksheet): void;
+        /**
+         * Called when a pivot table changes: its style, its layout, or where it sits.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}.
+         */
+        onPivotTablesChange?(source: IWorksheet): void;
         /**
          * Called when any data validation is added, removed, re-anchored, or re-evaluates its results.
          *

package/types/src/sheet/SheetCell.d.ts

@@ -5,8 +5,6 @@ import { IProperties, ITypes } from '../type';
 import { NumberFormat } from '../numFmt';
 import { ITextFrame, IRichText } from '../text';
 import { IRichDataKind } from '../richData/IRichDataKind';
-import { ITable } from '../table';
-import { IDataValidation } from '../dataValidation';
 import { IHyperlink } from '../hyperlink';
 import { ICalculation } from '../calculation';
 import { IComment } from '../comment';
@@ -22,6 +20,7 @@ import { CellStyleUpdater } from './style/SheetCellStyle';
 import { ICalcGrid } from '../calculation/grid';
 import { IConditionalFormat } from '../conditionalFormat';
 import { ICellControl } from '../cellControl/ICellControl';
+import { PivotLabelInset } from '../pivot/_PivotControls';
 /**
  * CellModifiers with all functions removed and all properties set and a type.
  */
@@ -67,12 +66,19 @@ isParsingCustom?: boolean, destination?: IRange.CellCoords | null, quotePrefixOn
  */
 export declare function csConditionalDecorations(conditionals: IConditionalFormat | IConditionalFormat[] | null | undefined, rowIndex: number, colIndex: number, value: Scalar, getStyle: () => ICellStyle): Readonly<IConditionalFormat.Decorations>;
 export declare const csIconGutter: (style: ICellStyle) => number;
+/**
+ * What a pivot label's leading inset adds to the one its style gives it: the label is set in by its
+ * table ({@link pivotLabelLayoutOf}), not by the indent in its format, so this replaces that indent
+ * with the table's level and box. Read the same way by {@link SheetCell.getInsets}, autoFit and the
+ * overflow walk.
+ */
+export declare const csPivotLead: (type: ScalarType, style: ICellStyle, label: PivotLabelInset) => number;
 export declare function csOverflowable(type: ScalarType, style: ICellStyle, prev?: boolean, next?: boolean): boolean;
 /**
  * Updates the overflow calc and returns a range if overflowed
  * @internal
  */
-export declare function calcTextOverflow(rowIndex: number, colIndex: number, type: ScalarType, style: ICellStyle, value: Scalar, prev: IRange.CellCoords | null, next: IRange.CellCoords | null, continuousCoords: IRange.Coords | null, cellOptions: SheetCellOptions): ICell.HorizontalOverflow | null;
+export declare function calcTextOverflow(rowIndex: number, colIndex: number, type: ScalarType, style: ICellStyle, value: Scalar, prev: IRange.CellCoords | null, next: IRange.CellCoords | null, continuousCoords: IRange.Coords | null, cellOptions: SheetCellOptions, leading?: number): ICell.HorizontalOverflow | null;
 /** Guaranteed to never return null */
 export declare function csStyle(value: Scalar, range: IRange.Coords | null, intersection: RangeState.Intersection | null, options: SheetCellOptions, direct: boolean, 
 /**
@@ -193,7 +199,6 @@ export declare class SheetCell implements ICell {
     protected _v: Scalar;
     protected _d: Date | null | undefined;
     protected _dfmt: string | null;
-    protected _column: ITable.IColumn | null | undefined;
     protected _cd: Readonly<IConditionalFormat.Decorations> | undefined;
     protected _s: ICellStyle | undefined;
     protected _sd: ICellStyle | undefined;
@@ -229,12 +234,6 @@ export declare class SheetCell implements ICell {
      * @internal
      */
     _openAddress(address: string, options: ITypes.SelectOptions | null, target?: string, features?: string): Promise<boolean>;
-    /** {@inheritDoc ICell.getColumn} */
-    getColumn(): ITable.IColumn | null;
-    /** {@inheritDoc ICell.getTable} */
-    getTable(): ITable | null;
-    /** {@inheritDoc ICell.getDataValidation} */
-    getDataValidation(): IDataValidation | null;
     /** {@inheritDoc ICell.getConditionalDecorations} */
     getConditionalDecorations(): Readonly<IConditionalFormat.Decorations>;
     /** {@inheritDoc ICell.getControl} */
@@ -260,14 +259,22 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getInsets} */
     getInsets(): Rectangle;
     /**
-     * The leading-edge width this cell's icon-set decoration reserves, or `0` for a cell without one.
+     * The leading-edge width this cell's icon-set decoration reserves, and what its pivot table's
+     * level and expand/collapse box add; `0` for a cell with neither.
      *
      * @remarks
-     * See {@link csIconGutter} for what the reservation is made of. Every measurement of the cell —
-     * insets, best-fit, the editor's caret — reads it from here, so they cannot disagree with the
-     * icon layer, which places the icon from the same two style numbers.
+     * See {@link csIconGutter} and {@link csPivotLead} for what the reservation is made of. Every
+     * measurement of the cell — insets, best-fit, overflow, the editor's caret — reads it from here,
+     * so they cannot disagree with the icon layer or the pivot layer, which place their marks from
+     * the same style numbers. A pivot label keeps the box's gutter whether or not it has a box, as
+     * Excel lines up a level's labels.
      */
     protected _iconGutter(): number;
+    /**
+     * How this cell is set in as a label of the pivot table placed over it: its level's indent and
+     * whether it keeps a box's gutter; `null` for a cell that is not one.
+     */
+    protected _pivotLabel(): PivotLabelInset | null;
     /** {@inheritDoc ICell.getTextFrame} */
     getTextFrame(showFormula?: boolean): ITextFrame | null;
     /** {@inheritDoc ICell.getTextPlacement} */

package/types/src/sheet/SheetRange.d.ts

@@ -7,6 +7,7 @@ import { ICellRange, ICellRegions, ICellRanges, ICellHeaderRange } from '../cell
 import { IComment, ICommentCollection } from '../comment';
 import { ICellStyle } from '../style';
 import { ITable, ITableCollection } from '../table';
+import { IPivotTable } from '../pivot';
 import { IMovable, IMovableCollection } from '../movable';
 import { IHyperlink } from '../hyperlink';
 import { IRichText } from '../text';
@@ -353,6 +354,8 @@ export declare class SheetRange implements ICellRange {
     getComments(options?: ICellRange.GetItemsOptions<ICommentCollection.GetItemsOptions>): IComment[];
     /** {@inheritDoc ICellRange.getTables} */
     getTables(options?: ICellRange.GetItemsOptions<ITableCollection.GetItemsOptions>): ITable[];
+    /** {@inheritDoc ICellRange.getPivotTables} */
+    getPivotTables(): IPivotTable[];
     /** {@inheritDoc ICellRange.getMovables} */
     getMovables(options?: ICellRange.GetItemsOptions<IMovableCollection.GetItemsOptions>): IMovable[];
     /** {@inheritDoc ICellRange.getSnapshot} */