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

package/types/src/pivot/_PivotUtils.d.ts

@@ -0,0 +1,37 @@
+import { IRange } from '@sheetxl/primitives';
+import { IPivotTable } from './IPivotTable';
+/**
+ * A plain A1 reference as the part spells it (`B3`, `A1:A7`, relative) made absolute, which is how
+ * it is held: a relative endpoint in a body that has no position is left where it is written,
+ * and these name fixed cells.
+ */
+export declare function absoluteA1(ref: string): string;
+/** The held text back in the part's spelling: relative. */
+export declare function relativeA1(ref: string): string;
+/**
+ * The cells a pivot table is laid out on, as coords on its own sheet, or `null` when its location
+ * is not one it can be anchored at.
+ */
+export declare function locationCoordsOf(json: IPivotTable.JSON | undefined): IRange.Coords | null;
+/**
+ * How many rows and columns a table's page fields take above its location, and after how many
+ * fields they wrap: down then across, or across then down with `pageOverThenDown`. All 0 when it
+ * has none.
+ */
+export declare function pageCountsOf(json: Pick<IPivotTable.JSON, 'pageFields' | 'pageWrap' | 'pageOverThenDown'>): {
+    rows: number;
+    columns: number;
+    wrap: number;
+};
+/**
+ * The cells a laid-out table shows a field button on, as {@link IPivotTable.JSON.buttons} holds
+ * them, or `null` when it has not been laid out ({@link IPivotTable.JSON.header}).
+ *
+ * @remarks
+ * As Excel places them (`pivotLayout.xlsx`, `pivotDefinitionSettings.xlsx`): each page field's
+ * caption; each row-label column of the row header; the column header's caption, beside the one
+ * data field's caption when there are row fields too. One button per column field outside compact
+ * form is assumed, not probed.
+ */
+export declare function buttonsOf(json: IPivotTable.JSON): string[] | null;
+//# sourceMappingURL=_PivotUtils.d.ts.map

package/types/src/pivot/engine/PivotAdd.d.ts

@@ -0,0 +1,37 @@
+import { IPivotTable } from '../IPivotTable';
+import { IPivotTableCollection } from '../IPivotTableCollection';
+import { PivotSourceRead } from './PivotRefresh';
+/** A cache's contents for a source read for the first time. */
+export declare const newPivotCache: (read: PivotSourceRead, source: IPivotTable.CacheSourceJSON, date1904: boolean) => Omit<IPivotTable.CacheJSON, "cacheId" | "part" | "partFormats">;
+/**
+ * A cache whose `fields` list their items rather than hold their values in the records: a table can
+ * only name a listed item, so a field placed on an axis is one, as Excel makes it when placing it.
+ *
+ * @returns `cache` itself when they all are already.
+ */
+export declare const withListedFields: <T extends Pick<IPivotTable.CacheJSON, "fields">>(cache: T, fields: readonly number[]) => T;
+/** The fields a table's definition places on an axis. */
+export declare const axisFieldsOf: (table: Pick<IPivotTable.JSON, "rowFields" | "columnFields" | "pageFields">) => number[];
+/**
+ * What a table lists for a field it places for the first time: a grouping's groups in their order, any
+ * other's items sorted by label, by no standing sort, so a new item goes last (A14, M16).
+ */
+export declare const listedItemsOf: (cache: IPivotTable.CacheJSON, field: number) => IPivotTable.PivotItemJSON[];
+/**
+ * @throws ExpectedError for a format that does not parse, or the id of no built-in one.
+ */
+export declare const assertNumberFormat: (format: string | number) => void;
+/**
+ * A data field over a field of the cache, as Excel makes one: the function by what the field holds
+ * unless asked for, the caption `Sum of Sales`, numbered, unless named (A07, D01, D26).
+ *
+ * @throws ExpectedError for a caption taken, a function that is none or a format that does not parse.
+ */
+export declare const newDataField: (table: Pick<IPivotTable.JSON, "fields" | "dataFields" | "valuesCaption">, cache: IPivotTable.CacheJSON, field: number, input?: Omit<IPivotTable.IDataField.Input, "field">) => IPivotTable.DataFieldJSON;
+/**
+ * The definition of a new table over `cache`, not yet laid out.
+ *
+ * @throws ExpectedError for a field the cache does not hold, or a value's caption Excel refuses.
+ */
+export declare const newPivotTable: (cache: IPivotTable.CacheJSON, options: IPivotTableCollection.AddOptions | undefined) => Omit<IPivotTable.JSON, "name" | "cacheId" | "location">;
+//# sourceMappingURL=PivotAdd.d.ts.map

