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

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

@@ -0,0 +1,48 @@
+import { ICellStyle } from '../style';
+import { IPivotTable } from './IPivotTable';
+import { PivotStructure } from './_PivotStructure';
+/**
+ * Whether `area` covers the cell at `row`, `column` of a laid-out table.
+ *
+ * @remarks
+ * By cell kind, as Excel records them: `all` is every cell, page fields included; `origin` and
+ * `topRight` the header cells left and right of the column fields' captions; `button` a field's
+ * caption on its axis. A `normal` area takes values (`dataOnly`, the default), labels
+ * (`labelOnly`) or both (`dataOnly="0"`). A label is the one whose field is the last selected
+ * reference's, under the items every reference names; a value is the crossing of the row line and
+ * the column line its references name, an axis no reference names taking every line, and
+ * `grandRow`/`grandCol` the grand totals'. A reference by position or relative to the cell, and the
+ * `data`, `topEnd` and `none` kinds, cover nothing (not probed).
+ *
+ * @param row From the top-left cell of the page fields and location.
+ */
+export declare const pivotAreaCovers: (structure: PivotStructure, table: IPivotTable.JSON, area: IPivotTable.PivotAreaJSON, row: number, column: number) => boolean;
+/**
+ * The areas Excel records for a format set on some cells of a laid-out table: one per kind of
+ * cell among them, in the order first met, so each covers those cells and follows them through a
+ * relayout (`pivot-probes/probe-pivot-format-areas.ps1`).
+ *
+ * @remarks
+ * Every cell of the location is `all`. Otherwise a caption is its `button`, and the header cells
+ * around the captions `origin` and `topRight`. Labels of one field are one area, referencing the
+ * items down their path (the outer ones not selected); a value is the crossing of its row and
+ * column paths. Where the cells of an area differ in an item, it takes all of the field's items;
+ * where their lines differ in depth or one is a grand total, the area names no line of that axis
+ * (a row of values runs on into the grand total column). Not probed: whether two of three items
+ * widen to all three, and a subtotal's caption (`defaultSubtotal` on its reference).
+ *
+ * @param cells From the top-left cell of the page fields and location.
+ */
+export declare const pivotAreasOf: (structure: PivotStructure, table: IPivotTable.JSON, cells: readonly {
+    readonly row: number;
+    readonly column: number;
+}[]) => IPivotTable.PivotAreaJSON[];
+/**
+ * The style a table's user formats ({@link IPivotTable.JSON.formats}) give the cell at `row`,
+ * `column`: each format whose area covers it, merged in order, a later one winning. `null` when none
+ * covers it.
+ *
+ * @param row From the top-left cell of the page fields and location.
+ */
+export declare const pivotUserFormatAt: (structure: PivotStructure, table: IPivotTable.JSON, row: number, column: number) => ICellStyle.Properties | null;
+//# sourceMappingURL=_PivotAreas.d.ts.map

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

