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

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

@@ -3,38 +3,159 @@ import { IWorksheet } from '../sheet';
 import { ICellRange } from '../cellRange';
 import { IAnchored } from '../anchored';
 import { IEmbeddedPart } from '../io';
+import { Tuple } from '../collections';
+import { Scalar } from '@sheetxl/primitives';
+import { ICondition } from '../condition';
+import { ITransaction } from '../transaction';
+import { ICellStyle } from '../style';
+import { ITableStyle } from '../table';
+import { ISlicer } from '../slicer';
+import { IPivotTableCollection } from './IPivotTableCollection';
 /**
- * A pivot table laid out on a sheet: the part it was read from, anchored at its location.
+ * A pivot table laid out on a sheet, anchored at the top-left cell of its location.
  *
  * @remarks
- * The table is not modeled yet beyond where it sits and what it summarizes: its markup is kept
- * as read and written back as read, with the location restated. Where it sits follows
- * structural edits as a table's range does; an edit that would move only part of it is refused,
- * as Excel refuses it, and one that takes every cell of it deletes it.
+ * Until it is refreshed, a table is written back as it was read, with the location restated.
+ * Where it sits follows structural edits; an edit that would move only part of it, its page
+ * fields included, is refused, as Excel refuses it, and one that takes every cell of it deletes it.
+ * While something is in the way of its cells, the table shows `#SPILL!` at its anchor and covers
+ * that cell alone, as in Excel.
  */
 export interface IPivotTable extends IAnchored {
     toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
     /**
-     * Returns the name, unique across the workbook as Excel keeps it.
+     * Returns the name.
+     *
+     * @remarks
+     * Unique on the table's sheet, as Excel keeps it. Tables on different sheets may share a name:
+     * a duplicated sheet's tables keep theirs, as they do in Excel.
      */
     getName(): string;
+    /**
+     * Renames the table, as one step that can be undone.
+     *
+     * @remarks
+     * Any text of 1 to 255 characters, spaces and punctuation included, unless another table on this
+     * sheet has it, without regard to case. A table on another sheet may have it. Slicers on the table
+     * follow it; `GETPIVOTDATA` names a cell, not the table, so it is unaffected.
+     *
+     * @throws ExpectedError For an empty name, one longer than 255 characters, or one another table on
+     * this sheet has.
+     */
+    setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
     /**
      * Returns the sheet the table is laid out on.
      */
     getWorksheet(): IWorksheet;
     /**
-     * Returns the cells the table is laid out on.
+     * Returns the cells the table is laid out on: its location, without the page fields above it.
      *
      * @remarks
-     * The anchor: an insert or delete before the table moves it, one taking every cell of it
-     * deletes it ({@link IAnchored.isDeleted}), and one that would move part of it - a row deleted
-     * or inserted inside it, a column cut through it - is refused.
+     * The anchor cell alone while the table shows `#SPILL!`. An insert or delete before the table
+     * moves it, one taking every cell of it deletes it ({@link IAnchored.isDeleted}), and one that
+     * would move part of it - a row deleted or inserted inside it or its page fields, a column cut
+     * through it - is refused.
      */
     getRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /**
-     * Returns the markup of the table's part, with the location as it is now.
+     * Returns the cells of the page fields above the table, each a caption and its pick; `null` when
+     * the table has no page field, or shows `#SPILL!`.
      */
-    getXML(): string | null;
+    getPageRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * Returns the cells that hold the table's values, its subtotals and grand totals included; `null`
+     * while the table shows `#SPILL!`.
+     *
+     * @remarks
+     * Every line below the header rows, right of the label columns. A table with no values still has
+     * its lines: then the last column, which holds the labels (as Excel's `DataBodyRange`).
+     */
+    getBodyAndTotalRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * Returns the label columns down the side, from the row of their captions to the last line; `null`
+     * when nothing is on the rows, or the table shows `#SPILL!`.
+     */
+    getRowLabelRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * Returns the header rows across the top, right of the label columns, from the row of their
+     * caption; `null` when nothing is on the columns, or the table shows `#SPILL!`.
+     */
+    getColumnLabelRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * Moves the table on its sheet, as one step that can be undone.
+     *
+     * @remarks
+     * `cell` takes the table's top-left cell, as {@link IPivotTableCollection.add}'s location does:
+     * page fields sit above it, a blank row between, and at the top of a sheet the table moves down
+     * to make room for them. The cells it leaves are cleared. The cells it needs must hold no value,
+     * unless {@link IPivotTable.MoveOptions.discardValues} clears them; another pivot table or an
+     * array's cells there always refuse it. The new place may overlap the old.
+     *
+     * @throws ExpectedError When `cell` is on another sheet, the cells it needs hold a value, an array
+     * or another pivot table, or the table is not modeled; ProtectedError on a locked sheet.
+     */
+    moveTo(cell: ICellRange.Address, options?: IPivotTable.MoveOptions): Promise<void>;
+    /**
+     * Returns the cells the table summarizes, as {@link IPivotTableCollection.add} takes them: a table's
+     * or defined name's name, or a sheet-qualified range; `null` when its cache names none, as one
+     * from another workbook or a database may not.
+     */
+    getSource(): string | null;
+    /**
+     * Summarizes other cells, as one step that can be undone: the table reads `source` as a refresh
+     * does and is laid out again.
+     *
+     * @param source The cells to summarize, as {@link IPivotTableCollection.add} takes them.
+     *
+     * @remarks
+     * Fields are matched to the new columns by their header, without regard to case. A field whose
+     * column is gone, or whose header changed, leaves the table; the rest keep their place, hidden
+     * items, filters, captions and formats. Other tables that shared the cache keep the cells they
+     * summarized. When the table grows over a value it shows `#SPILL!`, as after a refresh. A slicer
+     * on a field the new source does not have is deleted with it.
+     *
+     * @throws ExpectedError When `source` names nothing, has no row of data, overlaps the table, the
+     * table is not modeled, or a slicer on the table also filters another; ProtectedError on a locked
+     * sheet.
+     */
+    setSource(source: IPivotTableCollection.Source, options?: ITransaction.OperationOptions): Promise<void>;
+    /**
+     * Adds a slicer that filters one of the table's fields, as one step that can be undone.
+     *
+     * @param field The field, or its name.
+     * @param options Where it goes and how it looks. Sized 192 × 280 pixels and centered in the
+     * view unless `bounds` says otherwise; placed on the table's sheet unless `sheet` says otherwise.
+     *
+     * @returns The slicer, named for the field's name in the source (`Region`, then `Region 1`), unique
+     * in the workbook, and captioned with the field's caption.
+     *
+     * @remarks
+     * The field need not be on the table. The slicer's selection is the items the field hides.
+     *
+     * @throws ExpectedError When the table has no such field, the name is taken, or the table is not
+     * modeled.
+     *
+     * @example
+     * ```ts
+     * const slicer = await pivot.addSlicer('Region');
+     * await slicer.selectItems(['East']);
+     * ```
+     */
+    addSlicer(field: IPivotTable.IField | string, options?: ISlicer.AddOptions): Promise<ISlicer>;
+    /**
+     * Returns whether the cells the table summarizes have been edited since its cache last read them.
+     *
+     * @remarks
+     * As in Excel, an edit to the source does not change the table; it shows what the cache held
+     * until it is refreshed from the source. Every table on the same cache is stale together.
+     *
+     * An edit is a value or formula written or cleared in the source (an undo of one too), a row
+     * or column inserted or deleted inside it, or a resize of the table it names. Moving the source
+     * whole is not. Neither is a recalculation: a formula in the source that reads cells outside it
+     * can change value without the table reading as stale. A source this workbook does not hold,
+     * such as another workbook's, never reads as stale.
+     */
+    isStale(): boolean;
     /**
      * Returns the id of the cache this table summarizes.
      *
@@ -44,16 +165,910 @@ export interface IPivotTable extends IAnchored {
      * @internal
      */
     getCacheId(): number;
+    /**
+     * Reads the table's source again and lays the table out from it, as one step that can be undone.
+     *
+     * @remarks
+     * The cache is read again from the cells its source names now, and every table on that cache is
+     * laid out again with this one, as in Excel. A field follows its column by the header's text
+     * (without regard to case): a column whose header changed, or that is gone, takes its field out
+     * of every table. Each field keeps its items in their place, with what was hidden, collapsed or
+     * renamed; an item no longer in the source is kept, missing, until it comes back, and a new one
+     * is added after the others (in its place under a sort), hidden when the field hides items.
+     * With `source: false` the table alone is laid out again from its cache as it is.
+     *
+     * The table takes the cells its layout needs: its range grows or shrinks from its top-left
+     * cell, and the cells it gives up are cleared. When a cell it needs holds anything, the table
+     * shows `#SPILL!` in its top-left cell, as a dynamic array does, and is laid out again as soon
+     * as the cells are clear.
+     *
+     * @throws When the table is not modeled, on a locked sheet, or its source is not in this
+     * workbook or its cache has calculated fields.
+     */
+    refresh(options?: IPivotTable.RefreshOptions): Promise<void>;
+    /**
+     * Returns the name of the table's style and which of its parts show.
+     *
+     * @remarks
+     * Absent flags are off; a table with no style has no `name`.
+     */
+    getStyleOptions(): IPivotTable.StyleOptions;
+    /**
+     * Changes the table's style or which of its parts show, as one step that can be undone.
+     *
+     * @param options Merged with the current options; `name: null` removes the style and keeps the flags.
+     *
+     * @throws When the table is not modeled.
+     */
+    updateStyleOptions(options: IPivotTable.StyleOptions, operation?: ITransaction.OperationOptions): IPivotTable;
+    /**
+     * Returns the table's pivot table style, or `null` when it names none or one the workbook does not have.
+     */
+    getStyle(): ITableStyle | null;
+    /**
+     * Returns the style the table gives the cell at a sheet position: its pivot table style, and
+     * the formats its layout sets, such as a row label set left and indented by its level.
+     * @param row The row on the sheet.
+     * @param column The column on the sheet.
+     *
+     * @remarks
+     * Not the cell's own formats or any other layer. A cell the table does not cover, or a table
+     * that is not laid out, has none of the table's styling.
+     */
+    getStyleAt(row: number, column: number): ICellStyle;
+    /**
+     * Sets whether the expand/collapse buttons beside the items are hidden, as one step that can be
+     * undone.
+     *
+     * @remarks
+     * The items still expand and collapse through {@link IPivotTable.IItem.setExpanded}.
+     *
+     * @throws When the table is not modeled.
+     */
+    setHiddenDrillIndicators(hidden: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns whether the expand/collapse buttons beside the items are hidden.
+     */
+    isHiddenDrillIndicators(): boolean;
+    /**
+     * Sets whether the captions over the row and column fields, and their buttons, are hidden, as
+     * one step that can be undone.
+     *
+     * @remarks
+     * The table is laid out again from its cache: the caption cells are left blank, and the row of
+     * column captions is dropped when nothing else is in it, so the table can shrink by a row, as in
+     * Excel. A page field keeps its caption and button.
+     *
+     * @throws When the table is not modeled.
+     */
+    setHiddenFieldHeaders(hidden: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether the captions over the row and column fields, and their buttons, are hidden.
+     */
+    isHiddenFieldHeaders(): boolean;
+    /**
+     * Returns how the table lays out its fields, or `null` when the row and column fields differ.
+     */
+    getForm(): 'compact' | IPivotTable.PivotForm | null;
+    /**
+     * Lays out every field of the table in a form, those off the table too, as one step that can be
+     * undone.
+     *
+     * @remarks
+     * The table is laid out again from its cache. As with every setting that changes its cells, when
+     * a cell it needs holds anything the setting stands and the table shows `#SPILL!` until the cells
+     * are clear.
+     *
+     * @throws ExpectedError For a form that is none, or when the table is not modeled.
+     */
+    setForm(form: 'compact' | IPivotTable.PivotForm, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether the row and column fields repeat their labels, or `null` when they differ.
+     */
+    getRepeatLabels(): boolean | null;
+    /**
+     * Sets whether every field repeats its item's label on each line the item spans, those off the
+     * table too, as one step that can be undone.
+     *
+     * @remarks
+     * Nothing shows in compact form, whose labels share a column; the setting stands for a later form.
+     *
+     * @throws When the table is not modeled.
+     */
+    setRepeatLabels(repeat: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether the row and column fields leave a blank line after each item, or `null` when
+     * they differ.
+     */
+    getBlankRowAfterItems(): boolean | null;
+    /**
+     * Sets whether every field leaves a blank line after each of its items, those off the table too,
+     * as one step that can be undone.
+     *
+     * @remarks
+     * A blank line shows only after the items of a row field with another row field inside it.
+     *
+     * @throws When the table is not modeled.
+     */
+    setBlankRowAfterItems(blank: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether the row and column fields show their subtotals on their items' first line, or
+     * `null` when they differ.
+     */
+    getSubtotalsOnTop(): boolean | null;
+    /**
+     * Sets whether every field shows its subtotals on its items' first line rather than on a line
+     * after them, those off the table too, as one step that can be undone.
+     *
+     * @remarks
+     * Tabular form always shows them after; the setting stands for a later form.
+     *
+     * @throws When the table is not modeled.
+     */
+    setSubtotalsOnTop(top: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether each row shows a grand total: the column of totals at the table's right.
+     */
+    isShowRowGrandTotals(): boolean;
+    /**
+     * Sets whether each row shows a grand total, as one step that can be undone.
+     *
+     * @remarks
+     * That is the column of totals at the table's right, so a table with no column fields has none to
+     * show. With the grand total of the whole table gone from the cells, `GETPIVOTDATA` for it is `#REF!`.
+     *
+     * @throws When the table is not modeled.
+     */
+    setShowRowGrandTotals(show: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether each column shows a grand total: the row of totals at the table's bottom.
+     */
+    isShowColumnGrandTotals(): boolean;
+    /**
+     * Sets whether each column shows a grand total, as one step that can be undone.
+     *
+     * @remarks
+     * That is the row of totals at the table's bottom.
+     *
+     * @throws When the table is not modeled.
+     */
+    setShowColumnGrandTotals(show: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns what a crossing no record falls in shows: this text, empty by default for a blank cell,
+     * or `null` when it shows 0.
+     */
+    getEmptyCaption(): string | null;
+    /**
+     * Sets what a crossing no record falls in shows, as one step that can be undone.
+     *
+     * @param text The text; empty for a blank cell; `null` for 0. Text that reads as a number shows as
+     * that number.
+     *
+     * @throws When the table is not modeled.
+     */
+    setEmptyCaption(text: string | null, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns what an error value shows as: this text, or `null`, the default, when it shows the error.
+     */
+    getErrorCaption(): string | null;
+    /**
+     * Sets what an error value shows as, as one step that can be undone.
+     *
+     * @param text The text; empty for a blank cell; `null` for the error itself.
+     *
+     * @throws When the table is not modeled.
+     */
+    setErrorCaption(text: string | null, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns whether the formats set on the table's cells follow their items through a relayout.
+     */
+    isPreserveFormatting(): boolean;
+    /**
+     * Sets whether the formats set on the table's cells follow their items through a relayout, as one
+     * step that can be undone.
+     *
+     * @remarks
+     * Turned off, the table lets go of the formats it holds, for good: turning it on again does not bring
+     * them back. While off, a format set on the cells lasts until the next time the table is laid out,
+     * whatever causes that.
+     *
+     * @throws When the table is not modeled.
+     */
+    setPreserveFormatting(preserve: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns whether the table fits its columns to its cells each time it is laid out.
+     */
+    isAutoFitColumns(): boolean;
+    /**
+     * Sets whether the table fits its columns to its cells each time it is laid out, as one step that
+     * can be undone.
+     *
+     * @remarks
+     * A fit measures only the table's cells, and sets the width of every column the table covers, a
+     * width set by hand included. Setting this does not fit the columns; the next layout does.
+     *
+     * @throws When the table is not modeled.
+     */
+    setAutoFitColumns(autoFit: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns whether a field's filters are allowed to combine.
+     */
+    isMultipleFiltersPerField(): boolean;
+    /**
+     * Sets whether a field's filters are allowed to combine, as one step that can be undone.
+     *
+     * @remarks
+     * Turned off, a field holding more than one filter loses all of them, and the table is laid out
+     * again if any went; a field with one keeps it. The flag does not limit
+     * {@link IPivotTable.IField.applyFilter}.
+     *
+     * @throws When the table is not modeled.
+     */
+    setMultipleFiltersPerField(multiple: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Returns the table's fields, one per field of its cache, in the cache's order; empty for a table
+     * that is not modeled.
+     *
+     * @example
+     * ```ts
+     * await pivot.getField('Region').getItem('East').setExpanded(false);
+     * await pivot.getField('Channel').setCurrentPage('Web');
+     * ```
+     */
+    getFields(): readonly IPivotTable.IField[];
+    /**
+     * Returns the field with a caption, matched without regard to case, or `null` when there is none.
+     */
+    getField(name: string): IPivotTable.IField | null;
+    /**
+     * Returns the fields down the rows, outermost first; the values, where they sit among them, are
+     * {@link getValuesField}.
+     */
+    getRowFields(): readonly IPivotTable.IField[];
+    /**
+     * Returns the fields across the columns, outermost first; the values, where they sit among them,
+     * are {@link getValuesField}.
+     */
+    getColumnFields(): readonly IPivotTable.IField[];
+    /**
+     * Returns the page fields above the table, in the order they are listed.
+     */
+    getPageFields(): readonly IPivotTable.IField[];
+    /**
+     * Returns the table's values, in the order they show; empty for a table that is not modeled.
+     */
+    getDataFields(): readonly IPivotTable.IDataField[];
+    /**
+     * Returns the value with a caption, matched without regard to case, or `null` when there is none.
+     */
+    getDataField(name: string): IPivotTable.IDataField | null;
+    /**
+     * Summarizes a field in the table's values, after the last, as one step that can be undone.
+     *
+     * @remarks
+     * The field comes off any row, column or page axis it is on, as in Excel, keeping what
+     * {@link IPivotTable.IField.setAxis} keeps. {@link IPivotTable.IField.setAxis} can then put it back,
+     * holding both. One source can be summarized any number of times.
+     *
+     * With a second value the table gains its {@link getValuesField | values field}.
+     *
+     * @param field The field, or its caption.
+     * @param input Its caption, function and number format; absent, as {@link IPivotTable.IDataField.Input} says.
+     *
+     * @example
+     * ```ts
+     * await pivot.addDataField('Sales');
+     * const average = await pivot.addDataField('Sales', { function: 'average', numberFormat: '0.00' });
+     * ```
+     *
+     * @throws ExpectedError For a field the table does not have, a caption another field or value has, a
+     * function that is none or a number format that does not parse.
+     */
+    addDataField(field: string | IPivotTable.IField, input?: Omit<IPivotTable.IDataField.Input, 'field'>, options?: ITransaction.OperationOptions): Promise<IPivotTable.IDataField>;
+    /**
+     * Returns where the table's values sit among the fields of an axis; `null` below two values, when
+     * there is nothing for them to be placed among.
+     */
+    getValuesField(): IPivotTable.IValuesField | null;
     /** For runtime type checking. */
     readonly isIPivotTable: true;
 }
 export declare namespace IPivotTable {
     /**
-     * A pivot cache as the workbook carries it: the part, by the id the tables name.
+     * The axis a {@link IField | field} is on: down the rows, across the columns, as a page field
+     * above the table, or where the values sit.
+     */
+    const Axis: {
+        readonly Row: "row";
+        readonly Column: "column";
+        readonly Page: "page";
+        readonly Values: "values";
+    };
+    type Axis = typeof Axis[keyof typeof Axis];
+    /**
+     * A field of a pivot table: a field of its cache, as the table uses it.
+     *
+     * @remarks
+     * Changing what a field shows - collapsing items, hiding them, choosing a page item - changes the
+     * table's definition and lays the table out again from its cache, as one step that can be undone.
+     * The source is not read again. A table that grows over cells that hold anything shows `#SPILL!`,
+     * as a {@link IPivotTable.refresh | refresh} does.
+     *
+     * A field is a view of the table: it reads the table as it is now.
+     */
+    interface IField {
+        /**
+         * Returns the field's caption: its own name in the table, else its cache field's.
+         */
+        getName(): string;
+        /**
+         * Returns what the field's items are: numbers, dates, text (logicals and errors among it), a
+         * mix of those, or `blank` when it holds nothing. A calculated field is numbers.
+         *
+         * @remarks
+         * The rule {@link IPivotTable.addDataField} follows for a value's function: `number` sums, any
+         * other counts. A field list places a field by it, numbers in the values and the rest on the rows.
+         */
+        getDataType(): IField.DataType;
+        /**
+         * Returns the axis the field is on, or `null` when it is on none.
+         */
+        getAxis(): Axis | null;
+        /**
+         * Puts the field on an axis, or takes it off the table for `null`, as one step that can be undone.
+         *
+         * @remarks
+         * The table is laid out again from its cache. Where a value is in the way it shows `#SPILL!`, and
+         * a page field with no room above moves the table down, where it stays once the field has gone.
+         *
+         * What the field holds goes with it, off the table and back too: hidden items, filters, sort and
+         * names. On the page axis it loses its filters, and items hidden there are a multiple selection;
+         * off the page it loses its pick. A field off the table filters nothing. Taking it off also drops
+         * the formats on its labels and on the values under them, for good; a move between axes keeps them.
+         * A sort by one line of the other axis ends when that line's fields are no longer that axis's
+         * outermost.
+         *
+         * A field stays with its data fields either way: one source can be on an axis and summarized at
+         * once. To remove a value, delete its {@link IDataField}.
+         *
+         * @param axis Where it goes; `null` is nothing for a field already off the table.
+         * @param position Its place on the axis, counted from 1, the values counting where they sit among
+         * the fields; absent, after the last. Absent is nothing for a field already on `axis`.
+         *
+         * @example
+         * ```ts
+         * await pivot.getField('Year').setAxis('column');
+         * await pivot.getField('Product').setAxis('row', 1);
+         * await pivot.getField('Region').setAxis(null);
+         * ```
+         *
+         * @throws ExpectedError For `values`, for a position not on the axis, and for a calculated field
+         * on any axis or a field with calculated items on the page axis.
+         */
+        setAxis(axis: Axis | null, position?: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the field's place on its axis, counted from 1, the values counting where they sit among
+         * the fields; `null` off the table.
+         */
+        getPosition(): number | null;
+        /**
+         * Moves the field along its axis, as one step that can be undone.
+         *
+         * @param position Its place, counted from 1 as {@link getPosition} counts.
+         * @throws ExpectedError When the field is off the table or the position is not on its axis.
+         */
+        setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the subtotals the field shows, in the order they show: `automatic`, or its functions;
+         * empty for none.
+         */
+        getSubtotals(): readonly IField.Subtotal[];
+        /**
+         * Sets the subtotals the field shows, as one step that can be undone.
+         *
+         * @remarks
+         * The automatic subtotal takes the place of any function asked for with it, and functions show in
+         * one order whatever the order asked. One function alone sits where the automatic subtotal does; two
+         * or more always show on lines after the items. With none, an item's own line holds no value in
+         * compact and outline forms. The setting holds for a field off the table, and shows when it is an
+         * outer field of its axis.
+         *
+         * @param subtotals Empty for none.
+         *
+         * @example
+         * ```ts
+         * await pivot.getField('Region').setSubtotals([]);
+         * await pivot.getField('Region').setSubtotals(['average', 'max']);
+         * ```
+         *
+         * @throws ExpectedError For a subtotal that is none, on a calculated field, and for functions on a
+         * field with calculated items.
+         */
+        setSubtotals(subtotals: readonly IField.Subtotal[], options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns how the field's items are laid out.
+         */
+        getForm(): 'compact' | PivotForm;
+        /**
+         * Lays out the field's items in a form, as one step that can be undone.
+         *
+         * @remarks
+         * Fields of different forms share an axis: a compact field shares its label column with the field
+         * inside it. {@link IPivotTable.setForm} sets every field at once.
+         *
+         * @throws ExpectedError For a form that is none.
+         */
+        setForm(form: 'compact' | PivotForm, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns whether the field repeats its item's label on each line the item spans.
+         */
+        getRepeatLabels(): boolean;
+        /**
+         * Sets whether the field repeats its item's label on each line the item spans, as one step that
+         * can be undone.
+         *
+         * @remarks
+         * It shows only where the field has a label column or row of its own, and has a field inside it.
+         */
+        setRepeatLabels(repeat: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns whether the field leaves a blank line after each of its items.
+         */
+        getBlankRowAfter(): boolean;
+        /**
+         * Sets whether the field leaves a blank line after each of its items, as one step that can be undone.
+         *
+         * @remarks
+         * It shows only on a row field with another row field inside it; a field inside it that also leaves
+         * one shares that line.
+         */
+        setBlankRowAfter(blank: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns whether the field's subtotals show on its items' first line rather than after them.
+         */
+        getSubtotalsOnTop(): boolean;
+        /**
+         * Sets whether the field's subtotals show on its items' first line rather than after them, as one
+         * step that can be undone.
+         *
+         * @remarks
+         * Tabular form always shows them after, as do two or more functions.
+         */
+        setSubtotalsOnTop(top: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the format code of the field's item labels: its own, else its source column's, else
+         * `General`; empty for a field holding anything but numbers and dates, which takes none.
+         */
+        getNumberFormat(): string;
+        /**
+         * Sets the number format of the field's item labels, as one step that can be undone.
+         *
+         * @remarks
+         * `GETPIVOTDATA` still finds items by their values, and by the text they show. It does not reach a value that
+         * summarizes the field: see {@link IDataField.setNumberFormat}.
+         *
+         * @param format A format code, or a built-in format's id.
+         * @throws ExpectedError For a format that does not parse, and on a field holding anything but
+         * numbers and dates.
+         */
+        setNumberFormat(format: string | number, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the table the field belongs to.
+         */
+        getPivotTable(): IPivotTable;
+        /**
+         * Returns the field's items in the table's order; empty for a field the table lists none for.
+         */
+        getItems(): readonly IItem[];
+        /**
+         * Returns the item with a caption, matched without regard to case, or `null` when there is none.
+         *
+         * @remarks
+         * A renamed item is found by its new caption only, as in Excel.
+         */
+        getItem(name: string): IItem | null;
+        /**
+         * Shows or hides the details of every item of the field, as one step that can be undone.
+         *
+         * @throws When the field is not a row or column field with another field inside it.
+         */
+        setExpanded(expanded: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Shows only the named items, or every item for `null`, as one step that can be undone.
+         *
+         * @remarks
+         * On a page field the items shown are its selection: the field selects more than one item, and
+         * its page cell shows the item when one is left, else `(Multiple Items)`.
+         *
+         * @throws When a name is not an item of the field, or no item would show.
+         */
+        setVisibleItems(names: readonly string[] | null, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the item a page field shows, or `null` when it shows every item or more than one.
+         */
+        getCurrentPage(): IItem | null;
+        /**
+         * Shows one item of a page field, or every item for `null`, as one step that can be undone.
+         *
+         * @remarks
+         * The field selects a single item: any items hidden by {@link setVisibleItems} are shown again.
+         *
+         * @throws When the field is not a page field or the name is not one of its items.
+         */
+        setCurrentPage(name: string | null, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the field's filters: its label or date filter, its value or top filter, and the items
+         * it shows when some are hidden by hand. Empty when the field is not filtered.
+         */
+        getFilters(): IField.Filters;
+        /**
+         * Returns whether the field is filtered: by a filter of `type`, or by any when omitted.
+         */
+        isFiltered(type?: IField.FilterType): boolean;
+        /**
+         * Sets the field's filters of the kinds given and leaves its others, as one step that can be
+         * undone.
+         *
+         * @remarks
+         * A field takes one label-or-date filter and one value-or-top filter, as Excel's does; one given
+         * replaces the field's filter of its kind. Items hidden by hand stand beside them.
+         *
+         * - `label` tests each item's caption as its cell shows it; given no selector, it takes the
+         *   Display selector.
+         * - `date` tests each item's date.
+         * - `value` tests each item's total of a data field within each item of the fields outside it;
+         *   a top N ranks the items under one outer item together.
+         * - `manual` names the items shown, every item for `null`; on a page field, its selection.
+         *
+         * A condition no Excel pivot filter type spells is kept and laid out, and is left out of an
+         * xlsx file with a warning.
+         *
+         * @example
+         * ```ts
+         * const region = table.getField('Region')!;
+         * await region.applyFilter({ label: { selector: 'display', operator: 'textStartsWith', param: 'N' } });
+         * await region.applyFilter({ value: { condition: { operator: 'greaterThan', param: 100 }, dataField: 'Sum of Sales' } });
+         * ```
+         *
+         * @throws ExpectedError When a label, date or value filter is given for a field that is not a
+         * row or column field, both a label and a date filter are given, a top N names no data field,
+         * a data field or item is not the table's, or no item would show.
+         */
+        applyFilter(filters: IField.FilterInput, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Clears the field's filter of `type`, as one step that can be undone; `manual` shows every
+         * item.
+         */
+        clearFilter(type: IField.FilterType, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Clears every filter of the field and shows every item, as one step that can be undone; a page
+         * field shows all its items again.
+         */
+        clearAllFilters(options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns how the field's items are sorted, or `null` when they are in the order listed.
+         */
+        getSort(): IField.Sort | null;
+        /**
+         * Sorts the field's items by their labels, as one step that can be undone: numbers, then text
+         * without regard to case, logicals, errors, and blanks last; descending is the exact reverse.
+         * A sort by value is replaced.
+         *
+         * @throws ExpectedError When the field is not a row or column field.
+         */
+        sortByLabels(order: 'ascending' | 'descending', options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Sorts the field's items under each outer item by a data field's value, as one step that can
+         * be undone: their totals, or their values in one line of the other axis.
+         *
+         * @remarks
+         * An empty value sorts as 0. Hiding an item of the scope ends the sort, as in Excel.
+         *
+         * @param dataField The data field, by name.
+         * @param scope The line of the other axis to read: its items' names, outermost field first.
+         * Fewer names than the axis has fields name a subtotal line (`['2023']` over Year and Quarter
+         * is the 2023 total). Absent or empty, the grand total.
+         * @throws ExpectedError When the field is not a row or column field, the data field is not the
+         * table's, or the scope names no line of the other axis.
+         */
+        sortByValues(order: 'ascending' | 'descending', dataField: string, scope?: readonly string[] | null, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns whether the field shows every item, those with no data included.
+         */
+        getShowAllItems(): boolean;
+        /**
+         * Shows every item of the field, those with no data included, or only those with data, as one
+         * step that can be undone.
+         */
+        setShowAllItems(showAllItems: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Renames the field in the table, as one step that can be undone; its source field's name
+         * restores the original.
+         *
+         * @throws ExpectedError When another field or data field of the table has the name.
+         */
+        setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+        /** For runtime type checking. */
+        readonly isIPivotField: true;
+    }
+    namespace IField {
+        /** What a field's items are ({@link IField.getDataType}). */
+        type DataType = 'number' | 'date' | 'text' | 'mixed' | 'blank';
+        /** A subtotal a field can show: the automatic one, or a function. */
+        type Subtotal = 'automatic' | IDataField.Function;
+        /** A kind of filter a field takes. `manual` is the items hidden by hand. */
+        type FilterType = 'label' | 'date' | 'value' | 'manual';
+        /** A field's filters, by kind; a kind the field does not have is absent. */
+        interface Filters {
+            label?: ICondition.JSON;
+            date?: ICondition.JSON;
+            value?: {
+                condition: ICondition.JSON;
+                dataField: string;
+            };
+            /** The items shown, when some are hidden by hand. */
+            manual?: readonly string[];
+        }
+        /** Filters to set on a field ({@link IField.applyFilter}); a kind absent is left as it is. */
+        interface FilterInput {
+            label?: ICondition.Input;
+            date?: ICondition.Input;
+            /** The data field by name. */
+            value?: {
+                condition: ICondition.Input;
+                dataField: string;
+            };
+            /** The items shown, by name; `null` every item. */
+            manual?: readonly string[] | null;
+        }
+        /** How a field's items are sorted ({@link IField.getSort}). */
+        interface Sort {
+            order: 'ascending' | 'descending';
+            /** Sorted by this data field's values; absent, by label. */
+            dataField?: string;
+            /** The line of the other axis the values are read in, outermost item first; absent, the grand total. */
+            scope?: readonly string[];
+        }
+    }
+    /**
+     * An item of a {@link IField | pivot field}: a value of its cache field, as the table lists it.
+     */
+    interface IItem {
+        /**
+         * Returns the item's caption: its own name in the table, else its value as text; `(blank)` for
+         * the blank item.
+         */
+        getName(): string;
+        /**
+         * Returns the field the item belongs to.
+         */
+        getField(): IField;
+        /**
+         * Returns whether the item shows: `false` when it is hidden from the field.
+         */
+        isVisible(): boolean;
+        /**
+         * Shows or hides the item, as one step that can be undone.
+         *
+         * @throws When it is the last item showing.
+         */
+        setVisible(visible: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns whether the item's details show: `false` when it is collapsed.
+         */
+        isExpanded(): boolean;
+        /**
+         * Shows or hides the item's details, as one step that can be undone.
+         *
+         * @remarks
+         * An item of the innermost field takes the setting, which shows nothing different, as in Excel.
+         *
+         * @throws When the field is not a row or column field.
+         */
+        setExpanded(expanded: boolean, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the item's place among the items of its field that show, counted from 1; `null` for
+         * a hidden item, or when the field is off the table.
+         */
+        getPosition(): number | null;
+        /**
+         * Moves the item among the items of its field that show, as one step that can be undone.
+         *
+         * @remarks
+         * The field's order is then by hand: a sort it had, by label or by value, ends, as in Excel, and
+         * the order holds through a refresh. The page pick, a sort by the item's line, a base item and
+         * the formats on the item follow it.
+         *
+         * @param position Its place, counted from 1 as {@link getPosition} counts.
+         * @throws ExpectedError For a hidden item or a field off the table, and for a position not
+         * among the items that show.
+         */
+        setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Renames the item in the table, as one step that can be undone; its value's own text restores
+         * the original.
+         *
+         * @remarks
+         * The name is kept as given, spaces and all, and may be empty. Under a sort by label the field
+         * is sorted again, by the captions, as in Excel. `GETPIVOTDATA` finds the item by the caption or
+         * by its value, and {@link IField.getItem} by the caption alone.
+         *
+         * @throws ExpectedError When another item of the field has the name, without regard to case.
+         */
+        setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+        /** For runtime type checking. */
+        readonly isIPivotItem: true;
+    }
+    /**
+     * Options for {@link IPivotTable.refresh}.
+     */
+    interface RefreshOptions extends ITransaction.OperationOptions {
+        /**
+         * Whether the cache is read again from the source first; `false` lays the table out from the
+         * cache as it is.
+         *
+         * @defaultValue `true`
+         */
+        source?: boolean;
+    }
+    /** Options for {@link IPivotTable.moveTo}. */
+    interface MoveOptions extends ITransaction.OperationOptions {
+        /**
+         * Whether values in the cells the table moves to are cleared; `false` refuses the move instead.
+         *
+         * @defaultValue `false`
+         */
+        discardValues?: boolean;
+    }
+    /**
+     * Options for {@link IPivotTable.updateStyleOptions}: the style's name, and which parts of it show.
+     */
+    interface StyleOptions extends Omit<PivotStyleJSON, 'name'> {
+        /** A pivot table style's name; `null` removes the style. */
+        name?: string | null;
+    }
+    /**
+     * A pivot cache as the workbook carries it, by the id the tables name.
+     *
+     * @remarks
+     * A cache over a worksheet source is modeled: its fields, their items and the records, which
+     * are what a refresh rebuilds and what a pivot is computed from. `part`, the definition and
+     * records as they were read, is present only while the cache is unchanged, and is then what is
+     * written. A cache with no `fields` is carried as its `part` alone.
      */
     interface CacheJSON {
         cacheId: number;
+        /** The parts as read, written as they are while the cache is unchanged. */
         part?: IEmbeddedPart.JSON;
+        /**
+         * The cells the records were read from: a sheet and a range, or a table's name. Present for a
+         * cache carried as its part too, when it names cells in this workbook.
+         */
+        source?: CacheSourceJSON;
+        fields?: CacheFieldJSON[];
+        /**
+         * Each field's items: the field's index, then its items in order. A string is literal; a
+         * missing item is `{ t: 'z', v: 0 }`; a date is its serial number (see
+         * {@link CacheFieldJSON.dates} and {@link CacheFieldJSON.dateItems}).
+         */
+        items?: Tuple.GridTuple<Scalar.JSON>;
+        /**
+         * Each field's records: the field's index, then, per record in order, the index of its item
+         * in {@link items}. A field with {@link CacheFieldJSON.noRecords} has none. Absent when the file
+         * saved no records: its tables are not laid out until a refresh from the source.
+         */
+        records?: Tuple.GridTuple<number>;
+        recordCount?: number;
+        refreshOnLoad?: boolean;
+        /**
+         * For a cache with no `fields`: what the format ids its `part` cites named in the file it was
+         * read from.
+         * @internal
+         */
+        partFormats?: PartFormatsJSON;
+        /**
+         * The definition's markup with what is modeled taken out (the fields, the source's cells, the
+         * record count and refresh flag): what the cache holds that is not typed yet.
+         */
+        rest?: string;
+    }
+    /**
+     * What the format ids in a part carried without a model name, by id, in the file it was read
+     * from. A save numbers its formats afresh and restates each id the part cites from these.
+     * @internal
+     */
+    interface PartFormatsJSON {
+        /** By `numFmtId`: a custom number format's code. Built-in ids are kept as they are. */
+        numberFormats?: Record<number, string>;
+        /** By `dxfId`: the differential format. */
+        dxfs?: Record<number, ICellStyle.Properties>;
+    }
+    /**
+     * The cells a {@link CacheJSON | cache} was read from.
+     */
+    interface CacheSourceJSON {
+        /** The range, A1 without `$`. With `sheet`. */
+        ref?: string;
+        sheet?: string;
+        /** A table's or a defined name's name, in place of `ref` and `sheet`. */
+        name?: string;
+    }
+    /**
+     * One field of a {@link CacheJSON | cache}: a column of its source, or a grouping of one.
+     */
+    interface CacheFieldJSON {
+        name: string;
+        /** The number format of its values: a format code, or a built-in format's id; absent, General. */
+        numberFormat?: string | number;
+        /** The records hold the values themselves, not the index of a shared item. */
+        inline?: true;
+        /** The items that are numbers are dates. */
+        dates?: true;
+        /**
+         * The items that are dates, by index, when others are plain numbers. A date and a number of the
+         * same value are two items.
+         */
+        dateItems?: number[];
+        /** The items the source no longer holds, kept from an earlier refresh. */
+        unused?: number[];
+        /** Not a column of the source (a grouping or calculated field): the records hold nothing for it. */
+        noRecords?: true;
+        /** How the field groups values, or the field its values are grouped by. */
+        group?: CacheFieldGroupJSON;
+        /** A calculated field's formula, as a file spells it (`Sales-Cost`), with {@link noRecords}. */
+        formula?: string;
+        /**
+         * The field's calculated items: each one's index in its items, and its formula, as a file spells
+         * it (`Region[North]+Region[South]`).
+         */
+        calculatedItems?: {
+            item: number;
+            formula: string;
+        }[];
+        /**
+         * The field's markup with what is modeled taken out (name, number format, items): its
+         * grouping, formula and anything else not typed yet.
+         */
+        rest?: string;
+    }
+    /**
+     * How a {@link CacheFieldJSON | cache field} groups the values of another, or its own.
+     *
+     * @remarks
+     * A table lists a grouping field's {@link items}, not its cache items. With neither
+     * {@link range} nor {@link discrete} the field groups nothing itself and only names its
+     * {@link parent}: a date field grouped by months.
+     */
+    interface CacheFieldGroupJSON {
+        /** The cache field whose values are grouped: this field, for a number range in place. */
+        base: number;
+        /** The next coarser field grouping the same values (Date to Months to Years). */
+        parent?: number;
+        /**
+         * Each group's caption. A range's first and last hold what falls before and after it. An item of
+         * the base that no group holds is its own group here, as itself: a number, a date's serial
+         * number ({@link dateItems}), a boolean, or the items' spelling of a blank or an error
+         * ({@link CacheJSON.items}).
+         */
+        items: Scalar.JSON[];
+        /** The {@link items} that are dates, by index. */
+        dateItems?: number[];
+        /** Groups by range of the base's values. */
+        range?: {
+            by: 'numbers' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years';
+            /** The first value; a date is its serial number. */
+            start: number;
+            /** The last value; a date range's whole-day end is the day after the last. */
+            end: number;
+            /** The width of each step, in values or days; absent, 1. */
+            interval?: number;
+            /** The start stays when the source changes, rather than following its least value. */
+            fixedStart?: true;
+            /** The end stays when the source changes, rather than following its greatest value. */
+            fixedEnd?: true;
+        };
+        /** Groups by hand: for each cache item of the base, its index in {@link items}. */
+        discrete?: number[];
     }
     /**
      * JSON representation of a pivot table.
@@ -61,7 +1076,528 @@ export declare namespace IPivotTable {
     interface JSON {
         name?: string;
         cacheId: number;
+        /**
+         * The cells the table's body is laid out on, as an A1 range (`A3:C20`): where it is anchored.
+         * Its page fields sit above it.
+         */
+        location: string;
         part?: IEmbeddedPart.JSON;
+        /**
+         * For a table with no `fields`: what the format ids its `part` cites named in the file it was
+         * read from.
+         * @internal
+         */
+        partFormats?: PartFormatsJSON;
+        /**
+         * The cells that show a field button, as addresses relative to the table's top-left cell
+         * (`A1` is that cell).
+         *
+         * @remarks
+         * A button belongs to the table, not to the cell's format: Excel drops it from a copied cell.
+         *
+         * @internal
+         */
+        buttons?: string[];
+        /**
+         * One per field of the cache, in the cache's order.
+         *
+         * @remarks
+         * A table is modeled when its markup holds nothing the model does not type yet on the
+         * elements it reads (OLAP hierarchies, item properties, extensions on a field or data field
+         * other than Excel's own repeat labels and show-values-as); it is then written from the model
+         * once it has no `part`.
+         */
+        fields?: PivotFieldJSON[];
+        /** The fields on the row axis, outermost first, by index; `-2` is where the values sit. */
+        rowFields?: number[];
+        /** The fields on the column axis, outermost first, by index; `-2` is where the values sit. */
+        columnFields?: number[];
+        pageFields?: PageFieldJSON[];
+        dataFields?: DataFieldJSON[];
+        /** Shown unless `false`. */
+        rowGrandTotals?: false;
+        /** Shown unless `false`. */
+        columnGrandTotals?: false;
+        /**
+         * The layout of fields added to the table and of the values; absent, compact. Each field
+         * keeps its own ({@link PivotFieldJSON.form}).
+         */
+        form?: PivotForm;
+        /** How far each level of a compact row field is indented, in characters past the first; absent, 0. */
+        indent?: number;
+        /** The caption of the values field; absent, `Values`. */
+        valuesCaption?: string;
+        /** The caption of the grand totals; absent, `Grand Total`. */
+        grandTotalCaption?: string;
+        /** The caption over the row labels in compact form; absent, `Row Labels`. */
+        rowHeaderCaption?: string;
+        /** The caption over the column labels in compact form; absent, `Column Labels`. */
+        columnHeaderCaption?: string;
+        /** Shown in place of an error value when {@link showError} is `true`. */
+        errorCaption?: string;
+        /** An error value shows as {@link errorCaption}. */
+        showError?: true;
+        /** Shown in a crossing no record falls in, unless {@link showEmpty} is `false`. */
+        emptyCaption?: string;
+        /** `false`: a crossing no record falls in shows 0 rather than {@link emptyCaption}. */
+        showEmpty?: false;
+        /** The values are laid out down the rows, or are to be with a second; their position is `-2` in {@link rowFields}. */
+        valuesOnRows?: true;
+        /**
+         * Below two values, where a second puts them among the fields of their axis, counted from 0; absent,
+         * after the last.
+         */
+        valuesPosition?: number;
+        /** A field takes more than one filter; absent, a new filter on a field replaces its last. */
+        multipleFiltersPerField?: true;
+        /** How many page fields sit in a row (or a column) before the next; absent, 0, no wrap. */
+        pageWrap?: number;
+        /** The page fields run across, then down; absent, down, then across. */
+        pageOverThenDown?: true;
+        /** The items' expand/collapse buttons are hidden; absent, shown. */
+        hiddenDrillIndicators?: true;
+        /** The field captions and their buttons are hidden; absent, shown. */
+        hiddenFieldHeaders?: true;
+        /** The table style and which of its parts show; absent, no style. */
+        style?: PivotStyleJSON;
+        /** The label, value and date filters, in the order they apply. */
+        filters?: PivotFilterJSON[];
+        /** `false`: a refresh drops the formats a user put on the table's cells; absent, they follow their areas. */
+        preserveFormatting?: false;
+        /** `false`: a layout leaves the columns' widths alone; absent, it fits the columns the table covers. */
+        autoFitColumns?: false;
+        /** The formats a user put on parts of the table, in the order they apply. */
+        formats?: PivotFormatJSON[];
+        /** The table's conditional formats: which sheet rule applies where in the table. */
+        conditionalFormats?: PivotConditionalFormatJSON[];
+        /** Where the laid-out parts start; absent, not laid out. */
+        header?: PivotHeaderJSON;
+        /** The lines of the rows as last laid out, top to bottom; absent, not laid out. */
+        rowLines?: PivotLineJSON[];
+        /** The lines of the columns as last laid out, left to right; absent, not laid out. */
+        columnLines?: PivotLineJSON[];
+        /** The definition's markup with what is modeled taken out: anything not typed yet. */
+        rest?: string;
+    }
+    /** How a field's items are laid out: compact (absent), outline, or tabular. */
+    type PivotForm = 'outline' | 'tabular';
+    /** The style of a {@link JSON | pivot table}: a pivot table style by name, and which parts of it show. */
+    interface PivotStyleJSON {
+        name?: string;
+        showRowHeaders?: boolean;
+        showColumnHeaders?: boolean;
+        showRowStripes?: boolean;
+        showColumnStripes?: boolean;
+        showLastColumn?: boolean;
+    }
+    /**
+     * A filter of a {@link JSON | pivot table}: which items of a field show.
+     *
+     * @remarks
+     * A label filter tests each item's caption (the Display selector), a date filter its date (the
+     * Date selector, or a time period), and a value or top filter the item's total of a data field,
+     * within each item of the fields outside it.
+     */
+    interface PivotFilterJSON {
+        /** The field filtered, by index. */
+        field: number;
+        /** A value or top filter: the data field whose total is tested, by index into {@link JSON.dataFields}. */
+        dataField?: number;
+        condition: ICondition.JSON;
+        id?: number;
+        /** The order the filter applies in; absent, -1, the order listed. */
+        evalOrder?: number;
+        name?: string;
+        description?: string;
+        /** A date filter that takes whole days, as a timeline sets it. */
+        useWholeDay?: true;
+    }
+    /** A conditional format of a {@link JSON | pivot table}: a sheet rule, by priority, and the areas it applies to. */
+    interface PivotConditionalFormatJSON {
+        /** The sheet rule's priority, as read. */
+        priority: number;
+        /** What the areas select, as OOXML spells it (`selection`, `data`, `field`). */
+        scope?: string;
+        /** Which way the rule runs over the areas, as OOXML spells it (`none`, `all`, `row`, `column`). */
+        type?: string;
+        areas: PivotAreaJSON[];
+    }
+    /** A format on part of a {@link JSON | pivot table}: what it sets, and where. */
+    interface PivotFormatJSON {
+        /** What it sets, as a conditional format's style holds it. */
+        style: ICellStyle.Properties;
+        area: PivotAreaJSON;
+        /** `blank`: the area shows nothing; absent, the style is applied. */
+        action?: 'blank';
+    }
+    /** A part of a {@link JSON | pivot table}, as a format or a conditional format names it. */
+    interface PivotAreaJSON {
+        /** What kind of part, as OOXML spells it; absent, `normal`: the cells the references pick. */
+        type?: 'data' | 'all' | 'origin' | 'button' | 'topEnd' | 'topRight' | 'none';
+        /** The field, by index; `-2` the values. A button's field, or the field whose labels. */
+        field?: number;
+        /** `false`: labels as well as values; absent, values only. */
+        dataOnly?: false;
+        /** Labels only. */
+        labelOnly?: true;
+        /** The grand total row. */
+        grandRow?: true;
+        /** The grand total column. */
+        grandCol?: true;
+        /** `false`: tabular rather than outline positions; absent, outline. */
+        outline?: false;
+        /** A collapsed item's line counts as its subtotal. */
+        collapsedLevelsAreSubtotals?: true;
+        axis?: Axis;
+        /** The field's position on its axis; absent, 0. */
+        fieldPosition?: number;
+        /** The cells picked, one reference per field. */
+        references?: PivotAreaReferenceJSON[];
+        /** The area's attributes not typed yet (`offset`, `cacheIndex`), as markup; absent, none. */
+        rest?: string;
+    }
+    /** The items of one field a {@link PivotAreaJSON} picks. */
+    interface PivotAreaReferenceJSON {
+        /** The field, by index; `-2` the values. */
+        field: number;
+        /** By index into the field's items, or into the data fields for `-2`; absent, all of them. */
+        items?: number[];
+        /** `false`: the items are not selected; absent, they are. */
+        selected?: false;
+        /** The items count by position, not by index. */
+        byPosition?: true;
+        /** The items are relative to the cell. */
+        relative?: true;
+        /** Which of the field's subtotals, as OOXML spells them (`defaultSubtotal`, `sumSubtotal`, ...). */
+        subtotals?: string[];
+    }
+    /**
+     * One field of a {@link JSON | pivot table}: how the table uses a field of its cache.
+     */
+    interface PivotFieldJSON {
+        axis?: Axis;
+        /** The field is summarized by a data field. */
+        dataField?: true;
+        /** The caption shown for the field. */
+        name?: string;
+        /**
+         * The subtotals shown for the field: `default` is the automatic one. Absent, the automatic
+         * subtotal alone; empty, none.
+         */
+        subtotals?: PivotSubtotal[];
+        /** The whole caption of the field's automatic subtotal lines, in place of `<item> Total`. */
+        subtotalCaption?: string;
+        /** The field's items in the table's order, which is state: a refresh keeps it. */
+        items?: PivotItemJSON[];
+        /** How the field's items are laid out; absent, compact. */
+        form?: PivotForm;
+        /** `false`: the field's subtotals sit under its items rather than on their row. */
+        subtotalsOnTop?: false;
+        /** A blank line follows each item. */
+        blankRowAfter?: true;
+        /** Items no record falls in show as well. */
+        showItemsWithNoData?: true;
+        /** Each item's label repeats on every line it spans. */
+        repeatLabels?: true;
+        /** The number format of the items' labels: a format code, or a built-in format's id; absent, General. */
+        numberFormat?: string | number;
+        /**
+         * The items are sorted by label, or by the total of a data field (by index into
+         * {@link JSON.dataFields}); absent, they stay in {@link items}' order.
+         */
+        sort?: {
+            order: 'ascending' | 'descending';
+            dataField?: number;
+            /** Sorted by one line of the other axis rather than by its grand total; absent, the total. */
+            scope?: PivotSortScopeJSON;
+        };
+        /** Items new to the cache show after a refresh while the field is filtered. */
+        includeNewItemsInFilter?: true;
+        /** A page field shows more than one item. */
+        multipleItemSelection?: true;
+        /** The field's markup with what is modeled taken out. */
+        rest?: string;
+    }
+    /**
+     * The line of the other axis a {@link PivotFieldJSON.sort | sort by value} reads: its items, as a
+     * line's path names them.
+     */
+    interface PivotSortScopeJSON {
+        /** The line's items, outermost field of the other axis first; each by index into its field's items. */
+        items: {
+            field: number;
+            item: number;
+        }[];
+        /** The line is its innermost item's subtotal (a `2023 Total` column) rather than the item's own line. */
+        subtotal?: true;
+    }
+    /**
+     * One line of a laid-out {@link JSON | pivot table}'s rows or columns: an item, a subtotal, the
+     * grand total, or a blank row, as Excel stores it in `rowItems` and `colItems`.
+     *
+     * @remarks
+     * A line names its items by index into each axis field's {@link PivotFieldJSON.items}, from the
+     * outermost field in; where the values sit, the index is a data field's. The first
+     * {@link repeat} of them are the line above's and are left out.
+     */
+    interface PivotLineJSON {
+        /** Absent: an item. `default` (or a subtotal function) for a subtotal, `grand`, `blank`. */
+        type?: string;
+        /** How many leading items are the same as the line above's, and so not in {@link items}. */
+        repeat?: number;
+        /** The item indexes after the repeated ones. */
+        items: number[];
+        /** The data field the line shows, by index into {@link JSON.dataFields}; absent, the first. */
+        dataField?: number;
+    }
+    /**
+     * Where a laid-out {@link JSON | pivot table}'s parts start, relative to its location's
+     * top-left cell, as Excel stores them on `location`.
+     */
+    interface PivotHeaderJSON {
+        /** The row of the column items' labels. */
+        firstHeaderRow: number;
+        /** The first row of values. */
+        firstDataRow: number;
+        /** The first column of values. */
+        firstDataCol: number;
+    }
+    /** A subtotal function of a {@link PivotFieldJSON | field}, as OOXML spells it. */
+    type PivotSubtotal = 'default' | 'sum' | 'countA' | 'avg' | 'max' | 'min' | 'product' | 'count' | 'stdDev' | 'stdDevP' | 'var' | 'varP';
+    /**
+     * One item of a {@link PivotFieldJSON | field}: an item of the cache field, or a subtotal or
+     * grand-total line.
+     */
+    interface PivotItemJSON {
+        /** The index of the item in the cache field's items. */
+        item?: number;
+        /** The line it is, when not an item of the cache, as OOXML spells it (`default`, `sum`, `grand`…). */
+        type?: string;
+        hidden?: true;
+        /** Its details are not shown. */
+        collapsed?: true;
+        /** The caption shown in place of the item's value. */
+        name?: string;
+        /** A calculated item: its value is a formula over the field's other items, the cache's. */
+        calculated?: true;
+        /** The item is no longer in the source; kept until a refresh drops it. */
+        missing?: true;
+    }
+    /**
+     * A field on the page axis and the item it shows.
+     */
+    interface PageFieldJSON {
+        /** The field, by index. */
+        field: number;
+        /** The item shown, by index into the field's {@link PivotFieldJSON.items}; absent, all. */
+        item?: number;
+    }
+    /**
+     * A value of a {@link JSON | pivot table}: a field of the cache summarized by a function.
+     */
+    interface DataFieldJSON {
+        name: string;
+        /** The field summarized, by index. */
+        field: number;
+        /** The function, as OOXML spells it; absent, `sum`. */
+        subtotal?: string;
+        /**
+         * How the value is shown, as OOXML spells it (`percentOfTotal`, `difference`,
+         * `percentOfParentRow`, `rankAscending`…); absent, as is.
+         */
+        showDataAs?: string;
+        /** The field `showDataAs` compares against, by index. */
+        baseField?: number;
+        /**
+         * The item of {@link baseField} `showDataAs` compares against: by index, or the one before or
+         * after each item.
+         */
+        baseItem?: number | 'previous' | 'next';
+        /** The number format of its values: a format code, or a built-in format's id; absent, General. */
+        numberFormat?: string | number;
+    }
+    /**
+     * A value of a pivot table: a field summarized by a function.
+     *
+     * @remarks
+     * A view of the table, found by its caption: what is asked of it after the value is deleted, or after
+     * another view has renamed it, throws. Each change lays the table out again from its cache, as one
+     * step that can be undone, and a table that grows over cells that hold anything shows `#SPILL!`.
+     */
+    interface IDataField {
+        /** Returns its caption. */
+        getName(): string;
+        /**
+         * Changes its caption.
+         *
+         * @remarks
+         * Its source's caption is taken, unless that field has been renamed; so is any other field's, any
+         * other value's and the {@link IValuesField | values'}, without regard to case.
+         *
+         * @throws ExpectedError For a caption taken.
+         */
+        setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns the field it summarizes. */
+        getField(): IField;
+        /** Returns the function it summarizes by. */
+        getFunction(): IDataField.Function;
+        /**
+         * Changes the function it summarizes by.
+         *
+         * @remarks
+         * Its caption changes too, a caption typed by hand included, as in Excel: what comes before its
+         * first ` of ` takes the function's name, a caption with none becomes the function's name and the
+         * field's (`Average of Sales`), and one that is taken is numbered. Its number format stays. Nothing
+         * changes when the function is the one it has.
+         *
+         * A value over a calculated field takes the function in name alone, as in Excel: its formula
+         * decides what it shows.
+         *
+         * @throws ExpectedError For a function that is none.
+         */
+        setFunction(fn: IDataField.Function, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Returns the caption it would take with `fn`, as {@link setFunction} gives it; its own when `fn`
+         * is its function already.
+         *
+         * @example
+         * ```ts
+         * value.getName(); // 'Sum of Sales'
+         * value.getCaptionFor('average'); // 'Average of Sales'
+         * ```
+         *
+         * @throws ExpectedError For a function that is none.
+         */
+        getCaptionFor(fn: IDataField.Function): string;
+        /** Returns how it is shown; `null` as it is. */
+        getShowAs(): IDataField.ShowAs | null;
+        /**
+         * Changes how it is shown; `null` shows it as it is.
+         *
+         * @remarks
+         * A kind that reads a base field and is given none reads the one it has, at first the cache's
+         * first; every line shows `#N/A` when that is not on the rows or columns. A new base field starts
+         * at its first item. The base stays when the kind changes, and through `null`.
+         *
+         * The number format changes with the kind, as in Excel. A kind that shows a share takes `0.00%`
+         * unless it reads as a percent already; a rank or an index drops what it has; going from a share to
+         * any other drops a percent format. A format on single cells stays over any of it.
+         *
+         * @example
+         * ```ts
+         * await value.setShowAs({ kind: 'percentOfTotal' });
+         * await value.setShowAs({ kind: 'difference', baseField: 'Year', baseItem: '(previous)' });
+         * await value.setShowAs(null);
+         * ```
+         *
+         * @throws ExpectedError For a kind that is none, or a base field or item that is not the table's.
+         */
+        setShowAs(rule: IDataField.ShowAs | null, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns the format code its values show in. */
+        getNumberFormat(): string;
+        /**
+         * Changes the format of its values, over any number format on single cells of them, whose other
+         * formats (a fill) stay.
+         *
+         * @param format A format code, or a built-in format's id.
+         * @throws ExpectedError For a format that does not parse.
+         */
+        setNumberFormat(format: string | number, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns its place among the values, counted from 1. */
+        getPosition(): number;
+        /**
+         * Moves it among the values. A sort, a value filter and the formats on it follow it.
+         *
+         * @param position Its place, counted from 1.
+         * @throws ExpectedError For a position that is not among the values.
+         */
+        setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /**
+         * Takes it off the table.
+         *
+         * @remarks
+         * What names it goes too: a sort by it leaves its items in their listed order, and a value filter
+         * and the formats on it are gone for good. Its source stays on any axis it is on. The
+         * {@link IValuesField | values field} goes below two values, and comes back where it was. A table
+         * with nothing left on it is empty again.
+         */
+        delete(options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns the table it belongs to. */
+        getPivotTable(): IPivotTable;
+        /** For runtime type checking. */
+        readonly isIPivotDataField: true;
+    }
+    /**
+     * Where a table's values sit among the fields of an axis, with two or more of them.
+     *
+     * @remarks
+     * A view of the table. While a table has fewer than two values they sit nowhere, and the table keeps
+     * the axis and the place for the next.
+     */
+    interface IValuesField {
+        /** Returns its caption. */
+        getName(): string;
+        /**
+         * Changes its caption, which no field or value of the table can have, without regard to case.
+         *
+         * @throws ExpectedError For a caption taken.
+         */
+        setName(name: string, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns the axis the values are on; `null` once they have gone. */
+        getAxis(): Axis | null;
+        /**
+         * Moves the values to the rows or the columns, as one step that can be undone; `null` deletes every
+         * value.
+         *
+         * @param position Its place, counted from 1, among the axis's fields; absent, after the last, and
+         * nothing when it is on `axis`.
+         * @throws ExpectedError For the page axis, the values, or a position not on the axis.
+         */
+        setAxis(axis: Axis | null, position?: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns its place among the fields of its axis, counted from 1; `null` once the values have gone. */
+        getPosition(): number | null;
+        /**
+         * Moves it along its axis, as one step that can be undone.
+         *
+         * @param position Its place, counted from 1.
+         * @throws ExpectedError For a position not on the axis, or once the values have gone.
+         */
+        setPosition(position: number, options?: ITransaction.OperationOptions): Promise<void>;
+        /** Returns the table it belongs to. */
+        getPivotTable(): IPivotTable;
+        /** For runtime type checking. */
+        readonly isIPivotValuesField: true;
+    }
+    /** What belongs to {@link IDataField}. */
+    namespace IDataField {
+        /** A function that summarizes a value, as OOXML spells it. */
+        type Function = 'sum' | 'count' | 'average' | 'max' | 'min' | 'product' | 'countNums' | 'stdDev' | 'stdDevp' | 'var' | 'varp';
+        /** How a value can be shown, as OOXML spells it. */
+        type ShowAsKind = 'percentOfTotal' | 'percentOfRow' | 'percentOfCol' | 'index' | 'percentOfParentRow' | 'percentOfParentCol' | 'percentOfParent' | 'runTotal' | 'percentOfRunningTotal' | 'rankAscending' | 'rankDescending' | 'difference' | 'percent' | 'percentDiff';
+        /** How a value is shown. */
+        interface ShowAs {
+            kind: ShowAsKind;
+            /** The field a kind reads across, by caption; absent, the one it has. */
+            baseField?: string;
+            /**
+             * The item of {@link baseField} a kind compares with, by caption, or `(previous)` or `(next)` for
+             * the neighbor of each item; absent, the one it has.
+             */
+            baseItem?: string;
+        }
+        /** A value to add. */
+        interface Input {
+            /** The field to summarize. */
+            field: string;
+            /** Absent, the function's name and the field's (`Sum of Sales`), numbered when taken. */
+            name?: string;
+            /**
+             * Absent, sum for a column of numbers and count for any other.
+             */
+            function?: Function;
+            /** A format code, or a built-in format's id; absent, General. */
+            numberFormat?: string | number;
+        }
     }
     /**
      * `Events` for {@link IPivotTable}.