package/types/src/pivot/engine/PivotData.d.ts

@@ -0,0 +1,65 @@
+import { IPivotTable } from '../IPivotTable';
+/**
+ * What an edit of a table's values does to its definition, as Excel's
+ * (`pivot-probes/probe-pivot-data-fields.ps1`, `-fields2`, `-fields3`). Pure: the table lays itself out
+ * from what comes back.
+ */
+type Editable = Pick<IPivotTable.JSON, 'fields' | 'rowFields' | 'columnFields' | 'pageFields' | 'dataFields' | 'filters' | 'formats' | 'conditionalFormats' | 'valuesOnRows' | 'valuesPosition' | 'valuesCaption'>;
+/**
+ * `table` with a new data field, last. Its source leaves any axis it is on, with what a field taking
+ * that step keeps (D01, D27): setting it on an axis afterwards holds both.
+ *
+ * @throws ExpectedError for a caption taken, a function that is none or a format that does not parse.
+ */
+export declare const addPivotDataField: <T extends Editable>(table: T, cache: IPivotTable.CacheJSON, field: number, input?: Omit<IPivotTable.IDataField.Input, "field">) => T;
+/** `table` without a data field; without any when `data` is absent (D16). */
+export declare const removePivotDataField: <T extends Editable>(table: T, data?: number) => T;
+/**
+ * `table` with a data field at `position`, counted from 1.
+ *
+ * @returns `table` itself when it is there already.
+ * @throws ExpectedError for a position it cannot take.
+ */
+export declare const movePivotDataField: <T extends Editable>(table: T, data: number, position: number) => T;
+/**
+ * `table` with a data field's function. Its caption follows: what comes before its first ` of ` takes the
+ * function's name, a caption without one becomes the default, and a caption taken is numbered (D04, D05,
+ * D20, D21, D30). Its format stays.
+ *
+ * @returns `table` itself when the function is the field's already.
+ * @throws ExpectedError for a function that is none.
+ */
+export declare const setPivotDataFunction: <T extends Editable>(table: T, cache: IPivotTable.CacheJSON, data: number, name: string) => T;
+/**
+ * `table` with a data field shown as `rule`, or as is for `null`. A new base field starts at its first item
+ * (D22). The base stays through a change of kind and through `null` (D22); the number format is judged by
+ * {@link formatAfterKind} when the kind changes, the formats on single cells staying over it (D22).
+ *
+ * @returns `table` itself when nothing changes.
+ * @throws ExpectedError for a kind that is none, or a base field or item the table does not have.
+ */
+export declare const setPivotDataShowAs: <T extends Editable>(table: T, cache: IPivotTable.CacheJSON, data: number, rule: IPivotTable.IDataField.ShowAs | null) => T;
+/**
+ * `table` with a data field's number format, over any format a single cell of its values holds, whose
+ * other settings stay (D10, D23). Excel's own shape: the field's format and one more format on the table
+ * over all its values, replaced by the next.
+ *
+ * @returns `table` itself when the format is on top already.
+ * @throws ExpectedError for a format that does not parse.
+ */
+export declare const setPivotDataNumberFormat: <T extends Editable>(table: T, data: number, format: string | number) => T;
+/**
+ * `table` with the values on an axis, at `position` among its fields, counted from 1; absent, last, and
+ * nothing when they are on it. `null` takes every value off the table (D16).
+ *
+ * @throws ExpectedError for an axis the values cannot take, or a position not on it (D16, D24).
+ */
+export declare const movePivotValues: <T extends Editable>(table: T, axis: IPivotTable.Axis | null, position?: number) => T;
+/**
+ * `table` with the values' caption. It shares its namespace with the fields and the data fields (D24, D26).
+ *
+ * @throws ExpectedError for a caption taken.
+ */
+export declare const renamePivotValues: <T extends Editable>(table: T, cache: IPivotTable.CacheJSON, name: string) => T;
+export {};
+//# sourceMappingURL=PivotData.d.ts.map

package/types/src/pivot/engine/PivotEdit.d.ts