@@ -0,0 +1,140 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { ICellStyle } from '../style';
+import { ICell } from '../cell';
+import { IPivotTable } from './IPivotTable';
+import { PivotStructure } from './_PivotStructure';
+/** What the controls read of a table's definition. */
+export type PivotControlsDefinition = Pick<IPivotTable.JSON, 'fields' | 'indent' | 'hiddenDrillIndicators'>;
+/**
+ * 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;
+};
+/**
+ * How a label cell's text is set in: at its `level`, each level `step` characters of indent in the
+ * cells' formats (`indent`, the two multiplied, is what Excel writes there), after a box's gutter
+ * or not.
+ */
+export interface PivotLabelInset {
+    readonly level: number;
+    readonly step: number;
+    readonly indent: number;
+    readonly gutter: boolean;
+}
+/**
+ * The field dropdowns of a laid-out table.
+ */
+export declare const pivotDropdownsOf: (structure: PivotStructure) => PivotControl[];
+/**
+ * The expand/collapse boxes of a laid-out table within `window`, rows and columns from its
+ * top-left cell; only the lines in the window are walked.
+ */
+export declare const pivotTogglesIn: (definition: PivotControlsDefinition, structure: PivotStructure, window: IRange.Coords) => PivotControl[];
+/**
+ * How the label at `row`, `column` from the table's top-left is set in, or `null` for a cell that
+ * is not a label or a total's caption.
+ */
+export declare const pivotLabelInsetAt: (definition: PivotControlsDefinition, structure: PivotStructure, row: number, column: number) => PivotLabelInset | null;
+/**
+ * The indent, in characters, Excel stores set left in the format of a cell from the table's
+ * top-left, or `null` for a cell it leaves alone. Measured on Excel's own files: in a table of the
+ * compact form, every line of each label column, a tabular field's too, its labels and totals at
+ * their level's indent and its blank lines at none; nothing in a table of the outline or tabular
+ * form, nor in the header rows. A page field's selected item at none when it is a number, a date
+ * among them; a text item and `(All)` are left alone (`probe-pivot-page-item-xf.ps1`).
+ *
+ * @param value The cell's value, for a page field's item; not given, a selected item counts as a
+ * number, as the reader asks it of a saved left alignment.
+ * @internal
+ */
+export declare const pivotRowLabelIndentAt: (definition: PivotControlsDefinition, structure: PivotStructure, row: number, column: number, value?: Scalar) => 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 declare const pivotCellFormatsOf: (table: IPivotTable.JSON, cacheFields?: readonly {
+    numberFormat?: string | number;
+}[]) => PivotCellFormats | null;
+/**
+ * The field dropdowns and expand/collapse boxes of `table` within `coords`, at sheet cells; empty
+ * for a table that is not placed.
+ * @internal
+ */
+export declare const pivotControlsIn: (table: IPivotTable, coords: IRange.Coords) => PivotControl[];
+/** Where a label's box and text sit, in px at 100% from the cell's left edge. */
+export interface PivotLabelLayout {
+    /** The expand/collapse box's left edge and its side; `size` is `0` for a label with no gutter. */
+    readonly boxLeft: number;
+    readonly boxSize: number;
+    /** Where the text starts: the label's whole leading inset. */
+    readonly textLeft: number;
+}
+/**
+ * How a label of `style` is laid out, as Excel's window draws it
+ * (`pivot-probes/probe-pivot-label-geometry.ps1`, under Aptos Narrow 11, Calibri 11 and Arial 16
+ * Normal fonts, cells from 8 to 36 pt, 11-04). With `pad` the cell's own leading padding:
+ * - the box is a square of the Normal font, not the cell's: 9 px under an 11 pt Normal at every cell
+ *   size, odd so the `+` and `−` sit on a center pixel;
+ * - it starts two pads in and the text one pad after it, `[pad pad][box][pad][text]`;
+ * - each level moves both by the table's indent in Normal's indent units ({@link indentUnit}), but
+ *   never by less than a unit and two of Normal's pads: an indent of 1 steps 13 px under an 11 pt
+ *   Normal where an indented cell steps 9.
+ * A label without a gutter (a total's caption) starts one pad in, at its level's step.
+ *
+ * The indent moved by is the style's: the level's own (level × the table's indent), or one a user
+ * set, which the table holds as a format and which wins. Each of its units is that step over the
+ * table's indent below the first level, and Normal's indent unit at it: by hand, 2 on a first-level
+ * label is 18 px, 4 on a second-level one 52 px, under an 11 pt Normal and the table's indent 1
+ * (`probe-pivot-label-geometry.ps1`, `hand11`, `hand11b`, `hand2`).
+ * @internal
+ */
+export declare const pivotLabelLayoutOf: (style: ICellStyle, label: PivotLabelInset) => PivotLabelLayout;
+/**
+ * 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 declare const pivotBoxOf: (cell: ICell) => {
+    left: number;
+    size: number;
+} | null;
+//# sourceMappingURL=_PivotControls.d.ts.map

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

@@ -0,0 +1,9 @@
+/** The lazy pivot code's module (`./engine`). */
+export type PivotEngineModule = typeof import('./engine');
+/**
+ * The one loader of the pivot code that is not the opaque model: a workbook that only carries
+ * its pivot tables through never loads it.
+ * @internal
+ */
+export declare const PivotEngine: import('@sheetxl/utils').LazyModule<typeof import("./engine")>;
+//# sourceMappingURL=_PivotEngine.d.ts.map

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

