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

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

@@ -1,50 +1,584 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { IResource } from '../resource';
+import { ITransaction } from '../transaction';
 import { IWorksheet } from '../sheet';
+import { ICellRange } from '../cellRange';
+import { IPivotTableCollection } from './IPivotTableCollection';
+import { PivotCache } from './PivotCache';
+import { ICellStyle } from '../style';
+import { IProperties } from '../type';
+import { ITableStyle } from '../table';
 import { Anchored } from '../anchored/Anchored';
 import { AbstractAnchored } from '../anchored/AbstractAnchored';
 import { IEmbeddedPart } from '../io';
+import { ICalcGrid } from '../calculation/grid/ICalcGrid';
+import { Tuple } from '../collections';
+import { ISlicer } from '../slicer/ISlicer';
+import { ITimeline } from '../slicer/ITimeline';
 import { IPivotTable } from './IPivotTable';
+import { PivotEngineModule } from './_PivotEngine';
+import { PivotCacheRemap } from './engine/PivotRefresh';
+import { PivotFilterResult } from './engine/PivotFilters';
+import { PivotFormatRegion, PivotStructure, PivotCacheFieldFormats } from './_PivotStructure';
+import { PivotControl, PivotLabelInset } from './_PivotControls';
 interface State extends AbstractAnchored.State {
     anchorCoords: IRange.Coords;
     cacheId: number;
     name: string | null;
+    /** The fields, axes, data fields and layout; `null` for a table that is not modeled. */
+    model: PivotTable.Model | null;
+    /** The part as read, written while the table is unchanged; `null` once it is laid out again. */
+    part: IEmbeddedPart | null;
+    /** What the part's format ids named when read, for a table that is not modeled. */
+    partFormats: IPivotTable.PartFormatsJSON | null;
+    /** The location as the part spells it. While the location still says the same, the part is as read. */
+    ref: string | null;
+    /** As read, relative to the table's top-left cell; for a table never laid out. */
+    buttons: readonly string[] | null;
+    /** How many rows and columns the location covers, as read or as last laid out: the size it wants while blocked. */
+    size: PivotTable.Size;
+    /** It shows `#SPILL!` at its anchor, stored there, and covers that cell alone. */
+    blocked: boolean;
 }
 /**
- * Implementation for {@link IPivotTable}: the part it was read from, anchored on the sheet at its
- * `<location ref>`.
+ * Implementation for {@link IPivotTable}: the part it was read from, anchored on the sheet at what
+ * it holds, as a table is at its range.
  *
  * @remarks
- * The location is where the table SITS, so it is the anchor, as a table's range is, and the
- * sheet's anchored map moves it with structural edits inside their commit. The table rules on
- * those edits as a table does ({@link _processContainerShift}), with Excel's rule: an edit before
- * it moves it whole, one taking every cell of it deletes it, anything that would move part of it
- * is refused. {@link getXML} restates the anchor into the part; the rest of the part is as read.
+ * The anchor is what the table holds ({@link PivotTable.heldOf}): its page fields, the blank row
+ * under them and its location, or its location's top-left cell alone while it shows `#SPILL!`
+ * there. So the sheet's anchored map indexes it, a search finds it, and the map moves it with
+ * structural edits; an edit that takes it deletes the table. Each layout anchors it anew
+ * ({@link _refreshFrom}), as a table's resize does. The location is the anchor's bottom rows, the
+ * size it is laid out at, from its left column: the page fields only ever sit above it.
+ *
+ * The grid places the laid-out cells as a spill of kind `pivot`, or `#SPILL!` at the location when
+ * something is in the way (`ICalcGrid.setPivots`). That spill refuses an edit that would move part
+ * of it, as Excel refuses it (`SpillEntry.checkShift`), so the anchor only ever moves whole.
+ * {@link toJSON} restates the location into the part; the rest of the part is as read.
+ *
+ * The model, the part and the buttons are state, so a refresh is undone with the cells it wrote.
  */
 export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Events> implements IPivotTable {
     protected _sheet: IWorksheet;
-    protected _part: IEmbeddedPart | null;
-    /** The location as the part spells it. While the anchor still says the same, the part is as read. */
-    private _ref;
+    /** Its values and size, once computed ({@link _getPivotView}); `undefined` until asked, and after a change. */
+    private _view;
+    /** Its cells are being moved by a cut or written by its own layout ({@link _setSettling}). */
+    private _settling;
+    /** Its style over its cells, for the model, style and location it was made for ({@link _getRangedStyle}). */
+    private _ranged;
+    /** Where its layout puts it, for the model and location it was found for ({@link _getWanted}). */
+    private _placement;
+    /** Its cell layer, for the placement, style and cache fields it was made for ({@link _getCellLayer}). */
+    private _layer;
+    /** Its date regions, at sheet cells, for the placement and cache fields they were found for ({@link _getDateFormatsIn}). */
+    private _dates;
+    /** What its filters keep, for the filters, fields and cache contents they were evaluated over ({@link _prepareFilters}). */
+    private _filtered;
+    /** The model a relayout was prepared for and the one it lays out, anchored ({@link _prepareRelayout}); taken by {@link _refresh}. */
+    private _anchored;
+    /** The evaluation of its filters under way, if any ({@link _prepareFilters}). */
+    private _filtering;
     constructor(options: PivotTable.ConstructorOptions);
     protected _initialize(options: PivotTable.ConstructorOptions): void;
     /** {@inheritDoc IPivotTable.getName} */
     getName(): string;
+    /** {@inheritDoc IPivotTable.setName} */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
     /** {@inheritDoc IPivotTable.getWorksheet} */
     getWorksheet(): IWorksheet;
-    /** {@inheritDoc IPivotTable.getXML} */
-    getXML(): string | null;
+    /** {@inheritDoc IPivotTable.getRange} */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /** {@inheritDoc IPivotTable.getPageRange} */
+    getPageRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /** {@inheritDoc IPivotTable.getBodyAndTotalRange} */
+    getBodyAndTotalRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /** {@inheritDoc IPivotTable.getRowLabelRange} */
+    getRowLabelRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /** {@inheritDoc IPivotTable.getColumnLabelRange} */
+    getColumnLabelRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * A part of the laid-out table, as Excel's `PageRange`, `DataBodyRange`, `RowRange` and
+     * `ColumnRange` answer (`probe-pivot-add.ps1`, A08; `probe-pivot-table-api.ps1`, R01-R09): `null`
+     * when it has none, or is blocked, where Excel answers the anchor cell.
+     */
+    private _rangeOfPart;
+    /** {@inheritDoc IPivotTable.moveTo} */
+    moveTo(cell: ICellRange.Address, options?: IPivotTable.MoveOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.getSource} */
+    getSource(): string | null;
+    /**
+     * {@inheritDoc IPivotTable.setSource}
+     *
+     * @remarks
+     * The table always moves to a cache of its own, as Excel's `ChangePivotCache` does
+     * (`pivot-probes/probe-pivot-change-source.ps1`, C02, C07); one no table names is not written.
+     */
+    setSource(source: IPivotTableCollection.Source, options?: ITransaction.OperationOptions): Promise<void>;
+    /**
+     * {@inheritDoc IPivotTable.addSlicer}
+     *
+     * @remarks
+     * The cache lists the field's items, as Excel does for a slicer's field
+     * (`pivot-probes/probe-pivot-slicer-caption.ps1`, C07): a slicer's items are the cache's.
+     */
+    addSlicer(field: IPivotTable.IField | string, options?: ISlicer.AddOptions): Promise<ISlicer>;
+    /**
+     * Sets a field's label or date filter to a range of dates, or removes it for `null`: what a
+     * timeline's selection writes to each table it filters, the field on an axis or not.
+     *
+     * @throws ExpectedError When the table is not modeled.
+     * @internal
+     */
+    _setDateRange(field: number, name: string, range: ITimeline.DateRange | null): Promise<void>;
+    /**
+     * Shows the cache items `shown` of a field, or every item for `null`: what a slicer's selection
+     * writes to each table it filters. A field the table lists no items for lists them first.
+     *
+     * @throws ExpectedError When the table is not modeled.
+     * @internal
+     */
+    _showSlicerItems(field: number, shown: ReadonlySet<number> | null): Promise<void>;
+    /**
+     * Where the table is laid out: its location's top-left cell ({@link _locationCell}) and the size
+     * it is laid out at, or that cell alone while it shows `#SPILL!` there. `null` once deleted.
+     */
+    private _getLocation;
+    /**
+     * The top-left cell of the table's location: the first of the anchor's bottom rows, the size it
+     * holds, in its left column; the anchor itself while blocked. `null` once deleted.
+     * @internal
+     */
+    _locationCell(): IRange.Coords | null;
+    /**
+     * Takes the size it covers now as its own, before a cut moves it with its cells, and is anchored
+     * at what it holds at that size; the cut then moves the anchor in the sheet's map. A blocked table
+     * keeps the size it wants: it moves its anchor alone.
+     * @internal
+     */
+    _holdLocation(): void;
+    /** {@inheritDoc IPivotTable.isStale} */
+    isStale(): boolean;
+    /**
+     * Whether the table is modeled: its values can be computed (`ICalcGrid.setPivots`).
+     * @internal
+     */
+    _isModeled(): boolean;
+    /**
+     * The values the table shows and where it sits now, for the grid to hold its extent and for
+     * `GETPIVOTDATA`: computed once by `build`, from the location as saved (its top-left cell and
+     * the size read or last laid out) and whether it is blocked. `null` when the table is not modeled
+     * or `build` cannot lay it out.
+     * @internal
+     */
+    _getPivotView(build: (json: IPivotTable.JSON, saved: IRange.Coords, blocked: boolean) => PivotTable.View | null): ICalcGrid.PivotJSON | null;
+    /** @internal */
+    protected _processAnchorCoords(): void;
+    /**
+     * The table's pivot table style over its cells, page fields included, where it is placed
+     * ({@link _getPlacement}): `null` when it is not placed, names no style, or names one the workbook
+     * does not have. The extent it styles is its `getCoords`.
+     * @internal
+     */
+    _getRangedStyle(): IProperties.ICellRanged<ICellStyle.Properties> | null;
+    /**
+     * Where the table is laid out on the sheet, from its definition and location: its bands, the
+     * top-left cell of its page fields and location, and the cells it covers. `null` when it is not
+     * laid out (no saved layout), deleted, or blocked.
+     * @internal
+     */
+    _getPlacement(): PivotTable.Placement | null;
+    /**
+     * Where the table's layout puts it from its location, whether or not something is in the way:
+     * what {@link _getPlacement} answers when it is not blocked, and the cells it waits on when it is.
+     * @internal
+     */
+    _getWanted(): PivotTable.Placement | null;
+    /**
+     * Marks the table's cells as being moved by a cut, anchored where it lands before they get
+     * there, or written by its own layout: until they settle, the guard on them stands aside, as
+     * those writes are the table's, and a blocked table does not take them for its way clearing.
+     * @internal
+     */
+    _setSettling(settling: boolean): void;
+    /** @internal */
+    _isSettling(): boolean;
+    /**
+     * Whether the table shows `#SPILL!` at its anchor.
+     * @internal
+     */
+    _isBlocked(): boolean;
+    /**
+     * The cells the table holds now: its page fields' and its location as read or last laid out -
+     * which a file can save at another size than its layout says - its location's top-left cell
+     * alone while blocked, none when it is not laid out.
+     * @internal
+     */
+    _getOwnCells(): IRange.Coords[];
+    /**
+     * The table's field dropdowns and the expand/collapse boxes within `coords`, at sheet cells.
+     * @internal
+     */
+    _getControlsIn(coords: IRange.Coords): PivotControl[];
+    /**
+     * How the label in the sheet cell at `row`, `column` is set in, or `null` for a cell that is not
+     * a label of the placed table.
+     * @internal
+     */
+    _getLabelInsetAt(row: number, column: number): PivotLabelInset | null;
+    /** {@inheritDoc IPivotTable.getStyleOptions} */
+    getStyleOptions(): IPivotTable.StyleOptions;
+    /** {@inheritDoc IPivotTable.updateStyleOptions} */
+    updateStyleOptions(options: IPivotTable.StyleOptions, operation?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPivotTable.setHiddenDrillIndicators} */
+    setHiddenDrillIndicators(hidden: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPivotTable.isHiddenDrillIndicators} */
+    isHiddenDrillIndicators(): boolean;
+    /** {@inheritDoc IPivotTable.setHiddenFieldHeaders} */
+    setHiddenFieldHeaders(hidden: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.isHiddenFieldHeaders} */
+    isHiddenFieldHeaders(): boolean;
+    /** What the fields on the row and column axes agree on; `null` where they differ, `none` with none on them. */
+    private _axisFieldsAgree;
+    /** A setting edit that lays the table out again. */
+    private _editSetting;
+    /** Sets a property of every field, on the table or not. */
+    private _editEveryField;
+    /**
+     * Changes one field's definition and lays the table out again, as one step that can be undone.
+     * @internal
+     */
+    _editField(field: number, edit: (json: IPivotTable.PivotFieldJSON) => IPivotTable.PivotFieldJSON, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Sets a property of one field's definition, or leaves it out for `undefined`.
+     * @internal
+     */
+    _editFieldSetting<K extends keyof IPivotTable.PivotFieldJSON>(field: number, key: K, value: IPivotTable.PivotFieldJSON[K] | undefined, options?: ITransaction.OperationOptions): Promise<void>;
+    /** {@inheritDoc IPivotTable.getForm} */
+    getForm(): 'compact' | IPivotTable.PivotForm | null;
+    /** {@inheritDoc IPivotTable.setForm} */
+    setForm(form: 'compact' | IPivotTable.PivotForm, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getRepeatLabels} */
+    getRepeatLabels(): boolean | null;
+    /** {@inheritDoc IPivotTable.setRepeatLabels} */
+    setRepeatLabels(repeat: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getBlankRowAfterItems} */
+    getBlankRowAfterItems(): boolean | null;
+    /** {@inheritDoc IPivotTable.setBlankRowAfterItems} */
+    setBlankRowAfterItems(blank: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getSubtotalsOnTop} */
+    getSubtotalsOnTop(): boolean | null;
+    /** {@inheritDoc IPivotTable.setSubtotalsOnTop} */
+    setSubtotalsOnTop(top: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.isShowRowGrandTotals} */
+    isShowRowGrandTotals(): boolean;
+    /** {@inheritDoc IPivotTable.setShowRowGrandTotals} */
+    setShowRowGrandTotals(show: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.isShowColumnGrandTotals} */
+    isShowColumnGrandTotals(): boolean;
+    /** {@inheritDoc IPivotTable.setShowColumnGrandTotals} */
+    setShowColumnGrandTotals(show: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getEmptyCaption} */
+    getEmptyCaption(): string | null;
+    /** {@inheritDoc IPivotTable.setEmptyCaption} */
+    setEmptyCaption(text: string | null, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getErrorCaption} */
+    getErrorCaption(): string | null;
+    /** {@inheritDoc IPivotTable.setErrorCaption} */
+    setErrorCaption(text: string | null, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.isPreserveFormatting} */
+    isPreserveFormatting(): boolean;
+    /** {@inheritDoc IPivotTable.setPreserveFormatting} */
+    setPreserveFormatting(preserve: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPivotTable.isAutoFitColumns} */
+    isAutoFitColumns(): boolean;
+    /** {@inheritDoc IPivotTable.setAutoFitColumns} */
+    setAutoFitColumns(autoFit: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPivotTable.isMultipleFiltersPerField} */
+    isMultipleFiltersPerField(): boolean;
+    /** {@inheritDoc IPivotTable.setMultipleFiltersPerField} */
+    setMultipleFiltersPerField(multiple: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc IPivotTable.getStyle} */
+    getStyle(): ITableStyle | null;
+    /** {@inheritDoc IPivotTable.getStyleAt} */
+    getStyleAt(row: number, column: number): ICellStyle;
+    /**
+     * The table's style ({@link _getRangedStyle}) with the formats its definition sets, as Excel
+     * writes them into the cells: each cell's number format ({@link pivotNumberFormatAt}), a row
+     * label or row total set left and indented by its level, and the formats a user put on the
+     * table ({@link pivotUserFormatAt}). An empty table draws its box ({@link pivotEmptyBoxAt}) and
+     * nothing of its style, as Excel does. The pivot tier of a cell's style.
+     * @internal
+     */
+    _getCellLayer(): IProperties.ICellRanged<ICellStyle.Properties>;
+    /**
+     * A style written over cells of the table, as Excel takes it: formats of the table over the
+     * areas those cells are ({@link pivotAreasOf}), which follow their items through every relayout,
+     * not the cells' own styles. A format over an area the table already formats is merged into it.
+     *
+     * @param coords Sheet cells; those that are not the table's are left out.
+     * @returns Whether the table took any of them.
+     * @internal
+     */
+    _formatCells(coords: readonly IRange.Coords[], style: ICellStyle.Properties): boolean;
+    /**
+     * The cells within `coords` whose number format from the table's definition shows a date or a
+     * time, at sheet cells, with the code each renders with: what the sheet's date readers add to
+     * the date formats of its direct styles. Empty when the table is not placed.
+     * @internal
+     */
+    _getDateFormatsIn(coords: IRange.Coords): PivotFormatRegion[];
+    /** The cache's contents as the workbook holds them now: one identity per version; `null` when it holds none. */
+    private _getCacheData;
+    /**
+     * What the filters of `model` keep over the cache as it is now, for a layout to read: `null` for a
+     * table with no filters, `undefined` while they are not evaluated ({@link _prepareFilters}).
+     * @internal
+     */
+    _getFilterResult(model?: PivotTable.Model | null): PivotFilterResult | null | undefined;
+    /**
+     * What of the slicers on the table its held filter result depends on: the fields they filter when
+     * a value filter totals or a calculated item counts the records they keep out, else nothing, as
+     * each label and date filter is evaluated whether it applies or not. So adding or deleting a
+     * slicer lays the table out again from what is held ({@link _relayForSlicers}).
+     */
+    private _slicerKey;
+    /**
+     * The fields the slicers on the table filter, by cache index, ascending: their hidden items filter
+     * the table, on an axis or not (`pivot-probes/probe-pivot-slicer-offaxis.ps1`).
+     * @internal
+     */
+    _slicerFields(): number[];
+    /**
+     * Lays the table out again in the caller's operation, a slicer on it added or deleted. Nothing when
+     * its filters are not evaluated for its slicers yet: the next layout takes them.
+     * @internal
+     */
+    _relayForSlicers(): void;
+    /**
+     * Evaluates the filters of `model` over the cache as it is now and holds what they keep, for the
+     * layouts that follow, async or not; nothing when that is held already. Async, as every condition
+     * is: one may carry a formula.
+     * @internal
+     */
+    _prepareFilters(engine: PivotEngineModule, model?: PivotTable.Model | null): Promise<void>;
+    /**
+     * Evaluates the filters a relayout of the table lays it out with, which {@link _refresh} takes:
+     * its model with each relative date filter anchored to today.
+     * @internal
+     */
+    _prepareRelayout(engine: PivotEngineModule): Promise<void>;
+    /** `model` with its relative date filters anchored to the runtime's today, as a relayout evaluates them. */
+    private _anchoredToday;
+    /**
+     * Evaluates the table's filters once at a time, for a caller that cannot wait ({@link _prepareFilters}).
+     * @internal
+     */
+    _prepareFiltersOnce(engine: PivotEngineModule): Promise<void>;
+    /** The fields of the cache the table summarizes, as the workbook holds them; their identity changes with the cache's contents. */
+    private _getCacheFields;
+    /** Per version of a cache's contents, its fields: contents are replaced, never changed in place. */
+    private static _cacheFields;
     /** {@inheritDoc IPivotTable.getCacheId} */
     getCacheId(): number;
+    /** {@inheritDoc IPivotTable.refresh} */
+    refresh(options?: IPivotTable.RefreshOptions): Promise<void>;
+    /**
+     * Carries the table over to its cache as a refresh from the source rebuilt it, in the caller's
+     * commit; laid out again by the caller ({@link _refresh}).
+     * @internal
+     */
+    _remapCache(remap: PivotCacheRemap, engine: PivotEngineModule): void;
+    /**
+     * A refresh in the caller's batch: the table is laid out again ({@link _refreshFrom}), its relative
+     * date filters anchored as {@link _prepareRelayout} prepared them. With `preserveFormatting` off a
+     * table holds no formats of its own making, but a file can say both, and a refresh drops those first.
+     * @internal
+     */
+    _refresh(engine: PivotEngineModule): void;
+    /**
+     * A refresh is refused on a protected sheet, whatever its lock allows: Excel refuses it even
+     * where pivot tables are allowed (`pivot-probes/probe-pivot-protected.ps1`).
+     * @internal
+     */
+    _assertRefreshAllowed(): void;
+    /**
+     * Lays the table out from its cache inside the caller's batch: the model's lines, offsets and
+     * size, and its cells, written as stored values in the same commit. When a cell it needs holds
+     * anything, it gives up its cells and stores `#SPILL!` at its location instead, keeping the size
+     * it wants, and is laid out again once those cells are clear (`Worksheet._unblockPivots`). It is
+     * anchored at what it holds then ({@link PivotTable.heldOf}), as a table's resize anchors it, and
+     * the grid is told where it sits (`ICalcGrid.setPivots`).
+     *
+     * @param own The cells it holds now, for a caller that has changed what they follow from.
+     * @param place Given when the table is being placed: then nothing in its way is taken as a block.
+     * Values are cleared when `discardValues` asks, and refused otherwise; another pivot table or an
+     * array's cells are always refused. A refusal throws, for the caller's batch to roll back.
+     * @param at The top-left cell of the location it moves to ({@link moveTo}); where it is, absent.
+     * @internal
+     */
+    _refreshFrom(engine: PivotEngineModule, own?: readonly IRange.Coords[], place?: PivotTable.Place, at?: IRange.Coords): void;
+    /**
+     * A value typed over one of the table's cells, as Excel takes it: a label or a caption renamed,
+     * an item moved, a page field's item chosen (`typeOverPivot`); the table is laid out again in
+     * the caller's commit. A cell that is neither - a value, a total - is refused.
+     *
+     * @param row The cell, on the sheet.
+     * @throws ExpectedError where Excel refuses the value.
+     * @internal
+     */
+    _typeAt(row: number, column: number, value: Scalar): void;
+    /** {@inheritDoc IPivotTable.getFields} */
+    getFields(): readonly IPivotTable.IField[];
+    /** {@inheritDoc IPivotTable.getField} */
+    getField(name: string): IPivotTable.IField | null;
+    /** {@inheritDoc IPivotTable.getRowFields} */
+    getRowFields(): readonly IPivotTable.IField[];
+    /** {@inheritDoc IPivotTable.getColumnFields} */
+    getColumnFields(): readonly IPivotTable.IField[];
+    /** {@inheritDoc IPivotTable.getPageFields} */
+    getPageFields(): readonly IPivotTable.IField[];
+    /** The fields of an axis's slots, in order; the values' slot (a negative index) is not a field. */
+    private _fieldsOf;
+    /** {@inheritDoc IPivotTable.getDataFields} */
+    getDataFields(): readonly IPivotTable.IDataField[];
+    /** {@inheritDoc IPivotTable.getDataField} */
+    getDataField(name: string): IPivotTable.IDataField | null;
+    /** {@inheritDoc IPivotTable.addDataField} */
+    addDataField(field: string | IPivotTable.IField, input?: Omit<IPivotTable.IDataField.Input, 'field'>, options?: ITransaction.OperationOptions): Promise<IPivotTable.IDataField>;
+    /** {@inheritDoc IPivotTable.getValuesField} */
+    getValuesField(): IPivotTable.IValuesField | null;
+    /**
+     * The table's model: its definition and layout; `null` for a table that is not modeled.
+     * @internal
+     */
+    _getModel(): PivotTable.Model | null;
+    /**
+     * The cache the table summarizes, or `null` when the workbook does not hold it.
+     * @internal
+     */
+    _getCache(): IPivotTable.CacheJSON | null;
+    /**
+     * Changes the model and lays the table out again from its cache, as one step that can be
+     * undone; nothing when `edit` returns the model it was given.
+     *
+     * @throws What `edit` throws, or when the table is not modeled.
+     * @internal
+     */
+    _editModel(edit: (model: PivotTable.Model) => PivotTable.Model, description: string, options?: ITransaction.OperationOptions): Promise<void>;
+    /** Takes `model` and lays the table out from it, inside the caller's batch. */
+    private _relayAs;
+    /**
+     * A field to an axis, or off the table for `null`, as one step that can be undone. The cache lists
+     * a field placed for the first time, shared with whichever tables hold it, in the same step.
+     *
+     * @throws ExpectedError where Excel refuses the move, or when the table is not modeled.
+     * @internal
+     */
+    _moveField(field: number, axis: IPivotTable.Axis | null, position: number | undefined, options?: ITransaction.OperationOptions): Promise<void>;
     /** {@inheritDoc IPivotTable.toJSON} */
     toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
-    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _processUpdateState(prevState: Partial<State>, newState: Partial<State>): void;
+    /** @internal */
+    protected _processAfterStateChange(state: State, commit: ITransaction.ICommit, isRevert?: boolean, isRestore?: boolean): void;
+    /** @internal */
+    protected _isAnyChangeFromState(): boolean;
+    /** @internal */
+    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
     /** @internal */
     protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
     /** {@inheritDoc IPivotTable.isIPivotTable} */
     get isIPivotTable(): true;
 }
 export declare namespace PivotTable {
+    /** What a modeled table's JSON holds besides its name, cache, location, part and buttons. */
+    type Model = Omit<IPivotTable.JSON, 'name' | 'cacheId' | 'location' | 'part' | 'partFormats' | 'buttons'>;
+    /** How many rows and columns a table's location covers. */
+    interface Size {
+        rows: number;
+        columns: number;
+    }
+    /** Where a laid-out table sits on its sheet ({@link PivotTable._getPlacement}). */
+    interface Placement {
+        structure: PivotStructure;
+        /** The top-left cell of its page fields and location. */
+        origin: IRange.CellCoords;
+        /** What it covers, page fields included: the extent its style and its shift guard span. */
+        extent: IRange.Coords;
+        /** Its own cells: the page fields' and the location's, without the blank row between ({@link cellsOf}). */
+        cells: IRange.Coords[];
+    }
+    /** The workbook, as a refresh from the source reaches it. */
+    interface CacheRefresher {
+        doBatch(callback: () => void | Promise<void>, options?: ITransaction.OperationOptions): unknown;
+        _refreshPivotCaches(cacheIds: ReadonlySet<number>, engine: PivotEngineModule): Promise<void>;
+    }
+    /** The workbook, as adding a table reaches it. */
+    interface CacheAdder extends CacheRefresher {
+        _pivotSourceOf(source: IPivotTableCollection.Source, sheet: IWorksheet): IPivotTable.CacheSourceJSON | null;
+        _pivotSourceRangeOf(source: IPivotTable.CacheSourceJSON): Promise<ICellRange | null>;
+        _findPivotCache(source: IPivotTable.CacheSourceJSON): PivotCache | null;
+        _addPivotCache(model: PivotCache.Model): PivotCache;
+        getPivotTables(): IPivotTableCollection;
+    }
+    /** The workbook, as a field move that must list a field reaches it. */
+    interface CacheRestater extends CacheRefresher {
+        _getPivotCache(cacheId: number): PivotCache | null;
+    }
+    /** What is in a table's way, most binding first: another pivot table, an array's cells, a value. */
+    type Obstruction = 'pivot' | 'array' | 'value';
+    /** How a table being placed ({@link IPivotTableCollection.add}, {@link IPivotTable.moveTo}) takes what is in its way. */
+    interface Place {
+        /** Clear the values in its way, rather than refuse them. */
+        discardValues: boolean;
+    }
+    /** What a table asks of its sheet to lay itself out ({@link PivotTable._refreshFrom}). */
+    interface SheetWriter {
+        /** The top-left cell of the location a table placed at `location` takes, or throws where it cannot go. */
+        _pivotAnchorAt(location: ICellRange.Address, pageCount: number, table: IPivotTable | null): IRange.Coords;
+        /** Throws for a name the table cannot take on its sheet. */
+        _assertPivotName(name: string, table: IPivotTable | null): void;
+        /** What, but `table`, is in `wanted` past the cells `own` it holds now; `null` for nothing. */
+        _pivotObstructionOf(table: IPivotTable, wanted: readonly IRange.Coords[], own: readonly IRange.Coords[]): Obstruction | null;
+        /** The order the sheet stores its cells in, which `_writePivotCells` takes them in. */
+        _getPivotCellOrder(): 'rows' | 'columns';
+        /**
+         * Clears the values and direct styles of `clears`, then writes `cells`, in the sheet's order
+         * ({@link _getPivotCellOrder}) from `origin` and sparse, as stored values; the table is settling
+         * ({@link PivotTable._setSettling}) while it does.
+         */
+        _writePivotCells(clears: readonly IRange.Coords[], cells: Tuple.GridTuple<Scalar>, origin: {
+            row: number;
+            column: number;
+        }): void;
+        /** Tells the grid where the sheet's tables sit. */
+        _tellPivots(): void;
+        /** Fits the columns `extent` covers to its cells alone. */
+        _autoFitPivotColumns(extent: IRange.Coords): void;
+    }
+    /**
+     * Whether a table was saved showing `#SPILL!`: laid out larger than the one cell its location
+     * is, as Excel saves it (its top-left cell alone, offsets 0).
+     */
+    const isSavedBlocked: (model: Model | null, size: Size) => boolean;
+    /**
+     * What a table holds, which it is anchored at: its page fields, the blank row under them and its
+     * `location`, as `structure` lays the page fields out above it; the location alone with no
+     * layout or no page fields; its top-left cell alone while it shows `#SPILL!` there.
+     */
+    const heldOf: (structure: PivotStructure | null, location: IRange.Coords, blocked: boolean) => IRange.Coords;
+    /** What the table `json` describes holds as saved ({@link heldOf}), or `null` when it states no location. */
+    const anchorOf: (json: IPivotTable.JSON) => IRange.Coords | null;
+    /** The fields of a table's cache, as its number formats read them. */
+    type CacheFields = PivotCacheFieldFormats;
+    /** A table laid out where it sits: what the grid is told, and the size of its location. */
+    interface View {
+        view: ICalcGrid.PivotJSON;
+        size: Size;
+    }
+    /** The model of a table's JSON, or `null` when it has none. */
+    const modelOf: (json: IPivotTable.JSON) => Model | null;
     interface ConstructorOptions extends Anchored.ConstructorOptions<IPivotTable.JSON> {
         sheet: IWorksheet;
         fromResourceId?: (resourceId: number) => IResource;

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

@@ -1,3 +1,5 @@
+import { ICellRange } from '../cellRange';
+import { ITransaction } from '../transaction';
 import { AbstractCollection } from '../type';
 import { IPivotTable } from './IPivotTable';
 import { IPivotTableCollection } from './IPivotTableCollection';
@@ -6,20 +8,33 @@ import { IPivotTableCollection } from './IPivotTableCollection';
  *
  * @remarks
  * A front over storage held elsewhere — the sheet's own tables, or a walk over every sheet's for
- * the workbook — so the same class serves both. Nothing edits a pivot table yet, so there is
- * nothing to announce.
+ * the workbook — so the same class serves both.
  */
 export declare class PivotTableCollection extends AbstractCollection<IPivotTable> implements IPivotTableCollection {
     private _getItemsDelegate;
+    private _doBatch;
+    private _addDelegate;
     /**
      * @param getItems Returns the tables, as an array the caller may keep.
+     * @param doBatch Runs one step on the owner's undo stack.
+     * @param add Adds a table; absent for the workbook's, which holds no sheet to add to.
      */
-    constructor(getItems: () => IPivotTable[]);
+    constructor(getItems: () => IPivotTable[], doBatch: PivotTableCollection.DoBatch, add?: PivotTableCollection.Add | null);
+    /** {@inheritDoc IPivotTableCollection.add} */
+    add(source: IPivotTableCollection.Source, location: ICellRange.Address, options?: IPivotTableCollection.AddOptions): Promise<IPivotTable>;
     /** {@inheritDoc AbstractCollection._getItems} */
     protected _getItems(): IPivotTable[];
     /** {@inheritDoc IPivotTableCollection.getByName} */
     getByName(name: string): IPivotTable | null;
+    /** {@inheritDoc IPivotTableCollection.refreshAll} */
+    refreshAll(options?: IPivotTable.RefreshOptions): Promise<void>;
     /** {@inheritDoc IPivotTableCollection.isIPivotTableCollection} */
     get isIPivotTableCollection(): true;
 }
+export declare namespace PivotTableCollection {
+    /** The owner's `doBatch`: one step on its undo stack. */
+    type DoBatch = (callback: () => void, options: ITransaction.OperationOptions) => Promise<void> | void;
+    /** The sheet's add. */
+    type Add = (source: IPivotTableCollection.Source, location: ICellRange.Address, options?: IPivotTableCollection.AddOptions) => Promise<IPivotTable>;
+}
 //# sourceMappingURL=PivotTableCollection.d.ts.map