@@ -0,0 +1,45 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IPivotTable } from '../IPivotTable';
+import { PivotModel } from '../_PivotItems';
+import { PivotCellRole } from './PivotLayout';
+/**
+ * A table with an item of a field renamed, as Excel's `PivotItem.Caption` takes it
+ * (`pivot-probes/probe-pivot-items.ps1`, I05): the text as given, spaces and all, empty allowed;
+ * its value's own text restores the original. Under a sort by label the field is sorted again, as
+ * Excel sorts by the caption (I05c). The item's cell shows the caption; `GETPIVOTDATA` finds it by
+ * the caption or by its value.
+ *
+ * @param rank The item's place in the field's listed items.
+ * @returns The table as edited, or `table` itself when the item already has the name.
+ * @throws ExpectedError When another item of the field has the name, without regard to case, as
+ * Excel refuses (I05a).
+ */
+export declare const renamePivotItem: <T extends PivotModel>(table: T, cache: IPivotTable.CacheJSON, field: number, rank: number, name: string) => T;
+/**
+ * A table with an item of a field moved along its field's listed items, as Excel's
+ * `PivotItem.Position` and a label typed over with another item's name do
+ * (`pivot-probes/probe-pivot-items.ps1`, I01-I04; `probe-pivot-items-followup.ps1`): the field's
+ * order is then by hand, so a sort it had ends, by label or by value, and holds through a refresh.
+ * Whatever names an item by its place in the list follows it ({@link reorderPivotItems}).
+ *
+ * @param from The item's place in the field's listed items.
+ * @param to Its new place, in the list without it.
+ * @returns The table as edited, or `table` itself when the item is already there and the field has
+ * no sort to end.
+ */
+export declare const movePivotItem: <T extends PivotModel>(table: T, field: number, from: number, to: number) => T;
+/**
+ * A table with `value` typed over a cell of it, as Excel takes it
+ * (`pivot-probes/probe-pivot-edit.ps1`):
+ * - over an item's label, the item is renamed; over it with another item's name, that item moves
+ *   there instead;
+ * - over a field's caption, a data field's name, a compact table's header or the grand total's
+ *   caption, that caption is renamed; a field or data field cannot take a name another field has;
+ * - over a page field's item, the page field shows the item named, or every item for `(All)`.
+ *
+ * @param role What the cell is ({@link PivotLayout.roles}).
+ * @returns The table as edited; the caller lays it out again.
+ * @throws ExpectedError where Excel refuses the value.
+ */
+export declare const typeOverPivot: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, role: PivotCellRole, value: Scalar) => IPivotTable.JSON;
+//# sourceMappingURL=PivotEdit.d.ts.map

package/types/src/pivot/engine/PivotFilters.d.ts

@@ -0,0 +1,50 @@
+import { IRuntime, Scalar } from '@sheetxl/primitives';
+import { ICalculation } from '../../calculation';
+import { IPivotTable } from '../IPivotTable';
+import { isItemFilter } from '../_PivotItems';
+import { CalculatedRecords } from './PivotFormulas';
+export { isItemFilter };
+/**
+ * What a table's filters keep, for a layout to read ({@link layOutPivot}).
+ */
+export interface PivotFilterResult {
+    /**
+     * Per field with a label or date filter, per cache item id: `1` where the item passes every one
+     * of them. An item that fails is left out as a hidden item is.
+     */
+    readonly keep: ReadonlyMap<number, Uint8Array>;
+    /**
+     * Per record, which axes keep it after the value and top filters, which drop groups (an item
+     * under one outer item, which another outer item may keep): {@link KeepRows} unless a filter on a
+     * row field dropped it, {@link KeepColumns} unless one on a column field did. A record makes items
+     * on the axes that keep it and counts in a value only with both, as Excel's other axis keeps the
+     * items such a filter empties. Absent when none drops any.
+     */
+    readonly records?: Uint8Array;
+    /** The records a table's calculated items add ({@link calculatedRecordsOf}), when it has them. */
+    readonly calculatedRecords?: CalculatedRecords | null;
+    /** Per data field with a formula, its values: one per cell of the kernel's pass, then a crossing with no cell. */
+    readonly fieldValues?: ReadonlyMap<number, Scalar[]> | null;
+}
+/**
+ * Runs a table's filters, as the conditions model runs any condition. A label filter
+ * (Display-shaped) tests each item's caption, as its cell shows it, `(blank)` included, given as
+ * the value itself; a date filter tests the item's value, a date being a number. A value or top
+ * filter tests each item's total of its data field within each item of the fields outside it, the
+ * items under one outer item being the population a top filter ranks; the totals count only what
+ * the filters before it keep. Label and date filters apply first, then the others in their
+ * `evalOrder`; two filters on one field both apply.
+ *
+ * @remarks
+ * Async, as every condition is: one may carry a formula, which the engine evaluates.
+ */
+export declare const evaluatePivotFilters: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, runtime: IRuntime, calculation?: ICalculation | null) => Promise<PivotFilterResult>;
+/**
+ * `model` with each relative date filter's `anchorDate` set to `today`, as a relayout evaluates them
+ * again: Excel holds the window a period was last evaluated over until the table is laid out
+ * (`pivot-probes/probe-pivot-relative-dates.ps1`). `model` itself when none changes.
+ *
+ * @param today The day, as a whole serial.
+ */
+export declare const anchorPivotPeriods: <T extends Pick<IPivotTable.JSON, "filters">>(model: T, today: number) => T;
+//# sourceMappingURL=PivotFilters.d.ts.map