@@ -0,0 +1,25 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IPivotTable } from './IPivotTable';
+/**
+ * Per field, its records' item ids, a grouped field's being its groups.
+ *
+ * @returns `null` when a record's value cannot fall in its range: a file's, since a refresh ungroups
+ * such a field.
+ */
+export declare const recordColumnsOf: (cache: IPivotTable.CacheJSON, date1904: boolean) => number[][] | null;
+/**
+ * A range grouping after a refresh: its bounds follow the values unless fixed, and its groups are
+ * made anew from them.
+ *
+ * @param values The values the field holds now.
+ * @returns The group, or `null` when a value is not a number, which ungroups the field.
+ */
+export declare const regroupRange: (group: IPivotTable.CacheFieldGroupJSON, values: readonly Scalar[], date1904: boolean) => IPivotTable.CacheFieldGroupJSON | null;
+/**
+ * How the items of a range grouping carry over a refresh: the first and last by place, since their
+ * captions name the bounds, the others by caption.
+ *
+ * @returns Per old item, its new index; -1 when no group has it any more.
+ */
+export declare const remapRangeItems: (oldItems: readonly Scalar.JSON[], newItems: readonly Scalar.JSON[]) => number[];
+//# sourceMappingURL=_PivotGroups.d.ts.map

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

