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

package/types/scripting.d.ts

@@ -3301,6 +3301,18 @@ declare global {
      */
     export type ESIterator<T, TReturn = any, TNext = undefined> = Iterator<T, TReturn, TNext>;
 
+    /**
+     * Where a process stands under its license, as enforcement sees it.
+     *
+     * - `licensed` — a key covers it; nothing below applies.
+     * - `evaluation` — unlicensed, inside the evaluation period: runs in full. A page served over
+     *   http(s) stays here for good — the watermark is its enforcement.
+     * - `grace` — past the period: exports (every format but `.sxl`) are refused.
+     * - `stopped` — past the grace too: calculation and scripts stop as well. A workbook still opens
+     *   and still saves as `.sxl`, so no one is locked out of their own work.
+     */
+    export type EvalState = 'licensed' | 'evaluation' | 'grace' | 'stopped';
+
     /**
      * Special classification that that indicated the error is caused by user input.
      */
@@ -5146,6 +5158,35 @@ declare global {
          * The expression is read as storage text unless `options.target` is `'display'`.
          */
         evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
+        /**
+         * Evaluates several formulas over values of the caller's, in one request.
+         *
+         * @param request The values and the formulas.
+         * @returns One range per {@link ICalculation.BatchRequest.formulas | formula}, in the order given,
+         * the shape of its `coords` (a single cell included), read with local coordinates:
+         * `getValueAt(0, 0)` is the top-left of `coords`.
+         *
+         * @remarks
+         * - The values and formulas sit on a grid of their own, on no sheet, kept for this request only.
+         *   Nothing in the workbook changes, and it is never an undo step.
+         * - A formula reads the values by address and may read another formula's cells; the engine
+         *   orders them. Each is filled across its `coords`, relative references moving with it.
+         * - A cell that errors carries its error; the others are unaffected.
+         *
+         * @example
+         * ```typescript
+         * const [margin, doubled] = await calculation.evaluateBatch({
+         *   values: [[0, [[0, [100, 60]]]], [1, [[0, [50, 40]]]]],
+         *   formulas: [
+         *     { expression: 'A1-B1', coords: { rowStart: 0, colStart: 2, rowEnd: 1, colEnd: 2 } },
+         *     { expression: 'C1*2', coords: { rowStart: 0, colStart: 3, rowEnd: 1, colEnd: 3 } }
+         *   ]
+         * });
+         * margin.getValueAt(1, 0); // 10
+         * doubled.getValueAt(1, 0); // 20
+         * ```
+         */
+        evaluateBatch(request: ICalculation.BatchRequest): Promise<IRange[]>;
         /**
          * When the engine recalculates on its own — Excel's Calculation Options.
          *
@@ -6045,6 +6086,27 @@ declare global {
         /**
          * Options for evaluating a formula.
          */
+        /** What {@link ICalculation.evaluateBatch} evaluates. */
+        interface BatchRequest {
+            /** The values the formulas read, by row: `[row, [[column, values]]]`, A1 at row 0, column 0. */
+            values: Tuple.GridTuple<Scalar>;
+            /** The formulas. One over cells that hold a value replaces it. */
+            formulas: readonly BatchFormula[];
+            /**
+             * How long to wait, in milliseconds, for the answers of async functions; a cell still waiting
+             * then answers a `#TIMEOUT!` error.
+             *
+             * @defaultValue `30000`
+             */
+            timeout?: number;
+        }
+        /** One formula of a {@link BatchRequest}. */
+        interface BatchFormula {
+            /** The expression, with or without a leading `=`, written for the top-left of {@link coords}. */
+            expression: string;
+            /** The cells it is filled across. */
+            coords: IRange.Coords;
+        }
         interface EvaluateOptions {
             /**
              * If specified, evaluates only the token span associated with this index.
@@ -6901,20 +6963,6 @@ declare global {
          *   values, as 'general' is resolved to left or right based on the cell's content type.
          */
         getRenderHorizontalAlignment(): ITextFrame.HorizontalAlignment;
-        /**
-         * Return an {@link ITable.IColumn} if the cell is the the first row of an ITable range.
-         */
-        getColumn(): ITable.IColumn | null;
-        /**
-         * Returns the cell's primary data validation: the highest-priority one that covers it, or `null`
-         * when none does.
-         *
-         * @remarks
-         * Validations may overlap, and every one that covers the cell applies; see
-         * {@link ICellRange.getDataValidations} for all of them. The primary one is also the one Excel
-         * honors when it opens a file whose validations overlap.
-         */
-        getDataValidation(): IDataValidation | null;
         /**
          * Returns what the cell's conditional formatting DRAWS in it — an in-cell bar, an icon, or
          * neither.
@@ -6942,10 +6990,6 @@ declare global {
          * checkbox cell holding `2` has a control and draws `2`.
          */
         getControl(): ICellControl | null;
-        /**
-         * If the cell is in a table this will return it.
-         */
-        getTable(): ITable | null;
         /**
          * Returns `true` if the cell contains a value.
          *
@@ -8659,14 +8703,16 @@ declare global {
          */
         setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
         /**
-         * Returns the {@link IDataValidation}s that overlap the range.
+         * Returns the {@link IDataValidation}s that overlap the range, in priority order.
          *
          * @param options The filters of {@link IDataValidationCollection.getItems} without `address` —
          * this range is the address.
          *
          * @remarks
          * **Plural, unlike Excel.** A cell carries at most one validation there, so Excel's range accessor
-         * is singular; here a range may overlap any number of independently anchored validations.
+         * is singular; here a range may overlap any number of independently anchored validations. Every
+         * one that covers a cell applies to it. For a single cell the first is its primary validation,
+         * the one Excel honors when it opens a file whose validations overlap.
          *
          * See {@link getConditionalFormats} for the overlap and one-entry-per-item rules, which are the
          * same for every ranged item lookup.
@@ -8694,6 +8740,14 @@ declare global {
          * `fullyContained` to ask only for tables the range wholly encloses.
          */
         getTables(options?: ICellRange.GetItemsOptions<ITableCollection.GetItemsOptions>): ITable[];
+        /**
+         * Returns the {@link IPivotTable}s with a cell in the range, in the order the sheet lists them.
+         *
+         * @remarks
+         * A table's cells are its location and its page fields, not the blank row between them, as
+         * Excel's `Range.PivotTable` answers. A table showing `#SPILL!` holds its anchor alone.
+         */
+        getPivotTables(): IPivotTable[];
         /**
          * Returns the {@link IMovable}s anchored over the range.
          *
@@ -11322,6 +11376,11 @@ declare global {
             readonly Table: "table";
             /** Auto-table membership. */
             readonly AutoTable: "autoTable";
+            /**
+             * Cells a pivot table is laid out over, the page fields above it included. A blocked table
+             * covers none; {@link ICellRange.getPivotTables} names the tables over a range.
+             */
+            readonly Pivot: "pivot";
             /** Has a hyperlink. Regions group by what the link says, so the same link set twice is one region. */
             readonly Hyperlink: "hyperlink";
             /**
@@ -17326,6 +17385,12 @@ declare global {
              * Checks any text value is greater than or equal to.
              */
             readonly TextContains: "textContains";
+            /**
+             * Checks any text value matches a pattern, the whole text and ignoring case: `*` is any run of
+             * characters, `?` any one, and `~` makes the next `*`, `?` or `~` itself. Excel's filter
+             * `equal` with a wildcard (`a?ple`, `N*th`).
+             */
+            readonly TextMatches: "textMatches";
             /**
              * Evaluates a formula expression.
              *
@@ -17636,8 +17701,17 @@ declare global {
             limit?: number;
             /**
              * Flag indicating whether or not to filter by percent value. A `false` value filters by number of items.
+             *
+             * @remarks
+             * With {@link sum}, the percent of the values' total rather than of their count.
              */
             percent?: boolean;
+            /**
+             * Whether {@link limit} bounds the values' sum rather than their count: values are taken from
+             * the top (or the bottom) until their running sum reaches the limit, the one that reaches it
+             * included. A pivot table's Top 10 by Sum, and by Percent with {@link percent}.
+             */
+            sum?: boolean;
             /**
              * Flag indicating whether or not to filter by top order. A `false` value filters by bottom order.
              */
@@ -18651,11 +18725,12 @@ declare global {
          */
         interface JSON extends Properties {
             /**
-             * If associated with a pivot.
+             * Present when the rule belongs to a pivot table: the number the table names it by, which is
+             * the priority the rule had in the file it was read from.
              *
-             * @defaultValue false
+             * @internal
              */
-            pivot?: boolean;
+            pivotKey?: number;
             /**
              * Payload from a rule this build does not understand.
              *
@@ -22288,7 +22363,7 @@ declare global {
      * | Dates | `getNow`, `toSerialDate`, `fromSerialDate`, `getDateParts`, `getSerialDate`, `parseAsDate`, `parseAsSerialDate`, `isValidDate` |
      * | Coercion | `parseAsNumber`, `parseAsLiteral`, `toText`, `compare` |
      * | Criteria | `createCriteria` |
-     * | Grouping | `createGrouping` |
+     * | Grouping | `createPivot`, `getPivotAt` |
      * | Sheet introspection | `getSheetCount`, `getSheetIndex`, `getAddress`, `getNumberFormat` |
      *
      * ### Implementors
@@ -22600,32 +22675,50 @@ declare global {
          */
         createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
         /**
-         * Groups the records of a range — its rows — by their values.
+         * Groups the records of a range two ways at once — by row keys and by column keys — at every
+         * key level of each, and crosses every row group with every column group.
          *
-         * @param keys The key columns. Each row is one record, and records with equal values in every
-         * column form one group.
-         * @param options Which records take part. See {@link IFormulaContext.GroupingOptions}.
-         * @returns The groups, numbered in the order they first appear.
+         * @param rows The row key columns, or `null` for none: every record is then in the one row group.
+         * @param columns The column key columns, or `null` for none.
+         * @param options Which records take part. See {@link IFormulaContext.PivotOptions}.
+         * @returns The two axes of groups and what their crossings hold.
+         * @throws `#VALUE!` for more than 32 key columns on one axis, or more groups and crossings than
+         * the pivot can number.
          *
          * @remarks
-         * Two keys are equal by the rule `UNIQUE` uses: text ignores case, and types never mix, so `1`,
-         * `"1"` and `TRUE` are three groups. A blank key is a key of its own, distinct from `""`, and an
-         * error is a key like any other value. Every row is a record, blank rows included.
+         * Every row is a record, blank rows included. Two keys are equal by the rule `UNIQUE` uses: text
+         * ignores case, and types never mix, so `1`, `"1"` and `TRUE` are three groups. A blank key is a
+         * key of its own, distinct from `""`, and an error is a key like any other value.
          *
-         * Group ONCE and ask the grouping for each group's members. The grouping does the work a
-         * per-group scan would repeat, so it stays proportional to the data rather than to the data
-         * times the number of groups.
+         * Each axis is a tree: its root is every kept record, the root's children are the groups of the
+         * first key column, theirs add the second, and so on, each in the order its first record appears.
+         * A subtotal is then one group, never a union of its children.
+         *
+         * One pivot answers what a grouping per key level, and another per pair of levels, would — in
+         * one pass, which is what `PIVOTBY` and a pivot table need.
          *
          * @example
          * ```typescript
-         * const grouping = FormulaContext.createGrouping(regions);
-         * for (let g = 0; g < grouping.getGroupCount(); g++) {
-         *   const [region] = grouping.getKeys(g);
-         *   const sales = grouping.getMembers(amounts, [g]);
+         * const pivot = FormulaContext.createPivot(regions, years);
+         * for (const region of pivot.getRows().getRoot().getChildren()) {
+         *   const total = pivot.getMembers(sales, region); // every year
+         *   const [name] = region.getKeys();
          * }
          * ```
          */
-        createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+        createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+        /**
+         * The pivot table a reference touches, as the values it shows.
+         *
+         * @param reference Any cell or range of the table, its page fields included.
+         * @returns The view, or `null` when the reference touches no pivot table, or the table's values
+         * are not computed (it is not modeled, or its view has not loaded yet).
+         *
+         * @remarks
+         * What `GETPIVOTDATA` reads. The view answers for the values the table shows; matching a request
+         * to its fields and items by name is the caller's.
+         */
+        getPivotAt(reference: IReferenceRange): IFormulaContext.PivotView | null;
         /**
          * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
          *
@@ -22974,9 +23067,9 @@ declare global {
             anchor?: 'whole' | 'start';
         }
         /**
-         * Options for {@link IFormulaContext.createGrouping}.
+         * Options for {@link IFormulaContext.createPivot}.
          */
-        interface GroupingOptions {
+        interface PivotOptions {
             /**
              * One column, as tall as the keys, selecting the records that take part. A record is kept
              * when its member is `TRUE` or a nonzero number, and left out otherwise.
@@ -22984,48 +23077,148 @@ declare global {
             filter?: IRange;
         }
         /**
-         * The records of a range divided into groups — see {@link IFormulaContext.createGrouping}.
+         * The records of a range grouped by rows and by columns — see {@link IFormulaContext.createPivot}.
          */
-        interface Grouping {
+        interface Pivot {
             /**
              * The number of records kept by the filter.
              */
             getRecordCount(): number;
             /**
-             * The number of groups.
+             * The row groups.
              */
-            getGroupCount(): number;
+            getRows(): PivotAxis;
             /**
-             * The number of records in a group.
+             * The column groups.
              */
-            getSize(group: number): number;
+            getColumns(): PivotAxis;
             /**
-             * A group's key, one value per key column, as spelled by the group's first record. A blank
-             * key is `null`.
+             * The members of `values` in both a row group and a column group, as one column in record order.
+             *
+             * @param values One column, as tall as the keys.
+             * @param row A group of this pivot's rows; omit it, or pass the root, for every row.
+             * @param column A group of this pivot's columns; omit it, or pass the root, for every column.
+             * @returns An array, never a reference, or `null` when no kept record is in both groups.
              */
-            getKeys(group: number): readonly Scalar[];
+            getMembers(values: IRange, row?: PivotGroup, column?: PivotGroup): IRange | null;
             /**
-             * The group a record belongs to, or `-1` when the filter left it out.
+             * What `fn` returns over the members {@link getMembers} would give, computed without them.
+             *
+             * @returns `null` when no kept record is in both groups, `undefined` when the pivot does not
+             * compute `fn` this way: call `fn` over {@link getMembers} instead.
              *
-             * @param record The record's row within the keys.
+             * @remarks
+             * Optional. Where it is present it answers for the built-in aggregates it knows (`SUM`,
+             * `COUNT`, `AVERAGE`, ...) with exactly the value the call would return, the first error
+             * member included.
              */
-            getGroup(record: number): number;
+            getAggregate?(values: IRange, fn: IFunction, row?: PivotGroup, column?: PivotGroup): Scalar | null | undefined;
+        }
+        /**
+         * A pivot table as the values it shows — see {@link IFormulaContext.getPivotAt}.
+         */
+        interface PivotView {
+            /**
+             * The table's values, in its order.
+             */
+            getDataFields(): readonly PivotViewDataField[];
             /**
-             * The row of a group's first record within the keys.
+             * The fields on the table's rows, columns and pages, in that order.
+             */
+            getFields(): readonly PivotViewField[];
+            /**
+             * A value the table shows.
              *
-             * @remarks
-             * With {@link getGroup} on another grouping of the same records, this maps a group of one
-             * grouping onto the group of another — a finer grouping's group onto its parent's.
+             * @param dataField The value, by index into {@link getDataFields}.
+             * @param items Per field, by index into {@link getFields}, the item by index into its
+             * {@link PivotViewField.items}. A field left out is totaled over.
+             * @returns The value, or `undefined` when the table does not show it: a line it does not show
+             * (a hidden or collapsed item, a subtotal or grand total turned off), an item not on its page,
+             * or a crossing with no records.
              */
-            getFirstRecord(group: number): number;
+            getValue(dataField: number, items: ReadonlyMap<number, number>): Scalar | undefined;
             /**
-             * The members of `values` that belong to some groups, as one column in record order.
+             * Whether the table's values are known here.
              *
-             * @param values One column, as tall as the keys.
-             * @param groups The groups to take members from. Omit it for every kept record.
-             * @returns An array, never a reference. A blank member stays blank.
+             * @returns `false` for a table that is there but whose values the host does not compute: its
+             * fields and values are empty, and a caller that answered from it before keeps that answer, as
+             * the table only changes on a refresh. Absent means `true`.
+             */
+            isComputed?(): boolean;
+        }
+        /**
+         * A value of a {@link PivotView}.
+         */
+        interface PivotViewDataField {
+            /** As the table shows it (`Sum of Sales`). */
+            readonly name: string;
+            /** The name of the source field it summarizes (`Sales`). */
+            readonly sourceName: string;
+        }
+        /**
+         * A field of a {@link PivotView}.
+         */
+        interface PivotViewField {
+            /** As the table shows it: its caption, or the source field's name. */
+            readonly name: string;
+            readonly items: readonly PivotViewItem[];
+        }
+        /**
+         * An item of a {@link PivotViewField}.
+         */
+        interface PivotViewItem {
+            /** The item's value; `null` for the blank item. */
+            readonly value: Scalar;
+            /** The value as the table shows it, in the field's number format; `(blank)` for the blank item. */
+            readonly text: string;
+            /** The caption the item was renamed to, if it was. */
+            readonly name?: string;
+        }
+        /**
+         * One axis of a {@link Pivot}: its groups at every key level, as a tree under one root.
+         */
+        interface PivotAxis {
+            /**
+             * The group of every kept record, at level `0`.
+             */
+            getRoot(): PivotGroup;
+            /**
+             * The number of groups, the root included.
+             */
+            getGroupCount(): number;
+        }
+        /**
+         * One group of a {@link PivotAxis}. The axis answers the same object for a group every time, so a
+         * group can key a map.
+         */
+        interface PivotGroup {
+            /**
+             * The number of key columns the group is keyed by: `0` for the root, `1` for the groups of the
+             * first key column, and so on.
+             */
+            getLevel(): number;
+            /**
+             * The group one level up, or `null` for the root.
+             */
+            getParent(): PivotGroup | null;
+            /**
+             * The groups one level down, in the order their first records appear.
+             */
+            getChildren(): readonly PivotGroup[];
+            /**
+             * The keys, one per level down to this group's own. Each level's key is spelled by the first
+             * record of the group at that level, so a group's keys begin with its parent's. A blank key is
+             * `null`.
+             */
+            getKeys(): readonly Scalar[];
+            /**
+             * The number of kept records in the group.
              */
-            getMembers(values: IRange, groups?: readonly number[]): IRange;
+            getSize(): number;
+            /**
+             * The row of the group's first record within the keys.
+             */
+            getFirstRecord(): number;
         }
         /**
          * A serial date split into fields — see {@link IFormulaContext.getDateParts}.
@@ -29468,37 +29661,150 @@ declare global {
     }
 
     /**
-     * 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!`.
+         */
+        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.
          */
-        getXML(): string | null;
+        isStale(): boolean;
         /**
          * Returns the id of the cache this table summarizes.
          *
@@ -29508,17 +29814,911 @@ declare global {
          * @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 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.
@@ -29526,7 +30726,528 @@ declare global {
         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}.
@@ -29537,12 +31258,37 @@ declare global {
 
     /**
      * Holds {@link IPivotTable | pivot tables} — a sheet's, or every sheet's in the workbook.
-     *
-     * @remarks
-     * Read-only for now: a table is carried as it was read and written back unchanged. Adding,
-     * deleting and refreshing wait on the table having a model of its own.
      */
     export interface IPivotTableCollection extends ICollection<IPivotTable> {
+        /**
+         * Adds a pivot table on this sheet, as one step that can be undone.
+         *
+         * @param source The cells to summarize, their first row the field names: a range, a table, or a
+         * table's or defined name's name. A table already summarizing the same source shares its cache
+         * unless the source was edited since, so they refresh together.
+         * @param location Where the table's top-left cell goes. Filters sit above it, a blank row between;
+         * at the top of a sheet the table moves down to make room for them.
+         * @param options The fields to place. With none, the table is empty and holds 18 rows by 3 columns.
+         *
+         * @remarks
+         * The cells the table needs, its filters' included, must hold no value, unless
+         * {@link IPivotTableCollection.AddOptions.discardValues} clears them. Another pivot table or an
+         * array's cells there always refuse it.
+         *
+         * @example
+         * ```ts
+         * const pivot = await sheet.getPivotTables().add('Data!A1:H500', 'A3', {
+         *   rows: ['Region'],
+         *   columns: ['Year'],
+         *   values: ['Sales', { field: 'Sales', function: 'average' }]
+         * });
+         * ```
+         *
+         * @throws When the cells it needs hold a value, an array or another pivot table, a field or the source does not
+         * exist, the source has no row of data, the name is taken on this sheet or the sheet is locked; and
+         * on the workbook's collection, which holds no sheet to add to.
+         */
+        add(source: IPivotTableCollection.Source, location: ICellRange.Address, options?: IPivotTableCollection.AddOptions): Promise<IPivotTable>;
         /**
          * Returns the pivot tables, in the order they were read; the workbook's walks its sheets in
          * sheet order.
@@ -29552,12 +31298,51 @@ declare global {
          * Returns the pivot table with the given name, or `null` if there is none.
          *
          * @param name The name of the pivot table. This is case insensitive.
+         *
+         * @remarks
+         * A name is unique only on its sheet, so the workbook's collection returns the first table with
+         * that name in sheet order. Ask the sheet's collection to find one table for certain.
          */
         getByName(name: string): IPivotTable | null;
+        /**
+         * Refreshes every table ({@link IPivotTable.refresh}) as one step that can be undone.
+         *
+         * @remarks
+         * A table that cannot be refreshed refuses the whole step, and nothing changes.
+         */
+        refreshAll(options?: IPivotTable.RefreshOptions): Promise<void>;
         /** For runtime type checking. */
         readonly isIPivotTableCollection: true;
     }
 
+    export namespace IPivotTableCollection {
+        /** What a pivot table summarizes. A string is a table's name, a defined name, or an address. */
+        type Source = ICellRange.Address | ITable;
+        /** Options for {@link IPivotTableCollection.add}. */
+        interface AddOptions extends ITransaction.OperationOptions {
+            /** Absent, `PivotTable` and one past the highest number the workbook's tables have. */
+            name?: string;
+            /** The fields down the rows, outermost first. */
+            rows?: readonly string[];
+            /** The fields across the columns, outermost first. */
+            columns?: readonly string[];
+            /** The fields above the table, each filtering it by an item. */
+            pages?: readonly string[];
+            /** The values. A field's name alone sums a column of numbers, blanks among them, and counts any other. */
+            values?: readonly (string | IPivotTable.IDataField.Input)[];
+            /** Absent, compact. */
+            form?: 'compact' | IPivotTable.PivotForm;
+            /** A pivot table style by name; absent, `PivotStyleLight16`. */
+            style?: string;
+            /**
+             * Whether values in the cells the table needs are cleared; `false` refuses the table instead.
+             *
+             * @defaultValue `false`
+             */
+            discardValues?: boolean;
+        }
+    }
+
     /**
      * Contains interfaces for working with properties.
      */
@@ -34305,17 +36090,20 @@ declare global {
     export const isLazyValue: (value: unknown) => value is ILazy;
 
     /**
-     * A slicer: buttons that filter one column of a table.
+     * A slicer: buttons that filter one column of a table, or one field of pivot tables.
      *
      * @remarks
-     * A slicer holds no selection of its own. What it shows as selected is the column's filter
-     * ({@link ITable.IColumn.getFilter}), so a filter set from the column's menu shows on the slicer,
-     * and a selection made on the slicer is the column's filter, saved with the table. Two slicers on
-     * one column always agree.
-     *
-     * The column is named by a structured reference ({@link getSource}), which follows the table and
-     * the column through a rename. When the column or its table is deleted, the slicer is deleted with
-     * it, in the same step; an undo brings both back.
+     * A slicer holds no selection of its own. On a table, what it shows as selected is the column's
+     * filter ({@link ITable.IColumn.getFilter}), so a filter set from the column's menu shows on the
+     * slicer, and a selection made on the slicer is the column's filter, saved with the table. On pivot
+     * tables it is the field's items hidden by hand ({@link IPivotTable.IField.setVisibleItems}), the
+     * same on every pivot table it filters; a label or value filter on the field does not show on it.
+     * Two slicers on one column or field always agree.
+     *
+     * A table slicer follows its table and column through a rename. When the column or its table is
+     * deleted, the slicer is deleted with it, in the same step; an undo brings both back. A pivot slicer
+     * stays when its pivot tables are deleted, filtering nothing, and is deleted with its field when a
+     * pivot table's source no longer has it.
      *
      * Where a slicer sits is its movable's ({@link IMovable.getBounds}); it moves freely of the cells
      * under it by default.
@@ -34329,31 +36117,46 @@ declare global {
      */
     export interface ISlicer extends IModel, IMovable.IContent {
         /**
-         * Returns the column the slicer filters, as a structured reference: `Sales[Region]`.
+         * Returns the name of what the slicer filters: the column's, or the pivot field's in its source.
          *
          * @remarks
-         * Follows a rename of the table or the column.
+         * A table slicer's follows a rename of the column.
          */
-        getSource(): string;
+        getSourceName(): string;
         /**
-         * Returns the table the slicer filters, or `null` if it names none.
+         * Returns what the slicer filters: the table, or the first pivot table; `null` if there is none.
+         *
+         * @see {@link getPivotTables} for every pivot table a pivot slicer filters.
          */
-        getTable(): ITable | null;
+        getTable(): ITable | IPivotTable | null;
         /**
-         * Returns the column the slicer filters, or `null` if it names none.
+         * Returns the column the slicer filters, or `null` for a pivot slicer or one naming no column.
          */
         getColumn(): ITable.IColumn | null;
+        /**
+         * Returns the pivot tables the slicer filters; empty for a table slicer, or once they are deleted.
+         */
+        getPivotTables(): readonly IPivotTable[];
+        /**
+         * Returns the field a pivot slicer filters, as its first pivot table has it; `null` for a table
+         * slicer, or when there is no pivot table.
+         *
+         * @remarks
+         * Each pivot table has its own field. Select through the slicer, which changes every one of them.
+         */
+        getPivotField(): IPivotTable.IField | null;
         /**
          * Returns the text shown in the slicer's header.
          *
          * @remarks
-         * The column's name unless a caption has been set, and then it follows a rename of the column.
+         * {@link getSourceName} unless a caption has been set. A slicer added on a pivot field with a
+         * caption of its own starts with that caption, and keeps it when the field's changes.
          */
         getCaption(): string;
         /**
          * Sets the text shown in the slicer's header.
          *
-         * @param caption The caption, or `null` to show the column's name.
+         * @param caption The caption, or `null` to show {@link getSourceName}.
          */
         setCaption(caption: string | null, options?: ITransaction.OperationOptions): this;
         /**
@@ -34388,6 +36191,8 @@ declare global {
         getSortOrder(): ISlicer.SortOrder;
         /**
          * Sets the order the items are listed in.
+         *
+         * @throws ExpectedError For `'dataSource'` on a pivot slicer, which Excel does not offer.
          */
         setSortOrder(sortOrder: ISlicer.SortOrder, options?: ITransaction.OperationOptions): this;
         /**
@@ -34423,15 +36228,18 @@ declare global {
          */
         setLockedPosition(locked: boolean, options?: ITransaction.OperationOptions): this;
         /**
-         * Returns `true` when the column has no filter: every item is selected.
+         * Returns `true` when every item is selected: the column has no filter, or the field hides no item.
          */
         isFilterCleared(): boolean;
         /**
-         * Returns the items: the column's distinct values as it shows them, in the slicer's order.
+         * Returns the items: the column's distinct values as it shows them, or the field's items, in the
+         * slicer's order.
          *
          * @remarks
          * Every row of the column is read, hidden or not. An item has data when at least one row
-         * holding it passes the other columns' filters. Blanks are one item, keyed `''`, listed last.
+         * holding it passes the other columns' filters; on pivot tables, when a source row holding it
+         * passes the items the first pivot table's other fields hide, and an item the source no longer
+         * holds has none. Blanks are one item, keyed `''`, listed last in ascending order.
          */
         getItems(): Promise<readonly ISlicer.Item[]>;
         /**
@@ -34439,17 +36247,18 @@ declare global {
          */
         getItem(key: string): Promise<ISlicer.Item | null>;
         /**
-         * Selects the items with `keys` and no others, by filtering the column.
+         * Selects the items with `keys` and no others, by filtering the column or by hiding the field's
+         * other items on every pivot table, as one step that can be undone.
          *
          * @param keys The items' keys. `null`, an empty list or every item clears the filter.
          *
          * @remarks
          * The other columns' filters stay. On a date column the selection is saved as the dates
-         * themselves, not their text.
+         * themselves, not their text. A pivot field's label, date and value filters stay.
          */
         selectItems(keys: readonly string[] | null, options?: ITransaction.OperationOptions): Promise<this>;
         /**
-         * Clears the column's filter, selecting every item.
+         * Clears the column's filter, or shows every item of the field, selecting every item.
          */
         clearFilters(options?: ITransaction.OperationOptions): Promise<this>;
         /**
@@ -34500,21 +36309,21 @@ declare global {
          */
         interface Item {
             /**
-             * The item's identity: the text the column shows for it, `''` for the blank item. What
-             * {@link ISlicer.selectItems} takes.
+             * The item's identity: the text the column shows for it, or the pivot item's caption; `''` for
+             * the blank item. What {@link ISlicer.selectItems} takes.
              */
             key: string;
             /** The text shown on the button. */
             name: string;
-            /** The value of the first cell showing the item; `null` for the blank item. */
+            /** The value of the first cell showing the item, or the pivot item's; `null` for the blank item. */
             value: Scalar;
-            /** Whether at least one row holding the item passes the other columns' filters. */
+            /** Whether at least one row holding the item passes the other columns' or fields' filters. */
             hasData: boolean;
-            /** Whether the column's filter selects the item. */
+            /** Whether the column's filter selects the item, or the field shows it. */
             isSelected: boolean;
         }
         /**
-         * Options for {@link ITable.addSlicer}.
+         * Options for {@link ITable.addSlicer} and {@link IPivotTable.addSlicer}.
          */
         interface AddOptions extends IMovableCollection.AddOptions<ISlicer.JSON> {
             /**
@@ -34523,7 +36332,11 @@ declare global {
              * @defaultValue The table's sheet.
              */
             sheet?: IWorksheet;
-            /** {@inheritDoc ISlicer.JSON.caption} */
+            /**
+             * The header text.
+             *
+             * @defaultValue The column's name, or the pivot field's caption.
+             */
             caption?: string;
             /**
              * The slicer style's name.
@@ -34539,11 +36352,12 @@ declare global {
          */
         interface Events extends IMovable.ContentEvents {
             /**
-             * Called when the column's filter changes, by this slicer or anything else.
+             * Called when the column's filter or the field's hidden items change, by this slicer or anything
+             * else.
              */
             onSelectionChange?(source: ISlicer): void;
             /**
-             * Called when the column's values change, so the items may have.
+             * Called when the column's values or the pivot tables change, so the items may have.
              */
             onItemsChange?(source: ISlicer): void;
         }
@@ -34554,11 +36368,11 @@ declare global {
          */
         interface JSON {
             /**
-             * The column, as a structured reference: `Sales[Region]`.
+             * The column, as a structured reference: `Sales[Region]`. Absent for a slicer on a pivot table.
              */
-            source: string;
+            source?: string;
             /**
-             * The header text. Absent, the column's name.
+             * The header text. Absent, the column's or the pivot field's name.
              */
             caption?: string;
             /**
@@ -34619,6 +36433,56 @@ declare global {
              * The id the file gave the slicer.
              */
             uid?: string;
+            /**
+             * What a slicer on pivot tables filters.
+             *
+             * @internal
+             */
+            pivot?: ISlicer.PivotJSON;
+        }
+        /**
+         * A slicer on pivot tables: the field and the pivot tables it filters. A slicer on worksheet pivot
+         * tables takes its items and their states from the field; a data-model slicer's and a timeline's
+         * are carried as read.
+         *
+         * @internal
+         */
+        interface PivotJSON {
+            /** The field the slicer filters, by its name in the cache: `Region`, or `[Table1].[Region]` for a data model. */
+            sourceName: string;
+            /** The pivot tables the slicer filters, by sheet and name. Empty once they are deleted. */
+            tables: {
+                sheet: string;
+                name: string;
+            }[];
+            /**
+             * The workbook pivot cache the slicer's items index: its first pivot table's, kept once they are
+             * deleted. Absent for a data-model slicer.
+             */
+            cacheId?: number;
+            /**
+             * Present for a slicer or timeline on worksheet pivot tables the model holds, whose items and
+             * selection, or state, are the field's: what a slicer cache's `tabular` says beyond the slicer's
+             * sort order and cross filter.
+             */
+            tabular?: {
+                /** Whether items the source no longer holds are left out. */
+                hideMissing?: true;
+            };
+            /**
+             * The cache's children after its pivot tables, verbatim: for a {@link tabular} slicer what
+             * follows `<data>`, for a {@link tabular} timeline what follows `<state>`, else all of them.
+             */
+            body: string;
+            /**
+             * Present for a timeline, which Excel keeps as a slicer whose items are dates: the timeline's
+             * attributes beyond its name, cache and caption (level, scroll position, style, ...) and its
+             * children, as read. Its cache's `body` is then the `<state>` and what follows.
+             */
+            timeline?: {
+                attributes: Record<string, string>;
+                body: string;
+            };
         }
     }
 
@@ -36581,15 +38445,14 @@ declare global {
          */
         getRangedStyle(): IProperties.ICellRanged<ICellStyle.Properties>;
         /**
-         * Returns a cell style for the given coords.
-         * @param coords The absolute coords.
+         * Returns the style the table gives the cell at a sheet position.
+         * @param row The row on the sheet.
+         * @param column The column on the sheet.
          *
          * @remarks
-         * This will return a CellStyle rendered with the table styling but not any other styling.
-         *
-         * * This is used by the preview.
+         * The table's styling only, not the cell's own formats or any other layer.
          */
-        getStyleAt(coords: IRange.CellCoords): ICellStyle;
+        getStyleAt(row: number, column: number): ICellStyle;
         /**
          * Specifies if totals are being shown for the table.
          */
@@ -37023,6 +38886,29 @@ declare global {
             readonly LastTotalCell: "lastTotalCell";
         };
         type ElementType = typeof ElementType[keyof typeof ElementType];
+        /**
+         * The elements only a pivot table style has, beside the {@link ElementType}s a pivot table also
+         * uses (all but `lastHeaderCell`, `firstTotalCell` and `lastTotalCell`). On a pivot table,
+         * `totalRow` is the grand total row and `lastColumn` the grand total column.
+         */
+        const PivotElementType: {
+            readonly FirstSubtotalColumn: "firstSubtotalColumn";
+            readonly SecondSubtotalColumn: "secondSubtotalColumn";
+            readonly ThirdSubtotalColumn: "thirdSubtotalColumn";
+            readonly FirstSubtotalRow: "firstSubtotalRow";
+            readonly SecondSubtotalRow: "secondSubtotalRow";
+            readonly ThirdSubtotalRow: "thirdSubtotalRow";
+            readonly BlankRow: "blankRow";
+            readonly FirstColumnSubheading: "firstColumnSubheading";
+            readonly SecondColumnSubheading: "secondColumnSubheading";
+            readonly ThirdColumnSubheading: "thirdColumnSubheading";
+            readonly FirstRowSubheading: "firstRowSubheading";
+            readonly SecondRowSubheading: "secondRowSubheading";
+            readonly ThirdRowSubheading: "thirdRowSubheading";
+            readonly PageFieldLabels: "pageFieldLabels";
+            readonly PageFieldValues: "pageFieldValues";
+        };
+        type PivotElementType = typeof PivotElementType[keyof typeof PivotElementType];
         /**
          * Extends {@link ICellStyle.Properties} to include a size.
          *
@@ -37060,6 +38946,11 @@ declare global {
          * * Last Header Cell
          * * First Total Cell
          * * Last Total Cell
+         *
+         * A pivot table style also has the {@link PivotElementType} elements, and is applied in its own
+         * order: whole table, page field labels and values, column then row stripes, first column,
+         * header row, first header cell, subtotal columns, blank row, subtotal rows, column
+         * subheadings, row subheadings, grand total column (`lastColumn`), grand total row (`totalRow`).
          */
         interface Properties {
             /**
@@ -37136,6 +39027,28 @@ declare global {
              * both the total and last column must be selected.
              */
             lastTotalCell?: ICellStyle.Properties;
+            /** A pivot table's first, second and third level of subtotal columns. */
+            firstSubtotalColumn?: ICellStyle.Properties;
+            secondSubtotalColumn?: ICellStyle.Properties;
+            thirdSubtotalColumn?: ICellStyle.Properties;
+            /** A pivot table's first, second and third level of subtotal rows. */
+            firstSubtotalRow?: ICellStyle.Properties;
+            secondSubtotalRow?: ICellStyle.Properties;
+            thirdSubtotalRow?: ICellStyle.Properties;
+            /** A pivot table's blank row after an item. */
+            blankRow?: ICellStyle.Properties;
+            /** A pivot table's column labels at the first, second and third level. */
+            firstColumnSubheading?: ICellStyle.Properties;
+            secondColumnSubheading?: ICellStyle.Properties;
+            thirdColumnSubheading?: ICellStyle.Properties;
+            /** A pivot table's items with items under them, at the first, second and third level. */
+            firstRowSubheading?: ICellStyle.Properties;
+            secondRowSubheading?: ICellStyle.Properties;
+            thirdRowSubheading?: ICellStyle.Properties;
+            /** A pivot table's page field captions. */
+            pageFieldLabels?: ICellStyle.Properties;
+            /** A pivot table's page field items. */
+            pageFieldValues?: ICellStyle.Properties;
         }
         type ResolvableProperties = IProperties.ResolvableProperties<ITableStyle.Properties>;
         interface JSON extends ITableStyle.Properties {
@@ -37148,40 +39061,6 @@ declare global {
             defaultPivotStyle?: string;
             styles?: Record<string, ITableStyle.JSON>;
         }
-        /**
-         * Properties for a pivot table style.
-         *
-         * @remarks
-         * **NOT IMPLEMENTED**
-         */
-        interface PivotProperties {
-            name?: string;
-            wholeTable?: ICellStyle.Properties;
-            firstColumnStripe?: ITableStyle.SizeBasedProperties;
-            secondColumnStripe?: ITableStyle.SizeBasedProperties;
-            firstRowStripe?: ITableStyle.SizeBasedProperties;
-            secondRowStripe?: ITableStyle.SizeBasedProperties;
-            firstColumn?: ICellStyle.Properties;
-            headerRow?: ICellStyle.Properties;
-            firstHeaderCell?: ICellStyle.Properties;
-            pageFieldLabels?: ICellStyle.Properties;
-            pageFieldValues?: ICellStyle.Properties;
-            subtotalColumn1?: ICellStyle.Properties;
-            subtotalColumn2?: ICellStyle.Properties;
-            subtotalColumn3?: ICellStyle.Properties;
-            blankRow?: ICellStyle.Properties;
-            subtotalRow1?: ICellStyle.Properties;
-            subtotalRow2?: ICellStyle.Properties;
-            subtotalRow3?: ICellStyle.Properties;
-            columnSubheading1?: ICellStyle.Properties;
-            columnSubheading2?: ICellStyle.Properties;
-            columnSubheading3?: ICellStyle.Properties;
-            rowSubheading1?: ICellStyle.Properties;
-            rowSubheading2?: ICellStyle.Properties;
-            rowSubheading3?: ICellStyle.Properties;
-            grandTotalColumn?: ICellStyle.Properties;
-            grandTotalRow?: ICellStyle.Properties;
-        }
     }
 
     /**
@@ -38825,6 +40704,66 @@ declare global {
         type BuiltInFilterType = typeof BuiltInFilterType[keyof typeof BuiltInFilterType];
     }
 
+    /**
+     * A timeline: a slicer on a date field of pivot tables, whose selection is a range of dates.
+     *
+     * @remarks
+     * A timeline holds no selection of its own. What it selects is the field's date filter, the same on
+     * every pivot table it filters, so a date filter set on the field shows on the timeline, and a range
+     * set on the timeline is the field's date filter. While a timeline is on the field, that filter
+     * filters the tables whether or not the field is on an axis.
+     *
+     * It has no items: {@link ISlicer.getItems} answers none, and {@link ISlicer.clearFilters} clears the
+     * range.
+     *
+     * @example
+     * ```ts
+     * const content = movable.getContent<ISlicer>();
+     * if ((content as ITimeline).isITimeline) {
+     *   await (content as ITimeline).setDateRange({ start: 45689, end: 45747 });
+     * }
+     * ```
+     */
+    export interface ITimeline extends ISlicer {
+        /**
+         * Returns the dates selected, or `null` when every date is, or the field's date filter is not a
+         * range of dates.
+         */
+        getDateRange(): ITimeline.DateRange | null;
+        /**
+         * Selects a range of dates on every pivot table, as one step that can be undone.
+         *
+         * @param range The dates, or `null` to select every date.
+         *
+         * @remarks
+         * The range replaces the field's label or date filter; its value filter and the items it hides
+         * stay.
+         */
+        setDateRange(range: ITimeline.DateRange | null, options?: ITransaction.OperationOptions): Promise<this>;
+        /** For runtime type checking. */
+        readonly isITimeline: true;
+    }
+
+    /**
+     * {@inheritDoc ITimeline}
+     *
+     * @see
+     * ### **Interface**
+     *
+     * {@link ITimeline}
+     */
+    export namespace ITimeline {
+        /**
+         * A range of whole days, as date serial numbers.
+         */
+        interface DateRange {
+            /** The first day selected. */
+            start: number;
+            /** The last day selected. */
+            end: number;
+        }
+    }
+
     /**
      * Objects that implement this interface have ACID properties.
      */
@@ -39717,8 +41656,12 @@ declare global {
          * `fixed + error` is not a state: a fixed block owns its cells, so a write into part of it is
          * refused at the write site rather than detected at calc. That is what lets these three be one
          * enum rather than two booleans.
+         *
+         * A fourth kind is the calculation engine's alone: `pivot`, the cells a pivot table lays out. It
+         * is never saved, and a cell never reports it ({@link ICell.getSpillKind}): a pivot table's
+         * cells are the table's, not an array's. A blocked pivot table is `error`.
          */
-        type FormulaArrayKind = 'dynamic' | 'fixed' | 'error';
+        type FormulaArrayKind = 'dynamic' | 'fixed' | 'error' | 'pivot';
         /**
          * Options for controlling selection behavior, including scrolling and focus.
          */
@@ -40720,13 +42663,19 @@ declare global {
              * Absent when the source said nothing, which Excel reads as `userSet`.
              */
             updateLinks?: IExternalBookCollection.UpdateLinks;
+            /**
+             * The PivotTable Fields pane does not open when a pivot table is selected; absent, it does.
+             *
+             * @remarks
+             * Carried, not obeyed: SheetXL has no fields pane yet. Round-trips as `workbookPr@hidePivotFieldList`.
+             */
+            hiddenPivotFieldList?: true;
             /**
              * The workbook's pivot caches — the source snapshots its pivot tables summarize, each shared
              * by every table that references its id.
              *
              * @remarks
-             * Carried, not modeled — see {@link IPivotTable.CacheJSON}. The tables that summarize a cache
-             * are the modeled side; a table names its cache by {@link IPivotTable.getCacheId}.
+             * See {@link IPivotTable.CacheJSON}. A table names its cache by {@link IPivotTable.getCacheId}.
              */
             pivotCaches?: IPivotTable.CacheJSON[];
             /**
@@ -43150,6 +45099,14 @@ declare global {
          * own sheet).
          */
         getCalculation(): ICalculation;
+        /**
+         * Returns the {@link IFontCollection} the sheet measures text with.
+         *
+         * @remarks
+         * Fonts are shared: every sheet, with or without a workbook, returns the same collection, so a
+         * face loaded for one is loaded for all.
+         */
+        getFonts(): IFontCollection;
         /**
          * Recalculates THIS sheet — Excel's "Calculate Sheet" (Shift+F9) / `Worksheet.Calculate`.
          *
@@ -43186,6 +45143,25 @@ declare global {
          *   it has not been started.
          */
         whenCalculationReady(): Promise<ICalculation.Status>;
+        /**
+         * Returns when every font the sheet measures with has loaded and every autofit that was taken
+         * with a stand-in meanwhile has been taken again.
+         *
+         * @remarks
+         * Measuring never waits: a style naming a face not yet loaded measures with a related or
+         * built-in one and the lookup starts the load, the way a browser paints with a fallback until
+         * a web font arrives. This is the point after which sizes are final. Fonts are shared, so this
+         * also waits for faces other sheets and workbooks started loading; a load that fails leaves its
+         * stand-in and still settles.
+         *
+         * The same point as {@link IWorkbook.whenFontsReady}; a sheet without a workbook has it here.
+         */
+        whenFontsReady(): Promise<void>;
+        /**
+         * Returns when the sheet is settled: {@link whenCalculationReady} and {@link whenFontsReady}
+         * both hold.
+         */
+        whenReady(): Promise<void>;
         /**
          * Returns the {@link IWorkbook} for the sheet.
          *
@@ -43525,6 +45501,13 @@ declare global {
              * Called when any table are added or removed.
              */
             onTablesChange?(source: IWorksheet): void;
+            /**
+             * Called when a pivot table changes: its style, its layout, or where it sits.
+             *
+             * @remarks
+             * Always accompanied by the coarse {@link onStyleChange}.
+             */
+            onPivotTablesChange?(source: IWorksheet): void;
             /**
              * Called when any data validation is added, removed, re-anchored, or re-evaluates its results.
              *
@@ -45354,6 +47337,21 @@ declare global {
         getKeyFrom(): string;
         getBuildVersion(): string;
         getBuildDate(): string;
+        /**
+         * When this build's evaluation period ends — from then on, unlicensed, it refuses exports — or
+         * `null` for an unstamped build.
+         */
+        getEvalPeriodEnd(): Date | null;
+        /**
+         * When this build's grace ends — from then on, unlicensed, it stops calculating and running
+         * scripts — or `null` for an unstamped build.
+         */
+        getEvalStopDate(): Date | null;
+        /**
+         * The license as one report row — what `info` and `sheetxl info` print. `includeHost` adds where
+         * the key came from and its capacity, for a human diagnosing a machine.
+         */
+        getSummary(includeHost?: boolean): LicenseSummary;
     }
 
     /**
@@ -45363,6 +47361,19 @@ declare global {
      */
     export const LicenseManager: LM;
 
+    /**
+     * @hidden
+     *
+     * A license as one report row: how it stands, the edition, what qualifies it, and the exact command
+     * that resolves a `warn`.
+     */
+    export interface LicenseSummary {
+        level: 'ok' | 'warn';
+        value: string;
+        detail?: string;
+        fix?: string;
+    }
+
     /**
      * Rotated cell-text layout (the Excel model).
      *
@@ -45439,16 +47450,31 @@ declare global {
          */
         getDetails(): Promise<LicenseDetails>;
         /**
-         * Return the current license details, after confirming this runtime may run under them.
+         * Return the current license details, after confirming this runtime may use `meter` under them.
+         *
+         * @param meter What is about to be used: `'calcs'`, `'exports'` (a write in any format but
+         * `.sxl`) or `'scripts'`. Omitted, it asks whether this runtime may run at all.
+         * @param count How much of it — what a metered license will count against its limit.
          *
          * @remarks
-         * {@link getDetails} only reports. This also enforces: in a browser it always resolves, because
-         * an unlicensed page runs with the evaluation watermark. Outside a browser an evaluation runs
-         * for a limited period from the build's date; past it a valid license key is required, and this
-         * rejects with the reason and what to do. The engine calls it when it starts, so a host that
-         * wants to fail at startup instead of at the first workbook calls it itself.
+         * {@link getDetails} only reports. This also enforces: on a web page it always resolves, because
+         * an unlicensed page runs with the evaluation watermark. Anywhere else an unlicensed build runs
+         * for an evaluation period from its build date; after it `'exports'` are refused, and after its
+         * grace everything metered is. The rejection carries the reason and what to do. Opening a
+         * workbook and saving it as `.sxl` are never refused. The engine calls this when it starts, so a
+         * host that wants to fail at startup instead of at the first workbook calls it itself.
+         */
+        assertUsable(meter?: string, count?: number): Promise<LicenseDetails>;
+        /**
+         * Where this runtime stands under its license: `licensed`, in its `evaluation`, in the `grace`
+         * that refuses exports, or `stopped` (no calculation, scripts or exports).
+         */
+        getEvalState(): Promise<EvalState>;
+        /**
+         * Whether this runtime runs under the evaluation watermark: an unlicensed web page off localhost.
+         * An xlsx exported from it carries the watermark as a sheet added before the workbook's own.
          */
-        assertUsable(): Promise<LicenseDetails>;
+        isWatermarked(): Promise<boolean>;
         /**
          * Return the license key in use, or `null` for an evaluation.
          *
@@ -46666,6 +48692,96 @@ declare global {
         outerRadius: number;
     }
 
+    /**
+     * The expand/collapse box of a pivot label `cell`, in px at 100% from its left edge; `null` for a
+     * cell that keeps no box gutter.
+     * @internal
+     */
+    export const pivotBoxOf: (cell: ICell) => {
+        left: number;
+        size: number;
+    } | null;
+
+    /** What a laid-out table's definition writes into its cells' formats ({@link pivotCellFormatsOf}). */
+    export interface PivotCellFormats {
+        /** How many rows and columns it lays out, from the top-left cell of its page fields and location. */
+        readonly rows: number;
+        readonly columns: number;
+        /** How many rows sit above its location: the page rows and the gap. */
+        readonly top: number;
+        /** It has no fields: its cells hold nothing, and every one has a format, its box's. */
+        readonly empty: boolean;
+        /**
+         * The number format of the cell (`undefined` for General), the indent it is set left by (`null`
+         * when it is not), and the style the table's own formats give it (`null` for none), which wins
+         * over the other two: those a user put on the table, or an empty table's box.
+         */
+        formatAt(row: number, column: number): {
+            numberFormat: string | number | undefined;
+            labelIndent: number | null;
+            user: ICellStyle.Properties | null;
+        };
+    }
+
+    /**
+     * The formats a table's definition explains in its cells, as Excel writes them into each cell's
+     * xf: its number formats ({@link pivotNumberFormatAt}), its row labels' alignment
+     * ({@link pivotRowLabelIndentAt}), its user formats ({@link pivotUserFormatAt}) and, while it is
+     * empty, its box ({@link pivotEmptyBoxAt}). `null` for a table that is not laid out.
+     * @internal
+     */
+    export const pivotCellFormatsOf: (table: IPivotTable.JSON, cacheFields?: readonly {
+        numberFormat?: string | number;
+    }[]) => PivotCellFormats | null;
+
+    /**
+     * A control on a cell of a laid-out table, by row and column from the top-left cell of its page
+     * fields and location:
+     * - `dropdown`: a field button, for the fields it lists (more than one on a compact header);
+     * - `toggle`: an item's expand/collapse box; `item` by index into the field's items, `name` its
+     *   caption where the table has said it.
+     */
+    export type PivotControl = {
+        readonly kind: 'dropdown';
+        readonly row: number;
+        readonly column: number;
+        readonly fields: readonly number[];
+    } | {
+        readonly kind: 'toggle';
+        readonly row: number;
+        readonly column: number;
+        readonly field: number;
+        readonly item: number;
+        readonly expanded: boolean;
+        readonly name?: string;
+    };
+
+    /**
+     * The field dropdowns and expand/collapse boxes of `table` within `coords`, at sheet cells; empty
+     * for a table that is not placed.
+     * @internal
+     */
+    export const pivotControlsIn: (table: IPivotTable, coords: IRange.Coords) => PivotControl[];
+
+    /** A pivot table style over a small schematic table, cell by cell, for a gallery swatch. */
+    export interface PivotStylePreview {
+        readonly rows: number;
+        readonly columns: number;
+        /** The style a cell shows, from the preview's top-left. */
+        getStyleAt(row: number, column: number): ICellStyle;
+    }
+
+    /**
+     * `style` over Excel's gallery swatch, with no sheet and no WebAssembly; `null` is the gallery's
+     * None, a table with no style.
+     *
+     * @param options Which parts of the style show; absent, those Excel gives a new table.
+     * @param rows How many rows the swatch has, at least 3; 5 by default, as Excel online's. Excel
+     * desktop's has 8.
+     * @internal
+     */
+    export const pivotStylePreviewOf: (styles: IStyleCollection, style: ITableStyle | null, options?: IPivotTable.PivotStyleJSON, rows?: number) => PivotStylePreview;
+
     /**
      * Represents a point in 2D space.
      */