package/types/src/pivot/engine/PivotFormulas.d.ts

@@ -0,0 +1,72 @@
+import { IRuntime, Scalar } from '@sheetxl/primitives';
+import { ICalculation } from '../../calculation';
+import { IPivotTable } from '../IPivotTable';
+/**
+ * A table's calculated fields and items, by Excel's rules (PLAN-PIVOT §4.7,
+ * `pivot-probes/probe-pivot-calculated.ps1`). A formula names fields or items, never cells, and reads
+ * totals: rollup first, then the formula, then the layout. A table's formulas go to the calc service
+ * as one request ({@link ICalculation.evaluateBatch}), each written over columns of values.
+ */
+/** What a formula's names become: a reference; `null` for a name it does not know, left as it is. */
+type Resolve = (field: string, item: string | null) => string | null;
+/**
+ * A pivot formula with its field and item names replaced: `Sales-Cost`, `'Unit Price'*2`,
+ * `Region[North]+Region['North East']`.
+ *
+ * @returns The formula, or `null` when it names an item {@link Resolve} does not: a position
+ * (`Region[+1]`) or one the field does not list.
+ */
+export declare const rewriteFormula: (formula: string, resolve: Resolve) => string | null;
+/** The fields a data field's formula reads, the columns of the source, a formula's own followed. */
+export interface FieldFormulas {
+    /** The cache fields the formulas read, each rolled up as a sum. */
+    readonly operands: readonly number[];
+    /** The cache fields with a formula the data fields need, each read by those after it. */
+    readonly formulas: readonly {
+        readonly field: number;
+        readonly expression: string;
+    }[];
+    /** Per data field with a formula, its index and which of {@link formulas} it shows. */
+    readonly measures: readonly {
+        readonly data: number;
+        readonly formula: number;
+    }[];
+}
+/**
+ * What the data fields' formulas need, or `null` when a formula cannot be written over columns.
+ * A table with none has none of each.
+ */
+export declare const fieldFormulasOf: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON) => FieldFormulas | null;
+/**
+ * The data fields' values from what the rollup gave, one per cell and then what a crossing with no
+ * cell shows, in one request.
+ *
+ * @param operands Per {@link FieldFormulas.operands}, its sum per cell.
+ * @returns Per data field with a formula, its values.
+ */
+export declare const evaluateFieldFormulas: (plan: FieldFormulas, operands: readonly (readonly Scalar[])[], cells: number, calculation: ICalculation) => Promise<Map<number, Scalar[]>>;
+/** Records a table's calculated items add to its cache's, each holding the item's value at a crossing. */
+export interface CalculatedRecords {
+    /** How many. */
+    readonly count: number;
+    /** Per cache field, each record's item id. */
+    readonly ids: readonly (readonly number[])[];
+    /** Per data field, each record's value. */
+    readonly values: readonly (readonly Scalar[])[];
+}
+/**
+ * The records that make a table's calculated items show: one per item per crossing of the other
+ * fields on its axes, so a total adds the item as it adds any line, a sort or a filter reads it, and
+ * an item hidden leaves them. Under a count, as many as the count, each worth 1. The item shows under
+ * every outer item with records and with every item of the fields inside it and across, 0 where its
+ * members have none (S06, S27, S29, CI11).
+ *
+ * A member hidden still counts, its records read here whatever the table hides of its own field; one
+ * gone from the source is 0.
+ *
+ * @returns The records; `null` when the table has calculated items this cannot lay out: more than one
+ * field's, beside a calculated field, under another function, or a formula naming a position.
+ */
+export declare const calculatedRecordsOf: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, runtime: IRuntime, calculation: ICalculation, keep?: ReadonlyMap<number, Uint8Array>) => Promise<CalculatedRecords | null>;
+export {};
+//# sourceMappingURL=PivotFormulas.d.ts.map

package/types/src/pivot/engine/PivotLayout.d.ts