@@ -0,0 +1,167 @@
+import { Scalar } from '@sheetxl/primitives';
+import { Tuple } from '../collections';
+import { IPivotTable } from './IPivotTable';
+/** What the item edits read of a table's definition. */
+export type PivotDefinition = Pick<IPivotTable.JSON, 'fields' | 'rowFields' | 'columnFields' | 'pageFields'>;
+/** A table's definition without what names and places it: what the engine's edits take and give back. */
+export type PivotModel = Omit<IPivotTable.JSON, 'name' | 'cacheId' | 'location' | 'part' | 'partFormats' | 'buttons'>;
+/** The caption Excel shows for the blank item. */
+export declare const BlankText = "(blank)";
+/** Per field, its values from tuples keyed by field index. */
+export declare const cacheColumns: <T>(tuples: Tuple.GridTuple<T> | undefined, count: number) => T[][];
+/** Whether a cache field groups values, so a table lists its groups rather than its cache items. */
+export declare const isGrouping: (field: Pick<IPivotTable.CacheFieldJSON, "group"> | undefined) => boolean;
+/** A field's listed items with the lines of its subtotals last, as the file lists them. */
+export declare const withSubtotalItems: (items: readonly IPivotTable.PivotItemJSON[], subtotals: readonly IPivotTable.PivotSubtotal[] | undefined) => IPivotTable.PivotItemJSON[];
+/** The slots of an axis, outermost first: the fields by index, with `-2` where the values sit. */
+export declare const fieldSlotsOf: (table: Pick<IPivotTable.JSON, "rowFields" | "columnFields" | "pageFields">, axis: IPivotTable.Axis) => readonly number[];
+/** Whether a cache field is a calculated field: its values are a formula's. */
+export declare const isCalculatedField: (field: IPivotTable.CacheFieldJSON | undefined) => boolean;
+/** Whether a table shows what only the calc engine can evaluate: a calculated field or item. */
+export declare const hasFormulas: (table: Pick<IPivotTable.JSON, "dataFields">, fields: readonly IPivotTable.CacheFieldJSON[] | undefined) => boolean;
+/**
+ * Whether a table has work to do before it can be laid out, which is async: filters to evaluate, or
+ * formulas. What it finds is held on the table and every layout reads it.
+ */
+export declare const needsPrepare: (table: Pick<IPivotTable.JSON, "filters" | "dataFields">, fields: readonly IPivotTable.CacheFieldJSON[] | undefined) => boolean;
+/** Per field, the items a table lists for it, by item index: a grouping field's groups, else its cache items. */
+export declare const itemColumnsOf: (cache: IPivotTable.CacheJSON) => Scalar.JSON[][];
+/** The number format of a date among plain numbers, when the field names none: the short date. */
+export declare const DateItemFormat = 14;
+/** What says which of a field's items are dates when others are not. */
+type DateItemsField = Pick<IPivotTable.CacheFieldJSON, 'group'> & {
+    readonly dateItems?: readonly number[];
+};
+/** The items of a field that are dates among others: a grouping field's groups, else its cache items. */
+export declare const dateItemsOf: (field: DateItemsField | undefined) => readonly number[] | undefined;
+/** Whether an item of a field holding dates among other kinds is a date. */
+export declare const isDateItem: (field: DateItemsField | undefined, item: number | undefined) => boolean;
+/**
+ * The number format a date item shows with when its field names none. A group's item holds its value
+ * here, so its time shows (`pivot-probes/probe-pivot-discrete-group-kinds.ps1`, K05).
+ */
+export declare const dateItemFormatOf: (field: DateItemsField | undefined, item: number | undefined) => number;
+/** A cache item as a value. */
+export declare const scalarOf: (item: Scalar.JSON | undefined) => Scalar;
+/**
+ * What a field holds, from its items ({@link IPivotTable.IField.getDataType}): a calculated field is
+ * numbers, and a field whose numbers are dates is dates. Blanks are no kind.
+ */
+export declare const dataTypeOf: (field: IPivotTable.CacheFieldJSON | undefined, items: readonly Scalar.JSON[]) => IPivotTable.IField.DataType;
+/** A value as the text it is typed as. */
+export declare const textOf: (value: Scalar) => string;
+/** Whether a filter tests an item itself (a label or date filter) rather than its total of a data field. */
+export declare const isItemFilter: (filter: IPivotTable.PivotFilterJSON) => boolean;
+/** A kind of pivot filter: Excel's label, date, or value (top N among them). */
+export type PivotFilterKind = 'label' | 'date' | 'value';
+/** A filter's kind: a value filter names a data field; a label filter tests the caption (Display-shaped); any other tests the date. */
+export declare const filterKindOf: (filter: IPivotTable.PivotFilterJSON) => PivotFilterKind;
+/**
+ * A table with a field's filters of the kinds `drop` picks removed and `added` appended after the
+ * table's others, each with an id no other filter has.
+ *
+ * @returns `table` itself when nothing changes.
+ */
+export declare const withFieldFilters: <T extends Pick<IPivotTable.JSON, "filters">>(table: T, field: number, drop: (kind: PivotFilterKind) => boolean, added?: readonly IPivotTable.PivotFilterJSON[]) => T;
+/** Excel matches pivot field and item names without regard to case. */
+export declare const isSameText: (a: string, b: string) => boolean;
+/** A field's caption: its own name, else its cache field's. */
+export declare const fieldCaptionOf: (table: PivotDefinition, cache: IPivotTable.CacheJSON, field: number) => string;
+/** Whether a listed entry is an item of the cache rather than a subtotal or grand-total line. */
+export declare const isCacheItem: (item: IPivotTable.PivotItemJSON) => boolean;
+/** Where a field's subtotal lines start in its listed items, or their end. */
+export declare const firstLineIndex: (items: readonly IPivotTable.PivotItemJSON[]) => number;
+/**
+ * What a sort by label compares for a listed item: its caption when it has one, else its value, as
+ * Excel sorts a renamed item by its caption (`pivot-probes/probe-pivot-items.ps1`, I05c).
+ */
+export declare const sortKeyOf: (item: IPivotTable.PivotItemJSON, values: readonly Scalar.JSON[]) => Scalar;
+/**
+ * The captions of a field's items as the table lists them, by index into
+ * {@link IPivotTable.PivotFieldJSON.items}; `null` where an entry is not an item.
+ */
+export declare const itemCaptionsOf: (table: PivotDefinition, cache: IPivotTable.CacheJSON, field: number) => (string | null)[];
+/** Whether a field's items have details to show or hide: a row or column field. */
+export declare const isExpandable: (table: PivotDefinition, field: number) => boolean;
+/** Whether a field is a row or column field with another field inside it. */
+export declare const hasInnerField: (table: PivotDefinition, field: number) => boolean;
+/**
+ * A table with a row or column field's items expanded or collapsed: every item, or the one at
+ * `rank`. Excel takes an item of the innermost field (it changes nothing shown), but not the
+ * innermost field as a whole (`pivot-probes/probe-pivot-item-api.ps1`).
+ *
+ * @returns The table as edited, or `table` itself when nothing changes.
+ * @throws ExpectedError where Excel refuses it.
+ */
+export declare const withExpanded: <T extends PivotDefinition>(table: T, field: number, expanded: boolean, rank?: number) => T;
+/**
+ * A table showing only the items at `ranks` of a field, or every item for `null`. On a page field
+ * the items shown are its selection: more than one item turns on multiple selection, and the
+ * single item chosen is dropped.
+ *
+ * @returns The table as edited, or `table` itself when nothing changes.
+ * @throws ExpectedError when no item would show, as Excel refuses hiding the last one.
+ */
+export declare const withVisibleItems: <T extends PivotDefinition>(table: T, field: number, ranks: ReadonlySet<number> | null) => T;
+/**
+ * A table showing only the cache items `shown` of a field, or every item for `null`: what a slicer's
+ * selection is on each table it filters, the field on an axis or not
+ * (`pivot-probes/probe-pivot-slicer-edits.ps1`, E11, E12). A field the table lists no items for lists
+ * `listed()` first, as Excel does for a slicer's field (`probe-pivot-slicer-caption.ps1`, C07).
+ *
+ * @returns The table as edited, or `table` itself when nothing changes.
+ */
+export declare const withShownItems: <T extends PivotDefinition>(table: T, field: number, listed: () => IPivotTable.PivotItemJSON[], shown: ReadonlySet<number> | null) => T;
+/**
+ * `table` with each field of `fields` that is on no axis and hides an item or has a filter added as
+ * a page field showing what it does not hide or filter out: the records a layout and the filters
+ * keep. Items hidden and filters on a field off the axes filter nothing (M03, M29) unless a slicer
+ * or a timeline on the table filters that field, and then they filter it
+ * (`pivot-probes/probe-pivot-slicer-offaxis.ps1`, O01-O04; `probe-pivot-timeline-edits.ps1`, T02,
+ * T12). Never a table to show or save: its added page fields have no cells.
+ *
+ * @param fields The fields the table's slicers and timelines filter.
+ * @returns `table` itself when nothing is added.
+ */
+export declare const withSlicerPages: <T extends PivotDefinition & Pick<IPivotTable.JSON, "filters">>(table: T, fields: readonly number[] | undefined) => T;
+/**
+ * A page field {@link withSlicerPages} adds: it also keeps what the field's label or date filter
+ * keeps, which a page field's does not.
+ */
+export type SlicerPageJSON = IPivotTable.PageFieldJSON & {
+    slicer?: true;
+};
+/**
+ * A table whose page field shows the item at `rank`, or every item for `null`: a single
+ * selection, so the field's hidden items and multiple selection are cleared.
+ *
+ * @returns The table as edited, or `table` itself when nothing changes.
+ * @throws ExpectedError when the field is not a page field.
+ */
+export declare const withCurrentPage: <T extends PivotDefinition>(table: T, field: number, rank: number | null) => T;
+/** How the API names the item before or after each item, as a base item: no item's caption, as Excel's are not. */
+export declare const BaseItemPrevious = "(previous)";
+export declare const BaseItemNext = "(next)";
+/** A data field's number format as a code, or a format's. */
+export declare const formatCodeOfData: (format: string | number | undefined) => string;
+/** A data field's rule as the API reads it; `null` shown as is. */
+export declare const showAsOf: (table: Pick<IPivotTable.JSON, "fields" | "dataFields">, cache: IPivotTable.CacheJSON, data: number) => IPivotTable.IDataField.ShowAs | null;
+/** How a value's caption starts, by the function as OOXML spells it. */
+export declare const CaptionPrefixes: Readonly<Record<string, string>>;
+/**
+ * `caption`, numbered from 2 when a field, another data field or the values have it: one namespace, by
+ * what they are called now, so a field's old name is free (D01, D03, D21, D24).
+ *
+ * @param except The data field the caption is for, which does not clash with itself.
+ */
+export declare const freeCaption: (table: Pick<IPivotTable.JSON, "fields" | "dataFields" | "valuesCaption">, cache: IPivotTable.CacheJSON, caption: string, except?: number) => string;
+/**
+ * The caption a data field takes with the function `fn`: what comes before its first ` of ` takes the
+ * function's name, a caption without one becomes the default, and a caption taken is numbered (D04, D05,
+ * D20, D21, D30). Its own when `fn` is its function already.
+ *
+ * @throws ExpectedError for a function that is none.
+ */
+export declare const dataCaptionFor: (table: Pick<IPivotTable.JSON, "fields" | "dataFields" | "valuesCaption">, cache: IPivotTable.CacheJSON, data: number, fn: string) => string;
+export {};
+//# sourceMappingURL=_PivotItems.d.ts.map

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

