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

package/types/src/sheet/Worksheet.d.ts

@@ -6,6 +6,7 @@ import { IListener } from '../listener';
 import { IResource, IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
 import { IProtection } from '../protection';
+import { IFontCollection } from '../font';
 import { IComment, ICommentCollection } from '../comment';
 import { IColor } from '../color';
 import { IHyperlink } from '../hyperlink';
@@ -29,6 +30,7 @@ import { IChartCollection } from '../chart';
 import { IPicture } from '../picture';
 import { InsertableCollection } from '../movable/_InsertableCollection';
 import { IPivotTable, IPivotTableCollection } from '../pivot';
+import { PivotTable } from '../pivot/PivotTable';
 import { AnomalyFindings, AnomalySet, AnomalySource, RoleSource } from '../anomalies/_Anomalies';
 import { CellKind } from './_Kinds';
 import { IRichDataKind } from '../richData/IRichDataKind';
@@ -77,6 +79,7 @@ import { Outline } from '../outline/Outline';
 import { PageLayout } from '../print/PageLayout';
 import { ICalculation } from '../calculation';
 import { ICalcGrid } from '../calculation/grid';
+import { SpillEntry } from '../calculation/spatial';
 import { SheetCellOptions } from './SheetCell';
 import * as _SheetFilterUtils from './_SheetFilterUtils';
 /** The font colors a workbook writes its roles in, and a key that compares by content. */
@@ -146,8 +149,8 @@ export declare class Worksheet implements IWorksheet {
      */
     protected _movableSelectionAtCommitEnd: Map<ITransaction.ICommit, readonly string[]>;
     /**
-     * What calculation passes realized while a root was open, told to listener nodes once it
-     * closes. See {@link _realizeCalcedValues}.
+     * What calculation passes realized while a root was open, told to listener nodes once it lands,
+     * or closes without landing. See {@link _realizeCalcedValues}.
      */
     protected _heldPassRanges: IRange.Coords[] | null;
     protected _emitter: ListenerEmitter<IWorksheet, IWorksheet.IListeners>;
@@ -266,6 +269,7 @@ export declare class Worksheet implements IWorksheet {
      * Set while a cut on a protected sheet moves its cells, which it ruled on before it began (see
      * `_copyFromNow`): the move's own steps (its clears, the rules it re-anchors) do not rule again,
      * since the first of them changes the cells the next would read. Synchronous, like the move.
+     * A pivot table's layout clearing its own cells is ruled the same way ({@link _writePivotCells}).
      */
     protected _isMoveRuled: boolean;
     protected _lastRangeRead: {
@@ -327,6 +331,8 @@ export declare class Worksheet implements IWorksheet {
     protected _emptyCell: ICell;
     protected _cellOptions: SheetCellOptions;
     protected _closed: boolean;
+    /** The grid holds pivot views this sheet told it ({@link _tellPivots}). */
+    protected _pivotsTold: boolean;
     protected _cellBuffer: CellBuffer | null;
     protected _defaultColWidthCache: number | null;
     protected _defaultRowHeightCache: number | null;
@@ -547,6 +553,7 @@ export declare class Worksheet implements IWorksheet {
         /** The same for the note boxes' index. */
         takeShiftedNoteModels: () => Map<IMovable, ISpatialMap.Entry<MovableEntry>> | null;
         markColumnHeaderTableNames: () => void;
+        tellPivots: () => void;
         commitWithDirectives: (trans: ITransaction, selection: Partial<IRangeSelection.Coords> | null, options?: ICellRange.OperationOptions, directives?: CommitDirectives) => void;
         recordAutoFit: (trans: ITransaction, ranges: readonly IRange.Coords[], autoFit: boolean | ICellRange.AutoFitOptions) => void;
         readonly styles: IStyleCollection;
@@ -786,9 +793,44 @@ export declare class Worksheet implements IWorksheet {
         fill: IUsedRangeSpatialMap<SheetDirectStyle>;
         content: IUsedRangeSpatialMap<SheetDirectStyle>;
     }): IUsedRangeSpatialMap<SheetDirectStyle>;
-    /** @internal Logic lives in `_SheetMutations.updateStyles`. */
+    /**
+     * Logic lives in `_SheetMutations.updateStyles`.
+     *
+     * @remarks
+     * Over a pivot table the write is not the cells' own: it goes to the table
+     * ({@link _formatPivotTables}).
+     * @internal
+     */
     protected _updateStyles(ranges: readonly ISpatialMap.Entry<ICellStyle.Update>[], defaultUpdate?: ICellStyle.Update, // we do this because updateTuples may update each
     options?: ICellStyle.UpdateOptions, calcedNumberFormat?: boolean): void;
+    /**
+     * A style written over a placed pivot table's cells is the table's, as Excel takes it: formats
+     * over the areas those cells are, which follow their items through a relayout
+     * (`PivotTable._formatCells`). Its other cells take it as their own, in the same step. Only a
+     * style given as plain properties is a table's; a callback, a cleared property or a value
+     * resolved per cell is written as the cells' own.
+     *
+     * @remarks
+     * A pivot cell's style marks a place in the table, not an address: North's label, East's
+     * subtotal, Apple's value under East. A relayout draws every cell again from the table, and a
+     * format goes wherever its place now is (`pivot-probes/probe-pivot-format-follows.ps1`): North's
+     * fill moves up with North when East collapses, and a fill on collapsed East's values moves to
+     * the `East Total` line when East expands with its subtotals at the bottom.
+     *
+     * So the table's formats are its definition's (`<formats>`), and they are the pivot tier of a
+     * cell's style ({@link PivotTable._getCellLayer}), where a table's style sits, below the direct
+     * one. A direct style inside a laid-out table is only what the table does not account for: what
+     * a file saved there and the table cannot explain. A relayout clears it, as Excel's does, since
+     * it has no place in the table to follow.
+     *
+     * Written as the cells' own instead, a format would be cleared by the next relayout, never reach
+     * Excel's `<formats>`, and could not undo what the table's style sets: over a table or pivot
+     * tier, a direct value matching the Normal style (not bold, 11 pt) is ignored.
+     *
+     * @returns `false` when no part of the write lands on a table.
+     * @internal
+     */
+    protected _formatPivotTables(ranges: readonly ISpatialMap.Entry<ICellStyle.Update>[], defaultUpdate: ICellStyle.Update | undefined, options: ICellStyle.UpdateOptions | undefined): boolean;
     /**
      * Holds a style set on one cell in the buffer the cell writes of an open transaction are held in
      * ({@link CellBuffer.holdStyle}).
@@ -1014,6 +1056,118 @@ export declare class Worksheet implements IWorksheet {
      * changes costs a walk of the tables. A restore is not told, as {@link _tellHidden}.
      */
     protected _tellFiltered(): void;
+    /** The tables a cut is moving, their cells not landed yet ({@link _cutPivots}, {@link _landPivots}). */
+    protected _pivotsInTransit: PivotTable[] | null;
+    /**
+     * The tables a cut moved have their cells where they landed: the guard on them stands again,
+     * and a blocked one is laid out there if it can be.
+     * @internal
+     */
+    _landPivots(): void;
+    /**
+     * What, but `table`, is in the cells `wanted`, past the cells `own` it holds now: another pivot
+     * table, an array's cells or a value, the first of those found in that order; `null` for nothing.
+     * What is in the way blocks it, as anything in a dynamic array's way does; formats are no
+     * obstacle, and neither is a table's empty cells: Excel lays a pivot table over them
+     * (`pivot-probes/probe-pivot-table-obstacle.ps1`).
+     * @internal
+     */
+    _pivotObstructionOf(table: IPivotTable, wanted: readonly IRange.Coords[], own: readonly IRange.Coords[]): PivotTable.Obstruction | null;
+    /**
+     * {@link IPivotTableCollection.add}: what can be refused is, before anything changes, and the
+     * cache and the table land in one step with the table's cells.
+     * @internal
+     */
+    protected _addPivotTable(source: IPivotTableCollection.Source, location: ICellRange.Address, options?: IPivotTableCollection.AddOptions): Promise<IPivotTable>;
+    /**
+     * Refuses a name a pivot table on this sheet cannot take: empty, longer than 255 characters, or
+     * another table's here, without regard to case (`pivot-probes/probe-pivot-table-api.ps1`, N01).
+     * Excel cuts a longer name to 255 silently; this refuses it.
+     *
+     * @param table The table being renamed, whose own name is free to it; `null` for a new one.
+     * @internal
+     */
+    _assertPivotName(name: string, table: IPivotTable | null): void;
+    /**
+     * The top-left cell of the location a pivot table placed at `location` takes, refused where it
+     * cannot go: on another sheet or in another pivot table. What else is in its cells is for its layout to judge
+     * ({@link PivotTable._refreshFrom}'s `place`). Page fields need their rows and a blank one above the
+     * table, so at the top of a sheet it moves down (A09, M05).
+     *
+     * @param pageCount How many page fields it has, each a row.
+     * @param table The table being moved, whose own cells it may land on; `null` for a new one.
+     * @internal
+     */
+    _pivotAnchorAt(location: ICellRange.Address, pageCount: number, table: IPivotTable | null): IRange.Coords;
+    /** The name Excel gives a new table: one past the highest number the workbook's tables have (A06, B12). */
+    private _nextPivotName;
+    /**
+     * The order the sheet stores its cells in: what a pivot table's layout is asked to emit, so
+     * {@link _writePivotCells} takes its runs as they are.
+     * @internal
+     */
+    _getPivotCellOrder(): 'rows' | 'columns';
+    /**
+     * Writes a pivot table's cells as stored values in the caller's batch: the values and direct
+     * styles of `clears` cleared, as Excel's relayout rewrites each cell's format from the table's,
+     * then `cells` written from `origin`, in the sheet's order ({@link _getPivotCellOrder}) and sparse:
+     * each run goes in as it is, shifted, and a blank is not stored. The mutations are called directly: the
+     * table is settling, so its guard stands aside, and no blocked table is laid out mid-write.
+     * Text is stored as text, never parsed. On a protected sheet the layout has ruled
+     * (`pivotTables`), so locked cells do not refuse its writes.
+     * @internal
+     */
+    _writePivotCells(clears: readonly IRange.Coords[], cells: Tuple.GridTuple<Scalar>, origin: {
+        row: number;
+        column: number;
+    }): void;
+    /**
+     * The blocked pivot tables waiting on any of `ranges`, or `null` for none.
+     */
+    protected _pivotsWaitingOn(ranges: readonly IRange.Coords[]): PivotTable[] | null;
+    /**
+     * Lays out again, in the caller's batch, each of `tables` whose way is clear now: Excel places a
+     * blocked table as soon as what blocked it is gone (`pivot-probes/probe-pivot-spill.ps1`). On a
+     * protected sheet it does so only where the lock allows pivot tables; otherwise the table stays
+     * blocked (`pivot-probes/probe-pivot-protected.ps1`).
+     */
+    protected _unblockPivots(tables: readonly PivotTable[]): void;
+    /**
+     * Fits the columns a pivot table covers to its cells alone, as Excel's update does: whatever else
+     * is in those columns is not measured. Part of the layout's step: a fit owed to fonts still
+     * loading runs later undescribed, so it is undone with the layout rather than on its own.
+     * @internal
+     */
+    _autoFitPivotColumns(extent: IRange.Coords): void;
+    /**
+     * Tells the grid the values this sheet's pivot tables show, where each sits now, for
+     * `GETPIVOTDATA` ({@link ICalcGrid.setPivots}): after the load, and from inside an operation that
+     * added, moved or deleted one. The pivot code is loaded the first time a modeled table asks; until
+     * it is, nothing is told and `GETPIVOTDATA` keeps the value it was saved with. A table whose
+     * values are not computed (not modeled, or not laid out) is told as there, at its location, so
+     * `GETPIVOTDATA` on it keeps its saved value while one on no table is `#REF!`.
+     * @internal
+     */
+    _tellPivots(): void;
+    /**
+     * The pivot tables of a cut from `source` landing on `landing` (its own size), before its cells
+     * move (`checkCutOfPivot`): one it holds whole moves with it, one it lands on whole is deleted,
+     * part of either is refused, as is a table landing on a table. A moved table is anchored where
+     * it lands at once, so the cut's clear does not take it for a table cleared; once the cells are
+     * across the caller tells the grids ({@link _tellPivots}), which take the cells that moved with
+     * it as its own, as they take a loaded table's.
+     *
+     * @returns Whether any table moved or was deleted.
+     * @throws ExpectedError where Excel refuses the cut, and for a table moved to another sheet.
+     * @internal
+     */
+    _cutPivots(source: Worksheet, from: IRange.Coords, landing: IRange.Coords): boolean;
+    /**
+     * The spill the grid holds anchored at a cell: an array's, or a pivot table's laid-out cells.
+     * `null` when none is anchored there; a blocked spill is not held (`ICalcGrid.getBlockedSpills`).
+     * @internal
+     */
+    _getSpillAt(row: number, column: number): SpillEntry | null;
     /** @internal */
     protected _getDefaultShiftAxis(coords?: IRange.Coords): IRange.Axis;
     /** @internal */
@@ -1073,7 +1227,8 @@ export declare class Worksheet implements IWorksheet {
     /**
      * Runs the fits owed (see {@link _autoFit}): one held runs for the first time as it was asked;
      * one that ran against a stand-in runs again, leaving alone a custom size or a hidden row set
-     * since (its first run already cleared what the caller asked to override).
+     * since (its first run already cleared what the caller asked to override). A run again is
+     * undescribed: it corrects the step its first run belongs to, and is undone with that step.
      *
      * @returns `false` if none were owed.
      */
@@ -1312,6 +1467,8 @@ export declare class Worksheet implements IWorksheet {
     /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
     protected _notifyTablesChange(): void;
     /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
+    protected _notifyPivotTablesChange(): void;
+    /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
     protected _notifyDataValidationsChange(): void;
     /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
     protected _notifyProtectedRangesChange(): void;
@@ -1691,6 +1848,12 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _onRootTransactionClose(commit: ITransaction.ICommit, isRollback?: boolean, isElided?: boolean, isAmend?: boolean): void;
+    /**
+     * Tells listener nodes of the passes held while an operation was open ({@link _heldPassRanges}).
+     *
+     * @internal
+     */
+    protected _releaseHeldPassRanges(): void;
     /**
      * Keep the view's selection somewhere it can be once the sheet has changed: inside the sheet,
      * and with its active cell on the top-left of the merge it falls in.
@@ -2118,8 +2281,8 @@ export declare class Worksheet implements IWorksheet {
     protected _createCellControls(cellControls: IAnchoredMap<ICellControl, ICellControl.JSON>, key: keyof State, refs: IRange.JSONReference<ICellControl.JSON>[], createModel: (options: CellControl.ConstructorOptions) => ICellControl): IAnchoredMap<ICellControl, ICellControl.JSON>;
     /**
      * Loads the pivot tables into their anchored map, each anchored where its part says it sits.
-     * The map moves and deletes them with structural edits; the table itself rules on the edit
-     * (`PivotTable._processContainerShift`).
+     * The map moves and deletes them with structural edits; the grid's spill of a table rules on
+     * the edit (`SpillEntry.checkShift`).
      * @internal
      */
     protected _createPivotTables(pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>, key: keyof State, refs: IRange.JSONReference<IPivotTable.JSON>[], fromResourceId?: (resourceId: number) => IResource): IAnchoredMap<IPivotTable, IPivotTable.JSON>;
@@ -2157,7 +2320,6 @@ export declare class Worksheet implements IWorksheet {
     /** {@inheritDoc IWorksheet.getNames} */
     getNames(): INamedCollection;
     /** {@inheritDoc IWorksheet.getCalculation} */
-    /** {@inheritDoc IWorksheet.getCalculation} */
     getCalculation(): ICalculation;
     /** {@inheritDoc IWorksheet.createFormula} */
     createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
@@ -2165,6 +2327,12 @@ export declare class Worksheet implements IWorksheet {
     evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /** {@inheritDoc IWorksheet.whenCalculationReady} */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /** {@inheritDoc IWorksheet.getFonts} */
+    getFonts(): IFontCollection;
+    /** {@inheritDoc IWorksheet.whenFontsReady} */
+    whenFontsReady(): Promise<void>;
+    /** {@inheritDoc IWorksheet.whenReady} */
+    whenReady(): Promise<void>;
     /** {@inheritDoc IWorksheet.getWorkbook} */
     getWorkbook(): IWorkbook | null;
     get [Symbol.toStringTag](): string;

package/types/src/sheet/_PivotFootprint.d.ts

@@ -0,0 +1,42 @@
+import { IRange } from '@sheetxl/primitives';
+import { ISpatialMap, ISpatialQuery } from '../collections';
+import { ICellStyle } from '../style';
+import { IPivotTable } from '../pivot';
+import { IAnchoredMap } from '../anchored/IAnchoredMap';
+/** Where a pivot table sits ({@link pivotFootprintOf}). */
+export interface PivotFootprint {
+    /** What it covers: its page fields, the blank row under them and its location; the anchor alone while blocked. */
+    extent: IRange.Coords;
+    /** Its own cells: the page fields' and the location's, without the blank row between, which is the sheet's. */
+    cells: IRange.Coords[];
+    /** It shows `#SPILL!` at its anchor. */
+    isBlocked: boolean;
+}
+/**
+ * Where `table` sits, from its definition and anchor: laid out, or `#SPILL!` at its anchor. `null`
+ * for a table that is not laid out.
+ * @internal
+ */
+export declare const pivotFootprintOf: (table: IPivotTable) => PivotFootprint | null;
+/**
+ * The pivot tables placed over `coords`, each at what it holds, which it is anchored at, for the
+ * pivot tier of a cell: its style and its labels' insets. A table that is not placed, blocked
+ * among them, has none. Reads no calculation: a table renders as its definition and its cells say.
+ *
+ * @remarks
+ * The map's search, borrowed as it is: read-only.
+ * @internal
+ */
+export declare const searchPivotPlacements: (pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>, coords: IRange.Coords) => ISpatialMap.Entry<IPivotTable>[];
+/**
+ * The sheet's date and time formats: its direct styles' (`dateFormatSpatial`) and the cells its
+ * placed pivot tables give a date or time format, from their definitions and the formats a user put
+ * on them. `dateFormats` itself when the sheet has no pivot table. A cell's own number format wins
+ * over a table's, date or not (`contentStyles`, the direct content styles): a direct date format
+ * is found in `dateFormats`, a direct non-date one masks the table's date there.
+ * @internal
+ */
+export declare const withPivotDateFormats: (dateFormats: ISpatialQuery<string>, pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>, contentStyles: ISpatialQuery<{
+    getProperties(): ICellStyle.Properties | null;
+}>) => ISpatialQuery<string>;
+//# sourceMappingURL=_PivotFootprint.d.ts.map

package/types/src/sheet/_SheetAutoFitUtils.d.ts

@@ -2,6 +2,17 @@ import { IRange } from '@sheetxl/primitives';
 import { Size } from '@sheetxl/utils';
 import { ICellRange } from '../cellRange';
 import { Worksheet } from './Worksheet';
+/**
+ * {@link doAutoFit}'s options, with what only the sheet's own callers ask.
+ * @internal
+ */
+export interface DoAutoFitOptions extends ICellRange.AutoFitOptions {
+    /**
+     * Measure only the cells in the ranges. Otherwise a fit that shrinks measures the whole of each
+     * row or column it fits, as a fit asked for by a user does.
+     */
+    within?: boolean;
+}
 /**
  * Automatically adjusts row heights and column widths to fit cell content and styles.
  * - Merges and sorts input ranges for efficient processing.
@@ -15,7 +26,7 @@ import { Worksheet } from './Worksheet';
  * @param options AutoFit options (axis, expandOnly, skipCustomSize, etc).
  * @internal
  */
-export declare function doAutoFit(sheet: Worksheet, ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions): void;
+export declare function doAutoFit(sheet: Worksheet, ranges: readonly IRange.Coords[], options?: DoAutoFitOptions): void;
 /**
  * The size `range`'s content needs — what {@link doAutoFit} would commit, reduced to a `Size`
  * instead of written.

package/types/src/sheet/_SheetMutations.d.ts

@@ -11,8 +11,55 @@ import { IProperties } from '../type';
 import { FormulaEntry } from '../calculation/grid';
 import { CellStateIteratorContext } from './_SheetUtils';
 import { SheetDirectStyle } from './style/SheetDirectStyle';
+import { IAnchoredMap } from '../anchored/IAnchoredMap';
+import { IPivotTable } from '../pivot';
 import { RangeState, InternalTupleUpdate } from './_SheetStateTypes';
 import { SheetMutationContext } from './Worksheet';
+/** What {@link checkCutOfPivot} finds a cut does to the pivot tables. */
+export interface PivotCut {
+    /** The tables the cut holds whole, which move with it, each with where it covers now. */
+    moves: {
+        table: IPivotTable;
+        extent: IRange.Coords;
+    }[];
+    /** The tables it lands on whole, which it deletes. */
+    covered: IPivotTable[];
+}
+/** A sheet's pivot tables, for {@link checkCutOfPivot}. */
+export interface PivotCutSide {
+    pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>;
+    /** The cells cut, or where they land: the same size. */
+    coords: IRange.Coords;
+}
+/**
+ * Excel's rules for a cut over pivot tables (`pivot-probes/probe-pivot-cut.ps1`): a cut holding
+ * a table's whole extent moves the table; one holding part of it, or landing on part of one, is
+ * refused; one landing on all of one deletes it. The blank row under the page fields is the
+ * sheet's, cut from or into. A table that is not laid out is not judged. Runs before any
+ * state is mutated.
+ *
+ * @param from The cut, on its sheet.
+ * @param to Where it lands, on the destination sheet (the same maps as `from` within a sheet).
+ */
+export declare const checkCutOfPivot: (from: PivotCutSide, to: PivotCutSide) => PivotCut;
+/** The part of a style write a pivot table takes: per style, the cells it lands on. */
+export interface PivotStyleWrite {
+    table: IPivotTable;
+    styles: Map<ICellStyle.Properties, IRange.Coords[]>;
+}
+/**
+ * A style write over pivot tables' cells, as Excel takes it: the part on a laid-out table's cells
+ * (its page fields' and location's; not while it shows `#SPILL!` or lays itself out, nor with
+ * preserve formatting off) is the table's, to become its formats; the rest is the cells' own, which
+ * the next relayout clears. Only a style given as plain
+ * properties ({@link asPlainStyle}) is a table's; any other passes through whole. The write's
+ * entries are cut by the tables' cells on a spatial map, where they overlap one another a later
+ * one merging over an earlier, as the cells' own write does. `null` when no part is a table's.
+ */
+export declare const splitStylesOverPivots: (pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>, ranges: readonly ISpatialMap.Entry<ICellStyle.Update>[], defaultUpdate: ICellStyle.Update | undefined) => {
+    tables: PivotStyleWrite[];
+    rest: ISpatialMap.Entry<ICellStyle.Update>[];
+} | null;
 /**
  * The shared insert/delete engine (see SHEET-SPLIT-DESIGN §6e). Shifts every state map (values,
  * spills, styles, merges, hyperlinks, comments, movables, tables, listeners, calc, …) one range at

package/types/src/sheet/_SheetStateTypes.d.ts

@@ -146,6 +146,10 @@ export declare namespace RangeState {
          * A table that this cell belongs to.
          */
         autoTable?: ITable;
+        /**
+         * The pivot table laid out over this cell, whose style the cell takes.
+         */
+        pivot?: IPivotTable;
         /**
          * Conditional styles.
          *
@@ -281,6 +285,8 @@ export declare namespace RangeState {
         readonly DateFormat: "dateFormat";
         readonly Table: "table";
         readonly AutoTable: "autoTable";
+        /** A pivot table laid out over the cell: its style is the pivot tier of the cell's style. */
+        readonly Pivot: "pivot";
         readonly DataValidations: "dataValidations";
         readonly Merge: "merge";
         readonly Hyperlink: "hyperlink";
@@ -528,5 +534,10 @@ export interface InternalTupleUpdate {
      * from an operation that has ruled on the sheet's protection, so locked cells do not refuse it.
      */
     isCalculatedFill?: boolean;
+    /**
+     * A pivot table's own cells, written by its layout, which has ruled on the sheet's protection
+     * (`pivotTables`), so locked cells do not refuse it.
+     */
+    isPivotLayout?: boolean;
 }
 //# sourceMappingURL=_SheetStateTypes.d.ts.map

package/types/src/sheet/style/SheetCellStyle.d.ts

@@ -317,6 +317,12 @@ export declare class SheetCellStyle implements ICellStyle {
     hasVisibleStyling(): boolean;
     /** {@inheritDoc ICellStyle.isNormal} */
     isNormal(): boolean;
+    /**
+     * The Normal style of this style's collection, for what Excel measures in Normal's font rather
+     * than the cell's (the indent unit); `null` outside a collection.
+     * @internal
+     */
+    _getNormal(): ICellStyle | null;
     /**
      * The AUTHORED (explicit) properties of this style: the direct layer values plus the `named`
      * reference. Never includes cascade-resolved values (named/table/conditional results) - those

package/types/src/sheet/style/SheetPivotStyle.d.ts

@@ -0,0 +1,83 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { IProperties } from '../../type';
+import { IBorders } from '../../border';
+import { ICellStyle, IStyleCollection } from '../../style';
+import { ITableStyle } from '../../table';
+import { PivotStructure, PivotStyleElement, PivotStyleOptions, PivotStripeSizes } from '../../pivot/_PivotStructure';
+/**
+ * A pivot table style laid over cells: each cell's style is the style's elements that cover it,
+ * merged in the pivot order, a later element winning what an earlier one also sets.
+ *
+ * @remarks
+ * An element's borders outline each of its bands, with its inside lines between the band's cells,
+ * and merge like its other properties: a cell's own line on a side is the last element's that draws
+ * one there. A side two cells share is one line, as Excel draws it: of the two cells' own lines, the
+ * later element's in the pivot order, whatever its weight or color; so a subheading's thin top shows
+ * over the header row's medium bottom, and a subheading's bottom over the whole table's inside line
+ * (`pivot-probes/probe-pivot-style-screen.ps1`, the live window; `DisplayFormat` reports the heavier,
+ * then the darker, which is not what Excel draws). Two lines of the same element: the heavier, then
+ * the darker, unprobed. The row under the page fields, which no element covers, shows the page
+ * fields' bottom line.
+ *
+ * A cell's style is a function of its elements and of each side's line; merged styles are kept
+ * by that permutation, so a table resolves to a few distinct styles however large it is.
+ */
+export declare abstract class PivotElementsStyle implements IProperties.ICellRanged<ICellStyle.Properties> {
+    protected _styles: IStyleCollection;
+    protected _properties: Readonly<ITableStyle.Properties>;
+    protected _coords: IRange.Coords;
+    protected _permCache: Map<string, Readonly<ICellStyle.Properties> | null>;
+    protected _luminances: Map<string, number>;
+    /**
+     * @param properties The style's resolved properties (`ITableStyle.getProperties`).
+     * @param coords The cells it covers.
+     */
+    constructor(styles: IStyleCollection, properties: Readonly<ITableStyle.Properties>, coords: IRange.Coords);
+    /** {@inheritDoc IProperties.ICellRanged.getCoords} */
+    getCoords(): IRange.Coords;
+    /** The elements covering a cell, from the top-left, in the pivot order; empty outside. */
+    protected abstract _coveringAt(row: number, column: number): PivotStyleElement[];
+    /** Which band of `element` a cell is in: two neighbors share an inside line only in the same band. */
+    protected abstract _bandOf(row: number, column: number, element: PivotStyleElement): string;
+    /** The style's elements covering a cell, from the top-left; those the style leaves unset dropped. */
+    protected _elementsAt(row: number, column: number): PivotStyleElement[];
+    /**
+     * A cell's own line on one side: of `elements` (the cell's, in the pivot order), the last that
+     * draws one there - its inside line where `across`, the elements whose band goes on across the
+     * side, has it, its outer line where it ends. `null` when none does, or the last says none.
+     */
+    protected _ownLine(elements: readonly PivotStyleElement[], across: ReadonlySet<PivotStyleElement>, side: keyof IBorders.Properties, inside: keyof IBorders.Properties): {
+        element: PivotStyleElement;
+        line: keyof IBorders.Properties;
+    } | null;
+    /**
+     * Of two cells' lines on the side they share, the one Excel draws: the later element's, then the
+     * heavier, then the darker.
+     */
+    protected _shownLine<T extends {
+        element: PivotStyleElement;
+        line: keyof IBorders.Properties;
+    }>(a: T | null, b: T | null): T | null;
+    /** A color's relative luminance (Rec. 709), by its spelling; black when it has none. */
+    protected _luminance(color: unknown): number;
+    /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
+    getPropertiesAt(rowIndex: number, colIndex: number, _value: Scalar): Readonly<ICellStyle.Properties>;
+}
+/**
+ * A pivot table style laid over a laid-out pivot table: the elements that cover each cell are
+ * {@link pivotElementsAt}'s, their bands {@link pivotBandOf}'s. The instance is the table's for one
+ * layout, style and style collection ({@link PivotTable._getRangedStyle}).
+ */
+export declare class PivotRangedStyle extends PivotElementsStyle {
+    protected _structure: PivotStructure;
+    protected _options: PivotStyleOptions;
+    protected _stripes: PivotStripeSizes;
+    /**
+     * @param properties The style's resolved properties (`ITableStyle.getProperties`).
+     * @param origin The top-left cell of the table's page fields and location.
+     */
+    constructor(styles: IStyleCollection, properties: Readonly<ITableStyle.Properties>, structure: PivotStructure, origin: IRange.CellCoords, options: PivotStyleOptions);
+    protected _coveringAt(row: number, column: number): PivotStyleElement[];
+    protected _bandOf(row: number, column: number, element: PivotStyleElement): string;
+}
+//# sourceMappingURL=SheetPivotStyle.d.ts.map

package/types/src/sheet/style/_IndentUnit.d.ts

@@ -0,0 +1,14 @@
+import { ICellStyle } from '../../style/ICellStyle';
+/**
+ * The Normal style `style` resolves against, or `style` itself when it has none.
+ */
+export declare function normalOf(style: ICellStyle): ICellStyle;
+/**
+ * The width in px of one indent level: three spaces of the Normal font, each rounded to a whole
+ * px, whatever the cell's own font. Measured against Excel
+ * (`private-assets/scripts/pivot-probes/probe-pivot-label-geometry.ps1`): 9 px under Calibri 11 and
+ * Aptos Narrow 11, 18 px under Arial 16, the same for a cell at 8 pt or 36 pt. Cached per Normal
+ * style until a font arrives.
+ */
+export declare function indentUnit(style: ICellStyle): number;
+//# sourceMappingURL=_IndentUnit.d.ts.map

package/types/src/sheetHeader/SheetCellHeader.d.ts

@@ -28,7 +28,7 @@ export declare class SheetCellHeader implements ICellHeader {
     isCustomSize(): boolean;
     /** {@inheritDoc ICellHeader.getSheetHeader} */
     getSheetHeader(): ISheetHeader;
-    /** {@inheritDoc ICell.getColumn} */
+    /** {@inheritDoc ICellHeader.getColumn} */
     getColumn(): ITable.IColumn | null;
     /** {@inheritDoc ICellHeader.asCell} */
     asCell(): ICell;