@@ -0,0 +1,133 @@
+import { IRuntime, Scalar } from '@sheetxl/primitives';
+import { ICalculation } from '../../calculation';
+import { Tuple } from '../../collections';
+import { IPivotTable } from '../IPivotTable';
+import { PivotFilterResult } from './PivotFilters';
+import { CalculatedRecords } from './PivotFormulas';
+import { formatCodeOf } from '../_PivotStructure';
+/** `KEEP_ROWS`, `KEEP_COLUMNS`: a record mask's bits, the axes whose items keep the record. */
+export declare const KeepRows = 1;
+export declare const KeepColumns = 2;
+/**
+ * A pivot table laid out: its cells, and the lines and offsets Excel stores beside them.
+ */
+export interface PivotLayout {
+    /**
+     * The table's cells from the location's top-left, in the order {@link LayOutOptions.cellOrder}
+     * asks for: a value, a label or a caption. The page fields sit at negative rows, above a blank
+     * row over the location. Blanks are not stored.
+     */
+    readonly cells: Tuple.GridTuple<Scalar>;
+    /** How many rows and columns the location covers. */
+    readonly rows: number;
+    readonly columns: number;
+    /** How many rows and columns of page fields there are. */
+    readonly rowPageCount: number;
+    readonly columnPageCount: number;
+    readonly header: IPivotTable.PivotHeaderJSON;
+    readonly rowLines: IPivotTable.PivotLineJSON[];
+    readonly columnLines: IPivotTable.PivotLineJSON[];
+    /**
+     * The values the table shows, keyed for `GETPIVOTDATA` (`ICalcGrid.PivotJSON.values`): per data
+     * field, the item of each row and column field, `-1` past a line's depth. An empty crossing is 0.
+     */
+    readonly viewValues: [string, Scalar][];
+    /**
+     * The key in {@link viewValues} of the first cell of the data area - the first row line's
+     * crossing with the first column line - or `null` when the table has none.
+     */
+    readonly firstKey: string | null;
+    /**
+     * What each label and caption cell is, by `row,column` as {@link cells} places them; asked for
+     * ({@link LayOutOptions.roles}). A cell without one - a value, a total, a subtotal's caption -
+     * takes no edit.
+     */
+    readonly roles?: ReadonlyMap<string, PivotCellRole>;
+}
+/** Options for {@link layOutPivot}. */
+export interface LayOutOptions {
+    /** Say what each label and caption cell is ({@link PivotLayout.roles}). */
+    roles?: boolean;
+    /**
+     * What the table's filters keep ({@link evaluatePivotFilters}), for the definition and cache laid
+     * out; without it a table with filters is not laid out.
+     */
+    filters?: PivotFilterResult | null;
+    /**
+     * The order of {@link PivotLayout.cells}: `rows`, the default, is major by row (`[row, [[column,
+     * run]]]`), `columns` major by column (`[column, [[row, run]]]`), so a sheet that stores by column
+     * takes the runs as they are.
+     */
+    cellOrder?: 'rows' | 'columns';
+    /**
+     * The fields the table's slicers filter, by cache index: their hidden items keep records out, on
+     * an axis or not ({@link withSlicerPages}).
+     */
+    slicerFields?: readonly number[];
+}
+/**
+ * What a laid-out cell is, for a value typed over it (`pivot-probes/probe-pivot-edit.ps1`):
+ * - `item`: an item's label on rows or columns, `rank` its index in the field's items;
+ * - `fieldCaption`: a field's caption, over an outline or tabular field or beside a page field;
+ * - `rowHeader`, `columnHeader`: a compact table's captions;
+ * - `dataCaption`: a data field's name;
+ * - `grandTotal`: the grand total's caption;
+ * - `pageItem`: the item a page field shows, `page` its index in the page fields.
+ */
+export type PivotCellRole = {
+    readonly kind: 'item';
+    readonly field: number;
+    readonly rank: number;
+} | {
+    readonly kind: 'fieldCaption';
+    readonly field: number;
+} | {
+    readonly kind: 'rowHeader';
+} | {
+    readonly kind: 'columnHeader';
+} | {
+    readonly kind: 'dataCaption';
+    readonly data: number;
+} | {
+    readonly kind: 'grandTotal';
+} | {
+    readonly kind: 'pageItem';
+    readonly page: number;
+};
+/**
+ * Lays out a modeled pivot table from its cache's records, as Excel lays it out on a refresh.
+ *
+ * @returns The layout, or `null` when the WebAssembly has not loaded, the table has filters and
+ * {@link LayOutOptions.filters} is not given, or the table asks for what is not laid out yet:
+ * a calculated item, a field the records do not hold that groups nothing, a value its group cannot
+ * hold, or a custom subtotal function.
+ */
+export declare const layOutPivot: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, runtime: IRuntime, options?: LayOutOptions) => PivotLayout | null;
+/** What {@link itemTotalsOf} gives a value or top filter. */
+export interface PivotItemTotals {
+    /** The fields outside the filtered one on its axis, outermost first. */
+    readonly outer: readonly number[];
+    /** Per item of the outer fields (their item ids, joined by `,`), the filtered field's items with data and their totals. */
+    readonly groups: ReadonlyMap<string, {
+        readonly ids: readonly number[];
+        readonly totals: readonly Scalar[];
+    }>;
+    /** Per field, its records' item ids. */
+    readonly records: readonly (readonly number[])[];
+}
+/**
+ * The totals a value or top filter on `field` tests: each of its items' total of data field
+ * `dataField`, within each item of the fields outside it on its axis, over the records the table
+ * keeps (hidden items, page picks, `keep` and `recordKeep` left out) and across the other axis.
+ * The items are those `field`'s axis keeps (`recordKeep`'s bit for it), so an item a filter on
+ * the other axis emptied is there with no total, as Excel judges it. `null` when `field` is on
+ * neither axis or the data field is not one a layout computes.
+ */
+export declare const itemTotalsOf: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, runtime: IRuntime, field: number, dataField: number, keep?: ReadonlyMap<number, Uint8Array>, recordKeep?: Uint8Array, added?: CalculatedRecords | null, calculation?: ICalculation | null) => Promise<PivotItemTotals | null>;
+/**
+ * The formulas of a table's data fields, evaluated over the rollup of what the table keeps: what
+ * {@link LayOutOptions.filters} carries for the layout. `null` when the table cannot be laid out.
+ */
+export declare const fieldValuesOf: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, runtime: IRuntime, calculation: ICalculation, keep: ReadonlyMap<number, Uint8Array> | undefined, recordKeep: Uint8Array | undefined, added: CalculatedRecords | null | undefined) => Promise<ReadonlyMap<number, Scalar[]> | null>;
+export { formatCodeOf };
+//# sourceMappingURL=PivotLayout.d.ts.map