@@ -0,0 +1,237 @@
+import { IRange, IRuntime } from '@sheetxl/primitives';
+import { ICellStyle } from '../style';
+import { IPivotTable } from './IPivotTable';
+/** A row or column slot: a field of the cache, or where the values sit ({@link ValuesField}). */
+export interface PivotSlot {
+    readonly field: number;
+    /** Its labels each take a column (outline, tabular) rather than sharing the next field's (compact). */
+    readonly ownColumn: boolean;
+    /** Tabular: an item's label beside its first child, rather than on a line of its own. */
+    readonly tabular: boolean;
+    /** Its label is written on every line, the repeated ones too. */
+    readonly repeatLabels: boolean;
+}
+/** A line of an axis, as the saved layout spells it with its items written out. */
+export interface PivotLineBand {
+    readonly kind: 'item' | 'subtotal' | 'grand' | 'blank';
+    /** Its position among the axis's lines, for stripes. */
+    readonly index: number;
+    /** The item at each slot, outermost first; empty for the grand total. */
+    readonly path: readonly number[];
+    /** How many leading items it shares with the item line before it, which it does not label. */
+    readonly repeat: number;
+    /** The data field it names; `null` when it names none. */
+    readonly data: number | null;
+}
+/**
+ * What a row or a column of a laid-out table is:
+ * - `page`: a row of the page fields (rows only);
+ * - `gap`: the blank row between the page fields and the location, not the table's (rows only);
+ * - `header`: a header row above the data, or a label column left of it, by `index`;
+ * - a line of the axis.
+ */
+export type PivotBand = {
+    readonly kind: 'page';
+    readonly index: number;
+} | {
+    readonly kind: 'gap';
+} | {
+    readonly kind: 'header';
+    readonly index: number;
+} | PivotLineBand;
+/** A laid-out table as bands, from the top-left cell of its page fields and location. */
+export interface PivotStructure {
+    /** Top to bottom: the page rows and the gap under them, then the location's. */
+    readonly rows: readonly PivotBand[];
+    /** Left to right across the location: the label columns, then the column lines. */
+    readonly columns: readonly PivotBand[];
+    /** How many rows sit above the location: the page rows and the gap. */
+    readonly top: number;
+    readonly rowSlots: readonly PivotSlot[];
+    readonly columnSlots: readonly PivotSlot[];
+    /** Per row slot, the label column its labels are in. */
+    readonly labelColumns: readonly number[];
+    /** The first header row of column labels; the header rows above it hold captions. */
+    readonly labelRow: number;
+    /** How many header rows there are above the data. */
+    readonly headerRows: number;
+    /** How many label columns there are left of the data. */
+    readonly headerColumns: number;
+    /** How many data fields the table has. */
+    readonly dataCount: number;
+    /** The table is in compact form: its header captions are `Row Labels` and `Column Labels`. */
+    readonly compact: boolean;
+    /** The field captions and their buttons are hidden: their cells are blank. */
+    readonly hiddenFieldHeaders: boolean;
+    /** Each page field: its field, and its caption cell from the top-left (its item is the next cell). */
+    readonly pages: readonly {
+        readonly field: number;
+        readonly row: number;
+        readonly column: number;
+        readonly selected: boolean;
+    }[];
+    /** It has no fields yet ({@link isPivotEmpty}): it holds its cells, and they show nothing. */
+    readonly empty?: true;
+}
+/** How many rows and columns a table with no fields holds (`pivot-probes/probe-pivot-add.ps1`, A01). */
+export declare const PivotPlaceholderSize: {
+    readonly rows: 18;
+    readonly columns: 3;
+};
+/**
+ * The borders an empty table draws at a cell of its placeholder ({@link PivotPlaceholderSize}), from
+ * its top-left: a grey outline round the box, its inner lines in the window's background. `null`
+ * for a table that is not empty, and outside the box. Excel writes them into the cells' formats on
+ * every layout that comes out empty, and the next layout clears them
+ * (`pivot-probes/probe-pivot-empty-box.ps1`).
+ */
+export declare const pivotEmptyBoxAt: (structure: PivotStructure, row: number, column: number) => ICellStyle.Properties | null;
+/** Whether a table has no field placed and no value. */
+export declare const isPivotEmpty: (table: Pick<IPivotTable.JSON, "rowFields" | "columnFields" | "pageFields" | "dataFields">) => boolean;
+/**
+ * The elements of a pivot table style, as OOXML names them, in Excel's precedence: a later one
+ * wins a property an earlier one also sets. Measured at every crossing of eleven layouts;
+ * `lastHeaderCell`, `firstTotalCell` and `lastTotalCell` are a table's only.
+ */
+export declare const PivotStyleElements: readonly ["wholeTable", "pageFieldLabels", "pageFieldValues", "firstColumnStripe", "secondColumnStripe", "firstRowStripe", "secondRowStripe", "firstColumn", "headerRow", "firstHeaderCell", "firstSubtotalColumn", "secondSubtotalColumn", "thirdSubtotalColumn", "blankRow", "firstSubtotalRow", "secondSubtotalRow", "thirdSubtotalRow", "firstColumnSubheading", "secondColumnSubheading", "thirdColumnSubheading", "firstRowSubheading", "secondRowSubheading", "thirdRowSubheading", "lastColumn", "totalRow"];
+export type PivotStyleElement = typeof PivotStyleElements[number];
+/**
+ * Where a table's parts start once it is laid out, from its row and column fields: the header
+ * rows above the data (one, or one per column field and one more for the column captions) and the
+ * label columns left of it.
+ *
+ * @remarks
+ * Hidden field headers drop the column captions' row unless the one data field's name sits in it,
+ * beside the row labels (`pivot-probes/probe-pivot-field-headers.ps1`, 2026-10-27).
+ */
+export declare const headerOf: (table: IPivotTable.JSON) => IPivotTable.PivotHeaderJSON;
+/**
+ * The table's bands from its saved layout, or `null` when it has none (never laid out).
+ *
+ * @remarks
+ * The page fields sit above the location, a blank row between, as `buttonsOf` places them.
+ */
+export declare const structureOf: (table: IPivotTable.JSON) => PivotStructure | null;
+/**
+ * The cells a laid-out table covers from `origin`, the top-left cell of its page fields and location:
+ * its rows, and its columns or its page fields' (a caption and an item each), whichever is wider.
+ */
+export declare const extentOf: (structure: PivotStructure, origin: IRange.CellCoords) => IRange.Coords;
+/**
+ * The cells a laid-out table writes from `origin`, the top-left cell of its page fields and
+ * location: the page fields' rows, as wide as the page fields, and the location. The blank row
+ * between them, and the cells beside the narrower of the two, are the sheet's.
+ */
+export declare const cellsOf: (structure: PivotStructure, origin: IRange.CellCoords) => IRange.Coords[];
+/** Which parts of a pivot table style show, as {@link IPivotTable.PivotStyleJSON} holds them. */
+export type PivotStyleOptions = Pick<IPivotTable.PivotStyleJSON, 'showRowHeaders' | 'showColumnHeaders' | 'showRowStripes' | 'showColumnStripes' | 'showLastColumn'>;
+/** How many lines each stripe covers, from the style's stripe elements (`size`); absent, 1. */
+export interface PivotStripeSizes {
+    readonly firstRowStripe?: number;
+    readonly secondRowStripe?: number;
+    readonly firstColumnStripe?: number;
+    readonly secondColumnStripe?: number;
+}
+/** Whether a band is a line of an axis. */
+export declare const isLine: (band: PivotBand | undefined) => band is PivotLineBand;
+/**
+ * The style elements that cover a cell, in {@link PivotStyleElements} order, the options applied;
+ * empty for a cell that is not the table's.
+ *
+ * @param row From the top-left cell of the page fields and location.
+ */
+export declare const pivotElementsAt: (structure: PivotStructure, row: number, column: number, options: PivotStyleOptions, stripes?: PivotStripeSizes) => PivotStyleElement[];
+/**
+ * Which band of `element` a cell is in: two neighbors that both have the element share an inside
+ * line only in the same band, and are outlined apart otherwise
+ * (`pivot-probes/probe-pivot-style-collapsed.ps1`). A subheading's band is its item, so a collapsed
+ * item is outlined from the next; a column item's subtotal is a band of its own. Each subtotal line
+ * is one, and a blank line is two, its label columns and its data. Every other element is one band.
+ */
+export declare const pivotBandOf: (structure: PivotStructure, row: number, column: number, element: PivotStyleElement) => string;
+/**
+ * What a cell of a laid-out table shows:
+ * - `pageCaption`, `pageItem`: a page field's caption and its item, `page` its index;
+ * - `dataCaption`: a data field's name, where the one data field is named in the header or on
+ *   the only line of a table with no row fields;
+ * - `rowHeader`, `columnHeader`: a compact table's `Row Labels` and `Column Labels`;
+ * - `fieldCaption`: a field's caption over its labels, outside compact form (the values' caption
+ *   where the values are the slot);
+ * - `label`: an item's label at `level` of `axis` (the values slot: a data field's name);
+ * - `total`: a subtotal's or the grand total's caption;
+ * - `value`: a crossing of two lines - a value, a total, or empty.
+ */
+export type PivotCell = {
+    readonly kind: 'pageCaption' | 'pageItem';
+    readonly page: number;
+} | {
+    readonly kind: 'dataCaption';
+    readonly data: number;
+} | {
+    readonly kind: 'rowHeader' | 'columnHeader';
+} | {
+    readonly kind: 'fieldCaption';
+    readonly axis: 'row' | 'column';
+    readonly level: number;
+} | {
+    readonly kind: 'label';
+    readonly axis: 'row' | 'column';
+    readonly level: number;
+    readonly line: PivotLineBand;
+} | {
+    readonly kind: 'total';
+    readonly axis: 'row' | 'column';
+    readonly line: PivotLineBand;
+} | {
+    readonly kind: 'value';
+    readonly row: PivotLineBand;
+    readonly column: PivotLineBand;
+};
+/**
+ * What the cell at `row`, `column` shows, or `null` for a blank cell or one that is not the table's.
+ *
+ * @param row From the top-left cell of the page fields and location.
+ */
+export declare const pivotCellAt: (structure: PivotStructure, row: number, column: number) => PivotCell | null;
+/** What a cell's number format reads of each cache field. */
+export type PivotCacheFieldFormats = readonly {
+    readonly numberFormat?: string | number;
+    readonly dateItems?: readonly number[];
+    readonly group?: IPivotTable.CacheFieldGroupJSON;
+}[];
+/**
+ * The number format Excel gives a cell of the table: a data field's or a pivot field's
+ * `numberFormat` (a code, or a built-in's id), or `undefined` for General or a cell that is not
+ * the table's.
+ *
+ * @remarks
+ * A value cell, empty or a total, takes its line's data field's; a label its field's, as do a
+ * subtotal's caption, a blank line's label cell, a page field's selected item and, from the first
+ * field of its axis, the grand total's caption; headers, captions, the values' labels and a page
+ * field showing all its items are General. A field's format is its pivot field's, else
+ * `cacheFields`'s (its source column's).
+ *
+ * @param row From the top-left cell of the page fields and location.
+ */
+export declare const pivotNumberFormatAt: (structure: PivotStructure, table: IPivotTable.JSON, row: number, column: number, cacheFields?: PivotCacheFieldFormats) => string | number | undefined;
+/**
+ * The code a pivot's number format renders with: a built-in id as `runtime`'s locale shows it,
+ * a code as it is; absent, General.
+ */
+export declare const formatCodeOf: (format: string | number | undefined, runtime: IRuntime) => string;
+/** A rectangle of a table's cells, from the top-left cell of its page fields and location, with a format code. */
+export interface PivotFormatRegion extends IRange.Coords {
+    readonly value: string;
+}
+/**
+ * The cells of a laid-out table whose number format ({@link pivotNumberFormatAt}) shows a date or
+ * a time, as rectangles with the code each renders with; empty when no format the table names is
+ * one. Walked by band: the value cells by runs of the lines' data fields, the page, header and
+ * label cells one at a time, merged down their column. A number format the user put on the table
+ * (`userNumberFormatAt`) wins over the definition's; a table with one is walked cell by cell.
+ *
+ * @param dateCodeOf The code a format renders with when it shows a date or a time, else `null`.
+ * @param userNumberFormatAt The number format the formats a user put on the table give a cell, if any.
+ */
+export declare const pivotDateRegionsOf: (structure: PivotStructure, table: IPivotTable.JSON, cacheFields: PivotCacheFieldFormats | undefined, dateCodeOf: (format: string | number) => string | null, userNumberFormatAt?: (row: number, column: number) => string | number | undefined) => PivotFormatRegion[];
+//# sourceMappingURL=_PivotStructure.d.ts.map

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

@@ -0,0 +1,21 @@
+import { ICellStyle, IStyleCollection } from '../style';
+import { ITableStyle } from '../table';
+import { IPivotTable } from './IPivotTable';
+/** 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 declare const pivotStylePreviewOf: (styles: IStyleCollection, style: ITableStyle | null, options?: IPivotTable.PivotStyleJSON, rows?: number) => PivotStylePreview;
+//# sourceMappingURL=_PivotStylePreview.d.ts.map