package/types/src/pivot/engine/PivotMove.d.ts

@@ -0,0 +1,24 @@
+import { IPivotTable } from '../IPivotTable';
+/**
+ * What a field's move does to a table's definition, as Excel's (`pivot-probes/probe-pivot-moves.ps1`,
+ * and A10 of `probe-pivot-add.ps1`). Pure: the table lays itself out from what comes back.
+ */
+type Movable = Pick<IPivotTable.JSON, 'fields' | 'rowFields' | 'columnFields' | 'pageFields' | 'filters' | 'formats'>;
+/**
+ * `table` with a field on `axis`, or off the table for `null`: at `position`, counted from 1 and with
+ * the values among the fields, else after the axis's last (A10, M01, M31).
+ *
+ * @remarks
+ * What the field holds goes with it, off the table too (M03, M06, M07, M09): its hidden items, filters,
+ * sort and names. A page field's pick does not leave the page (M04), a filter does not reach it (M05,
+ * M29), and hidden items there are a multiple selection (M03). Off the table it filters nothing, and
+ * the formats naming it in their references are gone for good (M20): other formats, a `button` area
+ * naming it too, stay.
+ *
+ * @returns `table` itself when the field is there already.
+ * @throws ExpectedError for a position not on the axis, the values, or what Excel will not place:
+ * a calculated field anywhere but the values, a field with calculated items on the page (M15).
+ */
+export declare const movePivotField: <T extends Movable>(table: T, cache: IPivotTable.CacheJSON, field: number, axis: IPivotTable.Axis | null, position?: number) => T;
+export {};
+//# sourceMappingURL=PivotMove.d.ts.map

package/types/src/pivot/engine/PivotRefresh.d.ts

@@ -0,0 +1,87 @@
+import { Scalar } from '@sheetxl/primitives';
+import { ICellRange } from '../../cellRange';
+import { IPivotTable } from '../IPivotTable';
+/**
+ * A pivot cache read again from its source, and each table on it carried over to the new cache,
+ * by Excel's rules (PLAN-PIVOT §4.4, `pivot-probes/probe-pivot-refresh-*.ps1`):
+ *
+ * - a field is matched to a source column by its header, without regard to case; a header no field
+ *   had is a new field, and a field no header has is gone from the cache and from every table;
+ * - a field's items are those the column holds, in the order they first appear, then the items
+ *   it held before and holds no longer, kept as unused (unless `missingItemsLimit="0"`);
+ * - a table's items keep their place and their state; an item no longer held is missing and keeps
+ *   its state for when it comes back; an item new to the field is added after the others, or in
+ *   its place under a sort, hidden when the field is filtered;
+ * - a range grouping's bounds follow the values unless fixed and its groups are made anew, and a
+ *   value that is not a number ends the grouping; a discrete grouping keeps its groups, each new
+ *   item a group of its own after them (§4.6);
+ * - a calculated field stays, and a calculated item, last among its field's items (§4.7).
+ */
+/** One column of the source as read: its header, each record's item id, and each id's value. */
+export interface PivotSourceColumn {
+    /** The header cell's text; `''` for a blank header. */
+    header: string;
+    /** Per record, the item id ({@link Items}); 0 is the blank. */
+    ids: Uint32Array;
+    /** Per item id, its value. */
+    values: readonly Scalar[];
+    /** The number format every data cell shares; `undefined` when they do not share one, or it is General. */
+    numberFormat?: string;
+    /** Its numbers are dates: every number in it has a date format. */
+    dates: boolean;
+    /** Which of `values` are dates, when others are plain numbers: then a value with both has two ids. */
+    dateIds?: ReadonlySet<number>;
+}
+/** A source as read: its columns, each as tall as the records. */
+export interface PivotSourceRead {
+    columns: PivotSourceColumn[];
+    recordCount: number;
+}
+/**
+ * Reads a source range, its first row the headers: each column interned into item ids, with the
+ * number format all its data cells share and whether its numbers are dates.
+ *
+ * @param range The source as the sheet holds it now.
+ */
+export declare const readPivotSource: (range: ICellRange) => PivotSourceRead;
+/** How a refresh carried each old cache field and its items into the new cache. */
+export interface PivotCacheRemap {
+    /** Per old cache field, its index in the new cache; -1 when it is gone. */
+    fields: number[];
+    /** Per old cache field, per old item index, its index in the new field's items; -1 when dropped. */
+    items: number[][];
+    /** Per new field, its items: in use first, then unused ({@link IPivotTable.CacheFieldJSON.unused}). */
+    newItems: Scalar.JSON[][];
+    /** Per new field, how many of its items are in use. */
+    usedCounts: number[];
+    /** Per new field, whether a table lists its items in their own order: a range's groups. */
+    inItemOrder: boolean[];
+    /** Per new field holding dates and plain numbers, the items that are dates. */
+    dateItems: (ReadonlySet<number> | undefined)[];
+}
+/**
+ * The cache a refresh from the source makes, and how its old fields and items map onto it.
+ *
+ */
+export declare const refreshPivotCache: (old: IPivotTable.CacheJSON, read: PivotSourceRead, source: IPivotTable.CacheSourceJSON | undefined, date1904?: boolean) => {
+    model: Omit<IPivotTable.CacheJSON, "cacheId" | "part" | "partFormats">;
+    remap: PivotCacheRemap;
+};
+/**
+ * Excel's ascending sort order: numbers, text without regard to case, logicals, dates among plain
+ * numbers (`pivot-probes/probe-pivot-dates-and-numbers.ps1`; errors after them is assumed), errors,
+ * blanks last.
+ *
+ * @param aIsDate Whether `a` is a date in a field that also holds plain numbers.
+ * @param bIsDate The same of `b`.
+ */
+export declare const compareItems: (a: Scalar, b: Scalar, aIsDate?: boolean, bIsDate?: boolean) => number;
+/**
+ * A table carried over to its refreshed cache: its fields in the new cache's order (a field gone
+ * from the source is gone from every axis, its data fields, filters and formats), and each
+ * field's items remapped by {@link PivotCacheRemap}.
+ */
+export declare const remapPivotTable: <T extends Omit<IPivotTable.JSON, "name" | "cacheId" | "location" | "part" | "partFormats" | "buttons">>(table: T, remap: PivotCacheRemap) => T;
+/** An area carried over: `null` when it names a field gone from the source or an item dropped. */
+export declare const remapArea: (area: IPivotTable.PivotAreaJSON, fieldOf: (old: number) => number, kept: (old: number) => boolean, listMaps: readonly (number[] | null)[], dataIndex: readonly number[]) => IPivotTable.PivotAreaJSON | null;
+//# sourceMappingURL=PivotRefresh.d.ts.map

package/types/src/pivot/engine/PivotSort.d.ts

@@ -0,0 +1,26 @@
+import { IPivotTable } from '../IPivotTable';
+import { PivotModel } from '../_PivotItems';
+/**
+ * A table with a field's items listed in a new order: `order` is the new list, each entry an index
+ * into the old one, every entry once.
+ *
+ * @remarks
+ * Whatever names an item by its place in the list follows it: the page pick, another field's sort
+ * scope, a data field's base item, the areas of the table's formats and conditional formats. The
+ * field's own sort is left as it is, for the caller to settle.
+ */
+export declare const reorderPivotItems: <T extends PivotModel>(table: T, field: number, order: readonly number[]) => T;
+/**
+ * A table with a field's items listed in Excel's label order and the field sorted so: numbers,
+ * text without regard to case, logicals, errors, blanks last; descending is the exact reverse, its
+ * blank first (`pivot-probes/probe-pivot-field-filter-api.ps1`, H15, H16). A sort by value the
+ * field had is replaced, as Excel's last sort wins (H17). A range's groups order as the range does,
+ * months by the calendar, and a discrete field's by caption (GE09-GE11). A renamed item sorts by its
+ * caption (`probe-pivot-items.ps1`, I05c).
+ *
+ * @remarks
+ * Entries that are not items (subtotal lines) keep their places. Whatever names an item by its
+ * place in the list follows it ({@link reorderPivotItems}).
+ */
+export declare const sortPivotItemsByLabel: <T extends PivotModel>(table: T, cache: IPivotTable.CacheJSON, field: number, order: "ascending" | "descending") => T;
+//# sourceMappingURL=PivotSort.d.ts.map

package/types/src/pivot/engine/PivotViewBuilder.d.ts

@@ -0,0 +1,22 @@
+import { IRange, IRuntime } from '@sheetxl/primitives';
+import { IPivotTable } from '../IPivotTable';
+import { PivotTable } from '../PivotTable';
+import { PivotFilterResult } from './PivotFilters';
+/**
+ * The values a modeled pivot table shows, from its model and its cache's: what its sheet tells
+ * the grid (`ICalcGrid.setPivots`) for `GETPIVOTDATA`.
+ *
+ * @param saved The location as saved: its top-left is the anchor.
+ * @param blocked The table shows `#SPILL!` at its anchor.
+ * @param filters What the table's filters keep ({@link LayOutOptions.filters}).
+ * @param slicerFields The fields the table's slicers filter ({@link LayOutOptions.slicerFields}).
+ * @returns The data and the location's size, or `null` when the table is not laid out
+ * ({@link layOutPivot}) or its page fields have no room above the anchor.
+ *
+ * @remarks
+ * The values are the layout's: a line is shown as Excel lays it out
+ * (`pivot-probes/probe-getpivotdata.ps1`), hidden items and the page selection keep their records
+ * out of every value, and an empty crossing answers 0.
+ */
+export declare const buildPivotView: (table: IPivotTable.JSON, cache: IPivotTable.CacheJSON, saved: IRange.Coords, runtime: IRuntime, blocked?: boolean, filters?: PivotFilterResult | null, slicerFields?: readonly number[]) => PivotTable.View | null;
+//# sourceMappingURL=PivotViewBuilder.d.ts.map

package/types/src/pivot/engine/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The pivot code a workbook loads only once it holds a modeled pivot table: the views
+ * `GETPIVOTDATA` reads and the layout they come from; in time the refresh and writer.
+ * @internal
+ */
+export { buildPivotView } from './PivotViewBuilder';
+export { anchorPivotPeriods, evaluatePivotFilters, isItemFilter, type PivotFilterResult } from './PivotFilters';
+export { layOutPivot, type PivotCellRole, type PivotLayout } from './PivotLayout';
+export { movePivotItem, renamePivotItem, typeOverPivot } from './PivotEdit';
+export { reorderPivotItems, sortPivotItemsByLabel } from './PivotSort';
+export { readPivotSource, refreshPivotCache, remapPivotTable, type PivotCacheRemap, type PivotSourceRead } from './PivotRefresh';
+export { assertNumberFormat, axisFieldsOf, listedItemsOf, newPivotCache, newPivotTable, withListedFields } from './PivotAdd';
+export { movePivotField } from './PivotMove';
+export { addPivotDataField, movePivotDataField, movePivotValues, removePivotDataField, renamePivotValues, setPivotDataFunction, setPivotDataNumberFormat, setPivotDataShowAs } from './PivotData';
+//# sourceMappingURL=index.d.ts.map

package/types/src/pivot/index.d.ts

@@ -3,4 +3,8 @@
  */
 export * from './IPivotTable';
 export * from './IPivotTableCollection';
+/** @internal */
+export { pivotStylePreviewOf, type PivotStylePreview } from './_PivotStylePreview';
+/** @internal */
+export { pivotBoxOf, pivotCellFormatsOf, pivotControlsIn, type PivotCellFormats, type PivotControl } from './_PivotControls';
 //# sourceMappingURL=index.d.ts.map