@jsfkit/types 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -9,6 +9,8 @@
  * | `d`   | Date    | The {@link Cell.s | cell style} formats the integer cell value as a date |
  * | `s`   | Text    |                                                                          |
  * | `z`   | Empty   | Cell is empty                                                            |
+ *
+ * @group Workbooks
  */
 type CellValueType = 'b' | 'e' | 'n' | 'd' | 's' | 'z';
 
@@ -16,6 +18,7 @@ type CellValueType = 'b' | 'e' | 'n' | 'd' | 's' | 'z';
  * A cell comment.
  *
  * @deprecated Use {@link Note | notes} and {@link ThreadedComment | threaded comments} instead.
+ * @group Workbooks
  */
 type Comment = {
     /** Author of the comment. */
@@ -33,6 +36,7 @@ type Comment = {
  * `XFD1048576` inclusive.
  *
  * @pattern ^[A-Z]{1,3}[0-9]{1,7}$
+ * @group Workbooks
  */
 type CellId = string;
 
@@ -42,12 +46,15 @@ type CellId = string;
  * The range consists of two {@link CellId | CellIds} separated by a colon (`:`) character.
  *
  * @pattern ^([A-Z]{1,3}[0-9]{1,7}):([A-Z]{1,3}[0-9]{1,7})$
+ * @group Workbooks
  */
 type CellRange = string;
 
 /**
  * Data table configuration, present on the master cell of a data table range.
  * Represents an Excel What-If Analysis data table.
+ *
+ * @group Workbooks
  */
 type DataTable = {
     /** Range of cells the data table manages (e.g., "D3:D5") */
@@ -64,11 +71,15 @@ type DataTable = {
 
 /**
  * A whole number without a fractional value.
+ *
+ * @group Workbooks
  */
 type integer = number;
 
 /**
  * A spreadsheet cell.
+ *
+ * @group Workbooks
  */
 type Cell = {
     /**
@@ -125,6 +136,8 @@ type Cell = {
  *   "scope": "Sheet1",
  *   "value": "Sheet1!B1:C1" }
  * ```
+ *
+ * @group Workbooks
  */
 type DefinedName = {
     /**
@@ -150,6 +163,8 @@ type DefinedName = {
 
 /**
  * A simple container sheet for cell values within an external workbook.
+ *
+ * @group Workbooks
  */
 type ExternalWorksheet = {
     /**
@@ -172,6 +187,8 @@ type ExternalWorksheet = {
 
 /**
  * A cell from another workbook (i.e. another file) that is referenced in this workbook.
+ *
+ * @group Workbooks
  */
 type External = {
     /** Filename being referenced. */
@@ -196,6 +213,7 @@ type External = {
  * A numeric value measured in pixels.
  *
  * @min 0
+ * @group Workbooks
  */
 type PixelValue = number;
 
@@ -209,6 +227,8 @@ type PixelValue = number;
  * GridSize may have a style-index ({@link GridSize.s}) attribute like individual cells. The styling
  * information on the column should be used for all cells that are not present in the sheet's cell
  * collection.
+ *
+ * @group Workbooks
  */
 type GridSize = {
     /** A 1-based inclusive start index. */
@@ -226,6 +246,8 @@ type GridSize = {
  *
  * There is a maximum of one note per cell, and there is no way to reply to a note. For cell
  * annotations with replies, see {@link ThreadedComment} and {@link Worksheet.comments}.
+ *
+ * @group Workbooks
  */
 type Note = {
     /** Cell to which the note is attached (e.g. A1, E24). */
@@ -254,6 +276,7 @@ type Note = {
  *
  * @see {@link MentionTextRun} for mentions of people
  * @see {@link HyperlinkTextRun} for hyperlinks
+ * @group Workbooks
  */
 type TextRun = {
     /** Starting character position of the run in the text (zero-indexed). */
@@ -264,6 +287,8 @@ type TextRun = {
 
 /**
  * A {@link TextRun | text run} representing a hyperlink within a threaded comment's text.
+ *
+ * @group Workbooks
  */
 type HyperlinkTextRun = TextRun & {
     /** Discriminator to identify this as a hyperlink text run. */
@@ -274,6 +299,8 @@ type HyperlinkTextRun = TextRun & {
 
 /**
  * A {@link TextRun | text run} representing a mention of a person within a threaded comment's text.
+ *
+ * @group Workbooks
  */
 type MentionTextRun = TextRun & {
     /** Discriminator to identify this as a mention text run. */
@@ -290,6 +317,8 @@ type MentionTextRun = TextRun & {
 
 /**
  * An author of a threaded comment, or a person mentioned in a threaded comment.
+ *
+ * @group Workbooks
  */
 type Person = {
     /**
@@ -319,6 +348,8 @@ type Person = {
 
 /**
  * A threaded comment that is attached to an individual cell.
+ *
+ * @group Workbooks
  */
 type ThreadedComment = {
     /**
@@ -357,15 +388,18 @@ type ThreadedComment = {
 
 /**
  * Represents a one dimensional position or length in EMUs.
- * Same as {@link Coordinate} but value must be 0 or higher.
+ * Same as {@link EmuValue} but value must be 0 or higher.
  *
  * @min 0
  * @max 27273042316900
+ * @group Drawings
  */
 type PositiveCoordinate = number;
 
 /**
  * Describes the length and width properties for how far drawing element should extend, in EMUs.
+ *
+ * @group Drawings
  */
 type Extent = {
     /** Horizontal size (X-axis). */
@@ -397,13 +431,16 @@ type Extent = {
  *
  * @min -27273042329600
  * @max 27273042316900
+ * @group Drawings
  */
 type EmuValue = number;
 
 /**
  * 2D position in EMUs.
  *
-z * Represents a point in 2D space using absolute coordinates measured in EMUs.
+ * Represents a point in 2D space using absolute coordinates measured in EMUs.
+ *
+ * @group Drawings
  */
 type Point = {
     /** Horizontal position (X-axis). */
@@ -414,6 +451,8 @@ type Point = {
 
 /**
  * Specifies an absolute anchor placeholder for a group, a shape, or a drawing element.
+ *
+ * @group Drawings
  */
 type GraphicAnchorAbsolute = {
     /** Type discriminator for an absolute anchor. */
@@ -426,6 +465,8 @@ type GraphicAnchorAbsolute = {
 
 /**
  * Specifies a point in the cell grid.
+ *
+ * @group Drawings
  */
 type CellOffset = {
     /** The row in which the point occurs, 1 indexed. */
@@ -440,6 +481,8 @@ type CellOffset = {
 
 /**
  * Specifies a one cell anchor placeholder for a group, a shape, or a drawing element.
+ *
+ * @group Drawings
  */
 type GraphicAnchorOneCell = {
     /** Type discriminator for a one-cell anchor. */
@@ -452,6 +495,8 @@ type GraphicAnchorOneCell = {
 
 /**
  * Specifies a two-cell anchor placeholder for a group, a shape, or a drawing element.
+ *
+ * @group Drawings
  */
 type GraphicAnchorTwoCell = {
     /** Type discriminator for a two-cell anchor. */
@@ -464,11 +509,15 @@ type GraphicAnchorTwoCell = {
 
 /**
  * Specifies an anchor placeholder for a group, a shape, or a drawing element.
+ *
+ * @group Drawings
  */
 type GraphicAnchor = GraphicAnchorAbsolute | GraphicAnchorOneCell | GraphicAnchorTwoCell;
 
 /**
  * Represents a percentage of a whole, usually [0-100].
+ *
+ * @group Drawings
  */
 type Percentage = number;
 
@@ -477,6 +526,8 @@ type Percentage = number;
  *
  * Defines a rectangle using relative offsets from each edge, expressed as percentages
  * of the parent rectangle's dimensions.
+ *
+ * @group Drawings
  */
 type RelativeRect = {
     /** Top edge offset as percentage from top. */
@@ -491,6 +542,8 @@ type RelativeRect = {
 
 /**
  * Specifies the direction(s) in which to flip a source image while tiling.
+ *
+ * @group Drawings
  */
 type FlipAxis = 'none' | 'x' | 'xy' | 'y';
 
@@ -510,6 +563,8 @@ type FlipAxis = 'none' | 'x' | 'xy' | 'y';
  * | `t`   | Top center     |
  * | `tl`  | Top left       |
  * | `tr`  | Top right      |
+ *
+ * @group Drawings
  */
 type RectAlignment = 'b' | 'bl' | 'br' | 'ctr' | 'l' | 'r' | 't' | 'tl' | 'tr';
 
@@ -518,6 +573,8 @@ type RectAlignment = 'b' | 'bl' | 'br' | 'ctr' | 'l' | 'r' | 't' | 'tl' | 'tr';
  *
  * Defines how an image should be repeated (tiled) when used as a fill,
  * including scaling, alignment, offset, and flip transformations.
+ *
+ * @group Drawings
  */
 type Tile = {
     /** Additional horizontal offset after alignment, in EMUs. */
@@ -542,6 +599,8 @@ type Tile = {
  *
  * Defines a fill using an embedded or linked image, with options for
  * tiling, stretching, cropping, and transparency.
+ *
+ * @group Drawings
  */
 type BlipFill = {
     /** Type discriminator for blip (image) fills. */
@@ -582,6 +641,8 @@ type BlipFill = {
  *
  * Positive angles are clockwise (i.e., towards the positive y axis);
  * negative angles are counter-clockwise (i.e., towards the negative y axis).
+ *
+ * @group Drawings
  */
 type DmlAngle = number;
 
@@ -590,6 +651,7 @@ type DmlAngle = number;
  *
  * @see {@link https://www.w3.org/TR/css-color-4/#hex-notation | CSS hexadecimal notation spec}
  * @pattern ^#([a-fA-F0-9]{3,4}|([a-fA-F0-9][a-fA-F0-9]){3,4})$
+ * @group Workbooks
  */
 type Color = `#${string}`;
 
@@ -598,6 +660,8 @@ type Color = `#${string}`;
  *
  * Defines a color transition point within a gradient fill,
  * specifying both the position and color at that point.
+ *
+ * @group Drawings
  */
 type GradientColorStop = {
     /**
@@ -617,6 +681,8 @@ type GradientColorStop = {
  *
  * Defines a gradient fill that transitions between colors along a straight line,
  * with configurable angle, flip behavior, and color stops.
+ *
+ * @group Drawings
  */
 type GradientLinearFill = {
     /** Type discriminator for linear gradient fills. */
@@ -640,6 +706,8 @@ type GradientLinearFill = {
  * - 'circle': Radial gradient emanating from center in a circular pattern.
  * - 'rect': Gradient following rectangular boundaries from center outward.
  * - 'shape': Gradient following the actual contour/outline of the shape.
+ *
+ * @group Drawings
  */
 type PathFillType = 'circle' | 'rect' | 'shape';
 
@@ -648,6 +716,8 @@ type PathFillType = 'circle' | 'rect' | 'shape';
  *
  * Defines a gradient fill that radiates from a center point or follows
  * the shape's contour, creating circular, rectangular, or shape-based gradients.
+ *
+ * @group Drawings
  */
 type GradientPathFill = {
     /** Type discriminator for path gradient fills. */
@@ -668,6 +738,8 @@ type GradientPathFill = {
  * Group fill.
  *
  * Declares that the element is part of a group and should inherit the fill properties of the group.
+ *
+ * @group Drawings
  */
 type GroupFill = {
     /** Type discriminator for group fills. */
@@ -678,6 +750,8 @@ type GroupFill = {
  * No fill.
  *
  * Declares that the element should not be filled.
+ *
+ * @group Drawings
  */
 type NoFill = {
     /** Type discriminator for none-fills. */
@@ -686,6 +760,8 @@ type NoFill = {
 
 /**
  * Pattern fill style presets.
+ *
+ * @group Drawings
  */
 type FillPatternStyle = 'pct5' | 'pct10' | 'pct20' | 'pct25' | 'pct30' | 'pct40' | 'pct50' | 'pct60' | 'pct70' | 'pct75' | 'pct80' | 'pct90' | 'ltHorz' | 'ltVert' | 'dkHorz' | 'dkVert' | 'narHorz' | 'narVert' | 'dashHorz' | 'dashVert' | 'ltDnDiag' | 'ltUpDiag' | 'dkDnDiag' | 'dkUpDiag' | 'wdDnDiag' | 'wdUpDiag' | 'dashDnDiag' | 'dashUpDiag' | 'smCheck' | 'lgCheck' | 'smGrid' | 'lgGrid' | 'dotGrid' | 'smConfetti' | 'lgConfetti' | 'horzBrick' | 'diagBrick' | 'solidDmnd' | 'openDmnd' | 'dotDmnd' | 'plaid' | 'sphere' | 'weave' | 'divot' | 'shingle' | 'wave' | 'trellis' | 'zigZag' | 'cross' | 'horz' | 'vert' | 'dnDiag' | 'upDiag' | 'diagCross';
 
@@ -694,6 +770,8 @@ type FillPatternStyle = 'pct5' | 'pct10' | 'pct20' | 'pct25' | 'pct30' | 'pct40'
  *
  * Defines a fill using a repeating pattern (dots, stripes, crosshatch, etc.)
  * with configurable foreground and background colors.
+ *
+ * @group Drawings
  */
 type PatternFill = {
     /** Type discriminator for pattern fills. */
@@ -710,6 +788,8 @@ type PatternFill = {
  * Solid color fill.
  *
  * Defines a fill using a single uniform color with no gradients, patterns, or images.
+ *
+ * @group Drawings
  */
 type SolidFill = {
     /** Type discriminator for solid fills. */
@@ -718,10 +798,17 @@ type SolidFill = {
     bg?: Color;
 };
 
+/**
+ * Union type representing all possible fill types for shapes.
+ *
+ * @group Drawings
+ */
 type Fill = PatternFill | SolidFill | GradientLinearFill | GradientPathFill | GroupFill | NoFill | BlipFill;
 
 /**
  * A dash stop primitive consisting of a dash and a space.
+ *
+ * @group Drawings
  */
 type DashStop = {
     /**
@@ -745,6 +832,8 @@ type DashStop = {
  * | `inside` | Stroke is drawn inside the path.
  *
  * These have been altered from DrawingML which used "ctr" for `center`, and "in" for `inside`.
+ *
+ * @group Drawings
  */
 type LineAlignment = 'center' | 'inside';
 
@@ -759,6 +848,8 @@ type LineAlignment = 'center' | 'inside';
  *
  * These have been altered from DrawingML which used "flat" for `butt`, "rnd" for `round`,
  * and "sq" for `square`.
+ *
+ * @group Drawings
  */
 type LineCapType = 'butt' | 'rnd' | 'sq';
 
@@ -772,19 +863,29 @@ type LineCapType = 'butt' | 'rnd' | 'sq';
  * | `thickThin` | Double lines: one thick, one thin
  * | `thinThick` | Double lines: one thin, one thick
  * | `tri`       | Three lines: thin, thick, thin
+ *
+ * @group Drawings
  */
 type LineCompoundType = 'dbl' | 'sng' | 'thickThin' | 'thinThick' | 'tri';
 
 /**
  * Line ending decoration size: Large, medium, small.
+ *
+ * @group Drawings
  */
 type LineEndSize = 'lg' | 'med' | 'sm';
 
-/** Line ending shape type. */
+/**
+ * Line ending shape type.
+ *
+ * @group Drawings
+ */
 type LineEndType = 'arrow' | 'diamond' | 'none' | 'oval' | 'stealth' | 'triangle';
 
 /**
  * Defines a line ending decoration.
+ *
+ * @group Drawings
  */
 type LineEnd = {
     /**
@@ -807,6 +908,8 @@ type LineEnd = {
 /**
  * Defines the shape to be used at the corners of a stroked path.
  * These are equivalent to their CSS/SVG linejoin value counterparts.
+ *
+ * @group Drawings
  */
 type LineJoinType = 'bevel' | 'round' | 'miter';
 
@@ -826,6 +929,8 @@ type LineJoinType = 'bevel' | 'round' | 'miter';
  * | `sysDashDot`    | Equivalent to SVG dashArray of `[3,1,1,1]`
  * | `sysDashDotDot` | Equivalent to SVG dashArray of `[3,1,1,1,1,1,1]`
  * | `sysDot`        | Equivalent to SVG dashArray of `[1,1]`
+ *
+ * @group Drawings
  */
 type LineStyle = 'dash' | 'dashDot' | 'dot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'solid' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot' | 'sysDot';
 
@@ -834,6 +939,8 @@ type LineStyle = 'dash' | 'dashDot' | 'dot' | 'lgDash' | 'lgDashDot' | 'lgDashDo
  *
  * Defines the visual appearance of lines and shape outlines, including
  * stroke style, width, caps, joins, and decorative line ends (arrows).
+ *
+ * @group Drawings
  */
 type Line = {
     /** Compound line type for creating multi-stroke effects. */
@@ -873,38 +980,60 @@ type Line = {
     tail?: LineEnd;
 };
 
-/** An identifier for a geometry guide */
+/**
+ * An identifier for a geometry guide.
+ *
+ * @group Drawings
+ */
 type GeomGuideName = string;
 
+/**
+ * Defines the type of an adjust coordinate, which can be either an {@link EmuValue} or a
+ * {@link GeomGuideName}.
+ *
+ * @group Drawings
+ */
 type AdjustCoordinate = EmuValue | GeomGuideName;
 
 /**
  * A path command to draw an elliptical arc to an endpoint.
+ *
+ * @group Drawings
  */
 type ArcToCommand = ['A', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
 
 /**
  * A path command to close the current subpath by drawing a line to the starting point.
+ *
+ * @group Drawings
  */
 type CloseCommand = ['Z'];
 
 /**
  * A path command to draw a cubic Bézier curve to an endpoint.
+ *
+ * @group Drawings
  */
 type CubicBezierToCommand = ['C', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
 
 /**
  * A path command to draw a line from the current position to a new one.
+ *
+ * @group Drawings
  */
 type LineToCommand = ['L', AdjustCoordinate, AdjustCoordinate];
 
 /**
  * A path command to move pen to a new position without drawing.
+ *
+ * @group Drawings
  */
 type MoveToCommand = ['M', AdjustCoordinate, AdjustCoordinate];
 
 /**
  * A path command to draw a quadratic Bézier curve to an endpoint.
+ *
+ * @group Drawings
  */
 type QuadraticBezierToCommand = ['Q', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
 
@@ -912,6 +1041,8 @@ type QuadraticBezierToCommand = ['Q', AdjustCoordinate, AdjustCoordinate, Adjust
  * Path command for shape geometry.
  *
  * Defines a single drawing command in a shape path, using a subset of SVG path commands.
+ *
+ * @group Drawings
  */
 type PathCommand = ArcToCommand | CloseCommand | CubicBezierToCommand | LineToCommand | MoveToCommand | QuadraticBezierToCommand;
 
@@ -926,6 +1057,8 @@ type PathCommand = ArcToCommand | CloseCommand | CubicBezierToCommand | LineToCo
  * | `lightenLess` | slightly lighter shaded color applied to its fill.
  * | `none`        | should have no fill.
  * | `norm`        | should have a normally shaded color applied to its fill.
+ *
+ * @group Drawings
  */
 type PathFillMode = 'none' | 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess';
 
@@ -934,6 +1067,8 @@ type PathFillMode = 'none' | 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'da
  *
  * Defines a single path within a custom shape's geometry, including
  * the path commands and rendering properties for that path.
+ *
+ * @group Drawings
  */
 type Path = {
     /** Whether this path should be stroked (outlined). */
@@ -960,6 +1095,8 @@ type Path = {
 
 /**
  * Defines an inset or internal margins for a text box within a shape.
+ *
+ * @group Drawings
  */
 type InsetRect = {
     /**
@@ -984,7 +1121,11 @@ type InsetRect = {
     r?: EmuValue;
 };
 
-/** A paragraph of text. */
+/**
+ * A paragraph of text.
+ *
+ * @group Drawings
+ */
 type Paragraph = {
     /** Text content. */
     text: string;
@@ -1002,6 +1143,8 @@ type Paragraph = {
  * | `b`    | Bottom aligned                          |
  * | `dist` | Distributed (evenly spaced lines)       |
  * | `just` | Justified (stretched to fill container) |
+ *
+ * @group Drawings
  */
 type TextAnchoring = 't' | 'b' | 'ctr' | 'dist' | 'just';
 
@@ -1014,6 +1157,8 @@ type TextAnchoring = 't' | 'b' | 'ctr' | 'dist' | 'just';
  * |------------|-----------------------------------------------|
  * | `overflow` | Text extends beyond container bounds          |
  * | `clip`     | Text is clipped at container edge             |
+ *
+ * @group Drawings
  */
 type TextHorzOverflow = 'overflow' | 'clip';
 
@@ -1029,6 +1174,8 @@ type TextHorzOverflow = 'overflow' | 'clip';
  * | `wordArtVertRtl` | Vertical WordArt should be shown from right to left.
  * | `eaVert`         | Some fonts are rotated by 90° while some (East Asian) are shown vertically.
  * | `mongolianVert`  | `eaVert` but the text flows top down then LEFT RIGHT, instead of RIGHT LEFT.
+ *
+ * @group Drawings
  */
 type TextVerticalType = 'horz' | 'vert' | 'vert270' | 'wordArtVert' | 'eaVert' | 'mongolianVert' | 'wordArtVertRtl';
 
@@ -1042,6 +1189,8 @@ type TextVerticalType = 'horz' | 'vert' | 'vert270' | 'wordArtVert' | 'eaVert' |
  * | `overflow` | Text extends beyond container bounds          |
  * | `ellipsis` | Text is truncated with ellipsis indicator     |
  * | `clip`     | Text is clipped at container edge             |
+ *
+ * @group Drawings
  */
 type TextVertOverflow = 'overflow' | 'ellipsis' | 'clip';
 
@@ -1054,6 +1203,8 @@ type TextVertOverflow = 'overflow' | 'ellipsis' | 'clip';
  * |----------|---------------------------------------------|
  * | `none`   | No wrapping (text runs on a single line)    |
  * | `square` | Wrap text at container boundaries           |
+ *
+ * @group Drawings
  */
 type TextWrapping = 'none' | 'square';
 
@@ -1062,6 +1213,8 @@ type TextWrapping = 'none' | 'square';
  *
  * Defines the text content within a shape, including paragraphs and formatting properties
  * such as alignment, overflow behavior, columns, rotation, and insets.
+ *
+ * @group Drawings
  */
 type TextBody = {
     /**
@@ -1132,6 +1285,13 @@ type TextBody = {
     p: Paragraph[];
 };
 
+/**
+ * Represents a point that can be adjusted in a shape. Each coordinate (x and y) can be defined as
+ * an {@link AdjustCoordinate}, which allows for flexible positioning based on the shape's
+ * dimensions and other factors.
+ *
+ * @group Drawings
+ */
 type AdjustPoint = {
     x: AdjustCoordinate;
     y: AdjustCoordinate;
@@ -1142,6 +1302,8 @@ type AdjustPoint = {
  *
  * Defines an interactive handle that can be dragged to adjust shape geometry
  * using polar coordinates (angle and radius from a center point).
+ *
+ * @group Drawings
  */
 type AdjustValueHandlePolar = {
     /** Type discriminator for polar adjustment handles. */
@@ -1167,6 +1329,8 @@ type AdjustValueHandlePolar = {
  *
  * Defines an interactive handle that can be dragged to adjust shape geometry
  * using Cartesian coordinates (X and Y positions).
+ *
+ * @group Drawings
  */
 type AdjustValueHandleXY = {
     /** Type discriminator for XY adjustment handles. */
@@ -1203,12 +1367,16 @@ type AdjustValueHandleXY = {
  * | `invGray` (Inverse Gray)       | Rendered with inverse gray coloring
  * | `ltGray` (Light Gray)          | Rendered with light gray coloring
  * | `white` (White)                | Rendered within white coloring
+ *
+ * @group Drawings
  */
 type BlackWhiteMode = 'clr' | 'auto' | 'gray' | 'ltGray' | 'invGray' | 'grayWhite' | 'blackGray' | 'blackWhite' | 'black' | 'white' | 'hidden';
 
 /**
  * Defines a connection point on a shape where other shapes can connect.
  * Connection points are used for connecting shapes with connectors/lines in diagrams.
+ *
+ * @group Drawings
  */
 type ConnectionPoint = {
     /** The position of the connection point on the shape */
@@ -1220,6 +1388,11 @@ type ConnectionPoint = {
     ang?: DmlAngle | GeomGuideName;
 };
 
+/**
+ * Represents the index of a font style in a drawing.
+ *
+ * @group Drawings
+ */
 type FontStyleIndex = 'major' | 'minor' | 'none';
 
 /**
@@ -1227,6 +1400,8 @@ type FontStyleIndex = 'major' | 'minor' | 'none';
  *
  * Defines a named calculation point that can be referenced in shape paths
  * and used to create parameterized, adjustable geometry.
+ *
+ * @group Drawings
  */
 type GuidePoint = {
     /**
@@ -1244,6 +1419,8 @@ type GuidePoint = {
  *
  * Defines the inset rectangle within a shape where text should be positioned,
  * specified using adjustable coordinates relative to the shape's geometry.
+ *
+ * @group Drawings
  */
 type ShapeRect = {
     /** Top edge inset from shape bounds. */
@@ -1258,6 +1435,8 @@ type ShapeRect = {
 
 /**
  * Transform directions to be applied to drawn graphic objects.
+ *
+ * @group Drawings
  */
 type Xfrm = {
     /**
@@ -1278,6 +1457,9 @@ type Xfrm = {
     ext?: Extent;
 };
 
+/**
+ * @group Drawings
+ */
 type ShapeStyle = {
     line?: {
         color: Color;
@@ -1302,6 +1484,8 @@ type ShapeStyle = {
  *
  * Defines the complete visual styling and custom geometry for a shape,
  * including fill, line, transformation, custom paths, and interactive handles.
+ *
+ * @group Drawings
  */
 type Shape = {
     /** 2D transformation (position, rotation, scale). */
@@ -1332,6 +1516,8 @@ type Shape = {
 
 /**
  * Bitmap graphic / Picture.
+ *
+ * @group Drawings
  */
 type GraphicBitmap = {
     /** Type discriminator for bitmap graphics. */
@@ -1370,6 +1556,8 @@ type GraphicBitmap = {
 
 /**
  * A chart or plot.
+ *
+ * @group Drawings
  */
 type GraphicChart = {
     /** Type discriminator for a chart. */
@@ -1389,6 +1577,8 @@ type GraphicChart = {
  *
  * Represents a connector or line shape that connects two other shapes,
  * typically used for creating diagrams, flowcharts, and organizational charts.
+ *
+ * @group Drawings
  */
 type GraphicConnectionShape = {
     /** Type discriminator for connection shapes. */
@@ -1407,6 +1597,8 @@ type GraphicConnectionShape = {
 
 /**
  * Transform directions to be applied to group objects.
+ *
+ * @group Drawings
  */
 type XfrmGroup = Xfrm & {
     /** Child offset - position of child elements within a group. */
@@ -1420,6 +1612,8 @@ type XfrmGroup = Xfrm & {
  *
  * Represents a collection of graphic objects grouped together as a single unit,
  * allowing them to be transformed, moved, and manipulated collectively.
+ *
+ * @group Drawings
  */
 type GraphicGroup = {
     /** Type discriminator for group shapes. */
@@ -1439,6 +1633,8 @@ type GraphicGroup = {
  *
  * Represents a standard geometric shape (rectangle, circle, arrow, etc.)
  * with customizable geometry, styling, and text content.
+ *
+ * @group Drawings
  */
 type GraphicShape = {
     /** Type discriminator for basic shapes. */
@@ -1455,7 +1651,11 @@ type GraphicShape = {
     text?: TextBody;
 };
 
-/** A graphic element.  */
+/**
+ * A graphic element.
+ *
+ * @group Drawings
+ */
 type Graphic = GraphicChart | GraphicBitmap | GraphicShape | GraphicConnectionShape | GraphicGroup;
 
 /**
@@ -1463,6 +1663,8 @@ type Graphic = GraphicChart | GraphicBitmap | GraphicShape | GraphicConnectionSh
  *
  * A drawing is a collection of any graphic objects that should be displayed in a worksheet as
  * well as information on how they are positioned within the cell-grid.
+ *
+ * @group Drawings
  */
 type Drawing = {
     /** Defines how the drawing is placed onto a worksheet's cell-grid. */
@@ -1474,6 +1676,8 @@ type Drawing = {
 /**
  * The style to use when drawing a cell border. If the worksheet's zoom factor is changed the width
  * of the border is expected to stay the same.
+ *
+ * @group Workbooks
  */
 type BorderStyle = 
 /** No border is drawn.*/
@@ -1510,6 +1714,8 @@ type BorderStyle =
 
 /**
  * Specifies the horizontal alignment of content (text) within a container (cell).
+ *
+ * @group Workbooks
  */
 type HAlign = 
 /**
@@ -1545,19 +1751,29 @@ type HAlign =
 /**
  * The style of fill pattern used for a cell background. If the worksheets zoom factor is changed
  * the pixel scale of the pattern is still expected to stay the same.
+ *
+ * @group Workbooks
  */
 type PatternStyle = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';
 
 /**
  * Which type of underline to use when rendering text.
+ *
+ * @group Workbooks
  */
 type Underline = 'none' | 'single' | 'singleAccounting' | 'double' | 'doubleAccounting';
 
-/** Vertical alignment of a cell content. */
+/**
+ * Vertical alignment of a cell content.
+ *
+ * @group Workbooks
+ */
 type VAlign = 'bottom' | 'top' | 'center' | 'justify' | 'distributed';
 
 /**
  * Style rules that specify the visual presentation of a cell.
+ *
+ * @group Workbooks
  */
 type Style = {
     /**
@@ -1688,11 +1904,17 @@ type Style = {
     numberFormat?: string;
 };
 
-/** Describes the type of values found in the cells of a table column. */
+/**
+ * Describes the type of values found in the cells of a table column.
+ *
+ * @group Workbooks
+ */
 type TableColumnDataType = 'text' | 'number' | 'boolean' | 'datetime' | 'unknown';
 
 /**
  * Describes a column within a table.
+ *
+ * @group Workbooks
  */
 type TableColumn = {
     /**
@@ -1714,12 +1936,18 @@ type TableColumn = {
     formula?: string;
 };
 
-/** Excel's built-in table style names. */
+/**
+ * Excel's built-in table style names.
+ *
+ * @group Workbooks
+ */
 type TableStyleName = 'TableStyleDark1' | 'TableStyleDark2' | 'TableStyleDark3' | 'TableStyleDark4' | 'TableStyleDark5' | 'TableStyleDark6' | 'TableStyleDark7' | 'TableStyleDark8' | 'TableStyleDark9' | 'TableStyleDark10' | 'TableStyleDark11' | 'TableStyleLight1' | 'TableStyleLight2' | 'TableStyleLight3' | 'TableStyleLight4' | 'TableStyleLight5' | 'TableStyleLight6' | 'TableStyleLight7' | 'TableStyleLight8' | 'TableStyleLight9' | 'TableStyleLight10' | 'TableStyleLight11' | 'TableStyleLight12' | 'TableStyleLight13' | 'TableStyleLight14' | 'TableStyleLight15' | 'TableStyleLight16' | 'TableStyleLight17' | 'TableStyleLight18' | 'TableStyleLight19' | 'TableStyleLight20' | 'TableStyleLight21' | 'TableStyleMedium1' | 'TableStyleMedium2' | 'TableStyleMedium3' | 'TableStyleMedium4' | 'TableStyleMedium5' | 'TableStyleMedium6' | 'TableStyleMedium7' | 'TableStyleMedium8' | 'TableStyleMedium9' | 'TableStyleMedium10' | 'TableStyleMedium11' | 'TableStyleMedium12' | 'TableStyleMedium13' | 'TableStyleMedium14' | 'TableStyleMedium15' | 'TableStyleMedium16' | 'TableStyleMedium17' | 'TableStyleMedium18' | 'TableStyleMedium19' | 'TableStyleMedium20' | 'TableStyleMedium21' | 'TableStyleMedium22' | 'TableStyleMedium23' | 'TableStyleMedium24' | 'TableStyleMedium25' | 'TableStyleMedium26' | 'TableStyleMedium27' | 'TableStyleMedium28';
 
 /**
  * Describes which style is used to display this table, and specifies which portions of the table
  * have which styles applied.
+ *
+ * @group Workbooks
  */
 type TableStyle = {
     /**
@@ -1763,6 +1991,7 @@ type TableStyle = {
  * calculated columns.
  *
  * @see {@link https://support.microsoft.com/office/f5ed2452-2337-4f71-bed3-c8ae6d2b276e}
+ * @group Workbooks
  */
 type Table = {
     /**
@@ -1806,128 +2035,1718 @@ type Table = {
 };
 
 /**
- * Directions on how formulas should be recalculated in the workbook.
+ * The axis a pivot field can be placed on.
+ *
+ * @group PivotTables
  */
-type CalcProps = {
+type PivotFieldAxis = 'row' | 'col' | 'page';
+
+/**
+ * The axis a pivot area targets. Extends {@link PivotFieldAxis} with an additional `'values'`
+ * option for the data-values axis.
+ *
+ * @group PivotTables
+ */
+type PivotAreaAxis = PivotFieldAxis | 'values';
+
+/**
+ * A reference within a pivot area, identifying specific field items that define the area's scope.
+ *
+ * @group PivotTables
+ */
+type PivotAreaReference = {
     /**
-     * Specifies whether an attempt should be made to calculate formulas that contain circular
-     * references. Defaults to `false` in Excel.
+     * Index of the field this reference applies to.
+     * The special value `4294967294` (0xFFFFFFFE) refers to the data (values) field.
      */
-    iterate: boolean;
+    field?: integer;
     /**
-     * The maximum number of calculation iterations, when {@link CalcProps.iterate} is `true`.
-     * Defaults to `100` in Excel.
+     * Whether this reference participates in the selection. When false, the reference
+     * constrains the area without being selected itself.
+     *
+     * @default true
      */
-    iterateCount: integer;
+    selected?: boolean;
     /**
-     * When a calculation iteration results in an absolute change that is less than iterateDelta,
-     * then no further iterations should be attempted. Defaults to `0.001` in Excel.
+     * Whether item indices are positional (absolute row/column position)
+     * rather than field-item-based.
+     *
+     * @default false
      */
-    iterateDelta: number;
+    byPosition?: boolean;
     /**
-     * Which of the two date systems the workbook uses. 1900 is the default.
+     * Whether the reference is relative to the pivot table's origin.
      *
-     * @see {@link https://support.microsoft.com/office/e7fe7167-48a9-4b96-bb53-5612a800b487 | Date systems in Excel}
+     * @default false
      */
-    epoch?: 1900 | 1904;
+    relative?: boolean;
     /**
-     * The calculation mode for the workbook.
+     * Whether the default subtotal is included.
      *
-     * - `"auto"` (default when absent): recalculate all formulas automatically.
-     * - `"autoNoTable"`: recalculate automatically but exclude data tables.
-     * - `"manual"`: formulas are only recalculated when explicitly triggered.
+     * @default false
+     */
+    defaultSubtotal?: boolean;
+    /**
+     * Whether the sum subtotal is included.
      *
-     * @defaultValue "auto"
+     * @default false
      */
-    calcMode?: 'auto' | 'autoNoTable' | 'manual';
-};
-
-/**
- * A collection of default properties that apply to cells, rows, or columns in the worksheet.
- */
-type WorksheetDefaults = {
-    /** Default width of the UI-grid column. */
-    colWidth: PixelValue;
-    /** Default height of the UI-grid height. */
-    rowHeight: PixelValue;
-};
-
-/**
- * Visual scale (aka zoom level, aka magnification) applied when displaying a worksheet.
- *
- * Each of the three layouts has its own scale. A scale is represented as a percentage, with `100`
- * (100%) being the default 1:1 scale. When a layout has no explicit scale, use 100%.
- */
-type WorksheetLayoutScales = {
+    sumSubtotal?: boolean;
     /**
-     * Zoom level for normal view.
+     * Whether the countA subtotal is included.
      *
-     * @min 10
-     * @max 400
-     * @defaultValue 100
-     * */
-    normal?: integer;
+     * @default false
+     */
+    countASubtotal?: boolean;
     /**
-     * Zoom level for page layout view.
+     * Whether the average subtotal is included.
      *
-     * @min 10
-     * @max 400
-     * @defaultValue 100
+     * @default false
      */
-    pageLayout?: integer;
+    avgSubtotal?: boolean;
     /**
-     * Zoom level for page break preview (aka sheet layout view).
+     * Whether the max subtotal is included.
      *
-     * @min 10
-     * @max 400
-     * @defaultValue 100
+     * @default false
      */
-    pageBreakPreview?: integer;
+    maxSubtotal?: boolean;
+    /**
+     * Whether the min subtotal is included.
+     *
+     * @default false
+     */
+    minSubtotal?: boolean;
+    /**
+     * Whether the product subtotal is included.
+     *
+     * @default false
+     */
+    productSubtotal?: boolean;
+    /**
+     * Whether the count subtotal is included.
+     *
+     * @default false
+     */
+    countSubtotal?: boolean;
+    /**
+     * Whether the standard deviation subtotal is included.
+     *
+     * @default false
+     */
+    stdDevSubtotal?: boolean;
+    /**
+     * Whether the population standard deviation subtotal is included.
+     *
+     * @default false
+     */
+    stdDevPSubtotal?: boolean;
+    /**
+     * Whether the variance subtotal is included.
+     *
+     * @default false
+     */
+    varSubtotal?: boolean;
+    /**
+     * Whether the population variance subtotal is included.
+     *
+     * @default false
+     */
+    varPSubtotal?: boolean;
+    /** Indices of the field items included in this reference. */
+    itemIndices?: integer[];
 };
 
 /**
- * A worksheet view.
- *
- * A worksheet view is a display configuration for a particular worksheet. Worksheet view settings
- * can include:
+ * The type of pivot area targeted.
  *
- * - Active cell
- * - Selected ranges
- * - View type (normal, page layout, or page break layout)
- * - Zoom level
+ * @group PivotTables
+ */
+type PivotAreaType = 'none' | 'normal' | 'data' | 'all' | 'origin' | 'button' | 'topRight';
+
+/**
+ * Describes a region of a pivot table, used to target formatting, conditional formatting,
+ * and other area-specific features.
  *
- * Currently JSF does not include all available settings for a worksheet.
+ * @group PivotTables
  */
-type WorksheetView = {
+type PivotArea = {
     /**
-     * The id of the workbook view this worksheet view belongs to.
+     * The type of area.
      *
-     * This is a zero-based index of the workbook view, as stored in the {@link Workbook.views} array.
+     * @default 'normal'
+     */
+    type?: PivotAreaType;
+    /** The field index this area applies to. */
+    field?: integer;
+    /**
+     * Whether the area applies only to data cells (excluding labels).
      *
-     * Within a single worksheet, each view must reference a distinct workbook view (i.e. no two views
-     * in the same worksheet can share the same `workbookView` id). However, views from different
-     * worksheets may reference the same workbook view.
+     * @default true
      */
-    workbookView: integer;
-    /** Cell that is selected by default when the sheet is visible. */
-    activeCell?: CellId;
-    /** Ranges of cells that are selected by default when the sheet is visible. */
-    activeRanges?: CellRange[];
+    dataOnly?: boolean;
     /**
-     * The layout used to display the worksheet.
+     * Whether the area applies only to label cells (excluding data).
      *
-     * @defaultValue "normal"
+     * @default false
      */
-    activeLayout?: 'normal' | 'pageLayout' | 'pageBreakPreview';
+    labelOnly?: boolean;
     /**
-     * Scale (aka zoom level, aka magnification) applied when displaying a worksheet. Each different
-     * layout has its own scale.
+     * Whether the row grand total is included.
+     *
+     * @default false
      */
-    layoutScales?: WorksheetLayoutScales;
-};
+    grandRow?: boolean;
+    /**
+     * Whether the column grand total is included.
+     *
+     * @default false
+     */
+    grandCol?: boolean;
+    /**
+     * Whether item indices refer to cache field items rather than pivot field items.
+     *
+     * @default false
+     */
+    cacheIndex?: boolean;
+    /**
+     * Whether the area includes outline-mode items.
+     *
+     * @default true
+     */
+    outline?: boolean;
+    /** A cell reference offset relative to the pivot table's top-left corner. */
+    offset?: string;
+    /**
+     * Whether collapsed hierarchy levels are treated as subtotals.
+     *
+     * @default false
+     */
+    collapsedLevelsAreSubtotals?: boolean;
+    /** The axis this area targets. */
+    axis?: PivotAreaAxis;
+    /** The position of the field on its axis (0-based). */
+    fieldPosition?: integer;
+    /** References that narrow the area to specific field items. */
+    references?: PivotAreaReference[];
+};
+
+/**
+ * Comparison operator for a custom auto-filter criterion.
+ *
+ * @group PivotTables
+ */
+type PivotCustomFilterOperator = 'lessThan' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'greaterThanOrEqual' | 'greaterThan';
+
+/**
+ * A single criterion within a custom auto-filter, specifying an operator and comparison value.
+ *
+ * @group PivotTables
+ */
+type PivotCustomFilterCriterion = {
+    operator?: PivotCustomFilterOperator;
+    val?: string;
+};
+
+/**
+ * A filter column within an auto-filter, specifying the filter criteria for a single column.
+ *
+ * @group PivotTables
+ */
+type PivotAutoFilterColumn = {
+    /** The 0-based column index within the auto-filter range. */
+    colId: integer;
+    /** Top-10 filter: show top/bottom N items by count, percent, or sum. */
+    top10?: {
+        /**
+         * Whether to show the top items (true) or bottom items (false).
+         *
+         * @default true
+         */
+        top?: boolean;
+        /**
+         * Whether filtering is by percent (true) or count (false).
+         *
+         * @default false
+         */
+        percent?: boolean;
+        /** The number of items (or percent) to show. */
+        val: number;
+        /** The actual cutoff value used for filtering. */
+        filterVal?: number;
+    };
+    /** Custom filter criteria (up to two conditions with AND/OR logic). */
+    customFilters?: {
+        /**
+         * Whether the two filters are combined with AND (true) or OR (false).
+         *
+         * @default false
+         */
+        and?: boolean;
+        filters: PivotCustomFilterCriterion[];
+    };
+};
+
+/**
+ * The unit used for grouping a cache field's values.
+ *
+ * @group PivotTables
+ */
+type PivotGroupBy = 'range' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'quarters' | 'years';
+
+/**
+ * Range grouping properties that define how a cache field's values are grouped into intervals.
+ *
+ * @group PivotTables
+ */
+type PivotCacheRangePr = {
+    /**
+     * Whether the start value is determined automatically from source data.
+     *
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Whether the end value is determined automatically from source data.
+     *
+     * @default true
+     */
+    autoEnd?: boolean;
+    /**
+     * The grouping unit.
+     *
+     * @default 'range'
+     */
+    groupBy?: PivotGroupBy;
+    /** Start value for numeric range grouping. */
+    startNum?: number;
+    /** End value for numeric range grouping. */
+    endNum?: number;
+    /** Start date for date range grouping (ISO 8601 datetime string). */
+    startDate?: string;
+    /** End date for date range grouping (ISO 8601 datetime string). */
+    endDate?: string;
+    /**
+     * The interval size for each group.
+     *
+     * @default 1
+     */
+    groupInterval?: number;
+};
+
+/**
+ * A shared item value in a pivot cache field. Each item represents a unique value found in the
+ * source data for that field.
+ *
+ * @group PivotTables
+ */
+type PivotCacheSharedItem = PivotCacheSharedItemStr | PivotCacheSharedItemNum | PivotCacheSharedItemBool | PivotCacheSharedItemDate | PivotCacheSharedItemErr | PivotCacheSharedItemNil;
+/** A string shared item. @group PivotTables */
+type PivotCacheSharedItemStr = {
+    t: 's';
+    v: string;
+};
+/** A numeric shared item. @group PivotTables */
+type PivotCacheSharedItemNum = {
+    t: 'n';
+    v: number;
+};
+/** A boolean shared item. @group PivotTables */
+type PivotCacheSharedItemBool = {
+    t: 'b';
+    v: boolean;
+};
+/** A date shared item (ISO 8601 string). @group PivotTables */
+type PivotCacheSharedItemDate = {
+    t: 'd';
+    v: string;
+};
+/** An error shared item (e.g. `"#REF!"`). @group PivotTables */
+type PivotCacheSharedItemErr = {
+    t: 'e';
+    v: string;
+};
+/** An empty/missing shared item. @group PivotTables */
+type PivotCacheSharedItemNil = {
+    t: 'z';
+};
+
+/**
+ * Field grouping information that defines how a cache field's values are grouped.
+ *
+ * @group PivotTables
+ */
+type PivotCacheFieldGroup = {
+    /** Index of the parent grouped field (for multi-level grouping). */
+    par?: integer;
+    /** Index of the base (source) cache field that this grouping is derived from. */
+    base?: integer;
+    /** Range grouping properties (for date or numeric range grouping). */
+    rangePr?: PivotCacheRangePr;
+    /** Discrete grouping: maps each shared item index to its group index. */
+    discretePr?: integer[];
+    /** The group item labels, representing each group's display value. */
+    groupItems?: PivotCacheSharedItem[];
+};
+
+/**
+ * Metadata describing the type composition and value range of a cache field's data. These are
+ * redundant when {@link PivotCacheField.sharedItems} contains items (the metadata can be derived),
+ * but for fields whose data is stored only in records (no shared items), they preserve min/max
+ * and type information that would otherwise be lost.
+ *
+ * @group PivotTables
+ */
+type PivotCacheSharedItemsMeta = {
+    /**
+     * Whether the field contains blank (missing) values.
+     *
+     * @default false
+     */
+    containsBlank?: boolean;
+    /**
+     * Whether the field contains more than one data type (excluding blank and string).
+     *
+     * @default false
+     */
+    containsMixedTypes?: boolean;
+    /**
+     * Whether the field contains a mix of text and other types, or only text.
+     *
+     * @default true
+     */
+    containsSemiMixedTypes?: boolean;
+    /**
+     * Whether the field contains string values.
+     *
+     * @default true
+     */
+    containsString?: boolean;
+    /**
+     * Whether the field contains numeric values.
+     *
+     * @default false
+     */
+    containsNumber?: boolean;
+    /**
+     * Whether the field contains only integer numeric values (no fractions).
+     *
+     * @default false
+     */
+    containsInteger?: boolean;
+    /**
+     * Whether the field contains date values.
+     *
+     * @default false
+     */
+    containsDate?: boolean;
+    /**
+     * Whether the field contains non-date values.
+     *
+     * @default true
+     */
+    containsNonDate?: boolean;
+    /** The minimum numeric value in the field. */
+    minValue?: number;
+    /** The maximum numeric value in the field. */
+    maxValue?: number;
+    /** The minimum date value in the field (ISO 8601 datetime string). */
+    minDate?: string;
+    /** The maximum date value in the field (ISO 8601 datetime string). */
+    maxDate?: string;
+};
+
+/**
+ * Describes a field (column) in a pivot cache. Each cache field corresponds to a column in the
+ * source data range.
+ *
+ * @group PivotTables
+ */
+type PivotCacheField = {
+    /** The name of the field, typically matching the column header in the source data. */
+    name: string;
+    /**
+     * The unique values found in this field's source data. Used for item indexing in pivot cache
+     * records and pivot field items.
+     */
+    sharedItems?: PivotCacheSharedItem[];
+    /**
+     * Metadata about the shared items or record-level values for this field. When
+     * {@link sharedItems} is populated, this can be derived from the items; when absent, it
+     * preserves type/range information that would otherwise be lost.
+     */
+    sharedItemsMeta?: PivotCacheSharedItemsMeta;
+    /** The number format code for this field's values (e.g. `"General"`, `"#,##0"`). */
+    numFmt?: string;
+    /** A formula for a calculated field, expressed in A1-style notation. */
+    formula?: string;
+    /**
+     * Whether this field comes from the source database. When `false`, the field is a calculated
+     * field not present in the original data source.
+     *
+     * @default true
+     */
+    databaseField?: boolean;
+    /** Grouping information for this field (date ranges, numeric ranges, or discrete groups). */
+    fieldGroup?: PivotCacheFieldGroup;
+};
+
+/**
+ * A single value in a pivot cache record. Each record is an array of these values, one per cache
+ * field.
+ *
+ * Each value is either an inline {@link PivotCacheSharedItem} or an `{ x: integer }` shared item
+ * index, referring to an entry in the corresponding field's
+ * {@link PivotCacheField.sharedItems | sharedItems} array.
+ *
+ * @group PivotTables
+ */
+type PivotCacheRecordValue = PivotCacheSharedItem | {
+    t: 'x';
+    v: integer;
+};
+
+/**
+ * A single record (row) of cached source data, with one value per cache field.
+ *
+ * @group PivotTables
+ */
+type PivotCacheRecord = PivotCacheRecordValue[];
+
+/**
+ * Shared properties for all pivot cache source types.
+ *
+ * @group PivotTables
+ */
+type PivotCacheBase = {
+    /**
+     * The fields (columns) in the cache, in source-data order. Each entry parallels the
+     * corresponding pivot table's {@link PivotTable.fields | fields} array by index.
+     */
+    fields: PivotCacheField[];
+    /**
+     * The cached data records. Each record is an array of values corresponding to the cache fields.
+     * When absent, the pivot table relies on the source data directly.
+     */
+    records?: PivotCacheRecord[];
+    /**
+     * Name of the user who last refreshed the cache.
+     */
+    refreshedBy?: string;
+    /**
+     * When the cache was last refreshed, as a serial date number (e.g. `39536.657`).
+     */
+    refreshedDate?: number;
+    /**
+     * Whether the cache is refreshed on file open.
+     *
+     * @default false
+     */
+    refreshOnLoad?: boolean;
+    /**
+     * Whether refresh is enabled for this cache.
+     *
+     * @default true
+     */
+    enableRefresh?: boolean;
+    /**
+     * Whether the cache definition is upgraded when refreshed.
+     *
+     * @default false
+     */
+    upgradeOnRefresh?: boolean;
+    /**
+     * Revision-tracking unique identifier. A GUID string like
+     * `"{93AACE53-8F3A-A04A-893A-A439866B3165}"` assigned by Excel 2014+ for revision tracking.
+     */
+    uid?: string;
+};
+
+/**
+ * One of the source ranges in a consolidation-source pivot cache.
+ *
+ * @group PivotTables
+ */
+type PivotCacheConsolidationRangeSet = {
+    /** The A1-style range reference. */
+    ref?: CellRange;
+    /** The sheet containing this range. */
+    sheet?: string;
+    /** Index into the first page field's items. */
+    i1?: integer;
+    /** Index into the second page field's items. */
+    i2?: integer;
+    /** Index into the third page field's items. */
+    i3?: integer;
+    /** Index into the fourth page field's items. */
+    i4?: integer;
+};
+
+/**
+ * Describes the source of a pivot cache's data when it consolidates multiple ranges (via the
+ * legacy PivotTable Wizard).
+ *
+ * @group PivotTables
+ */
+type PivotCacheConsolidationSource = {
+    /**
+     * Whether Excel automatically creates page fields.
+     *
+     * @default true
+     */
+    autoPage?: boolean;
+    /** Page fields. Each inner array is one page field's item names. Up to 4. */
+    pages?: string[][];
+    /** The source ranges being consolidated. */
+    rangeSets: PivotCacheConsolidationRangeSet[];
+};
+
+/**
+ * A pivot cache whose source data consolidates multiple ranges.
+ *
+ * @group PivotTables
+ */
+type PivotCacheConsolidation = PivotCacheBase & {
+    sourceType: 'consolidation';
+    consolidation: PivotCacheConsolidationSource;
+};
+
+/**
+ * A pivot cache whose source data comes from an external data connection.
+ *
+ * @group PivotTables
+ */
+type PivotCacheExternal = PivotCacheBase & {
+    sourceType: 'external';
+    connectionId: integer;
+};
+
+/**
+ * A pivot cache whose source data comes from scenarios.
+ *
+ * @group PivotTables
+ */
+type PivotCacheScenario = PivotCacheBase & {
+    sourceType: 'scenario';
+};
+
+/**
+ * A worksheet range source, identified by a cell range and sheet name.
+ *
+ * @group PivotTables
+ */
+type PivotCacheWorksheetSourceRange = {
+    /** Type discriminator for a worksheet range source. */
+    type: 'range';
+    /** The A1-style range reference to the source data, including headers. */
+    ref: CellRange;
+    /** The name of the sheet containing the source data. */
+    sheet?: string;
+};
+/**
+ * A named source (defined name or table), optionally scoped to a sheet.
+ *
+ * @group PivotTables
+ */
+type PivotCacheWorksheetSourceName = {
+    /** Type discriminator for a worksheet name source. */
+    type: 'name';
+    /** A defined name or table name that identifies the source data. */
+    name: string;
+    /** The name of the sheet, when `name` is a sheet-scoped defined name. */
+    sheet?: string;
+};
+/**
+ * Describes the source of a pivot cache's data when the source is a worksheet range or named
+ * range/table. Either `ref` + `sheet` identifies a cell range, or `name` identifies a defined
+ * name or table (with optional `sheet` for sheet-scoped names).
+ *
+ * @group PivotTables
+ */
+type PivotCacheWorksheetSource = PivotCacheWorksheetSourceRange | PivotCacheWorksheetSourceName;
+
+/**
+ * A pivot cache whose source data comes from a worksheet range or named range/table.
+ *
+ * @group PivotTables
+ */
+type PivotCacheWorksheet = PivotCacheBase & {
+    sourceType: 'worksheet';
+    worksheetSource: PivotCacheWorksheetSource;
+};
+
+/**
+ * A pivot cache stores a snapshot of the source data used by one or more pivot tables. It contains
+ * field definitions, shared item pools, and optionally the full set of cached records.
+ *
+ * @group PivotTables
+ */
+type PivotCache = PivotCacheWorksheet | PivotCacheExternal | PivotCacheConsolidation | PivotCacheScenario;
+
+/**
+ * A calculated field definition in a pivot table. Calculated fields derive their values from a
+ * formula that references other cache fields.
+ *
+ * @group PivotTables
+ */
+type PivotCalculatedField = {
+    /** The name of the calculated field. */
+    name: string;
+    /** The formula expression that computes this field's values from other cache fields. */
+    formula: string;
+};
+
+/**
+ * The aggregation function applied to a data field's values.
+ *
+ * Beware of the `'count'` false cognate: here it means "count of non-empty values" (like the
+ * COUNTA worksheet function), while in {@link PivotSubtotalFunction} `'count'` means "count of
+ * numeric values" (like the COUNT worksheet function). The `'countNums'` value here corresponds
+ * to COUNT.
+ *
+ * @group PivotTables
+ */
+type PivotDataFieldAggregation = 'sum' | 'count' | 'average' | 'max' | 'min' | 'product' | 'countNums' | 'stdDev' | 'stdDevP' | 'var' | 'varP';
+
+/**
+ * Controls how a data field's values are displayed relative to other values. For example,
+ * `'percentOfTotal'` displays each value as a percentage of the grand total.
+ *
+ * @group PivotTables
+ */
+type PivotShowDataAs = 'normal' | 'difference' | 'percent' | 'percentDiff' | 'runTotal' | 'percentOfRow' | 'percentOfCol' | 'percentOfTotal' | 'index' | 'percentOfParentRow' | 'percentOfParentCol' | 'percentOfParent' | 'percentOfRunningTotal' | 'rankAscending' | 'rankDescending';
+
+/**
+ * Describes a data field in a pivot table. Data fields define the values that are aggregated and
+ * displayed in the data area of the pivot table.
+ *
+ * @group PivotTables
+ */
+type PivotDataField = {
+    /**
+     * The display name of the data field (e.g. "Sum of Revenue"). Derivable from the field name
+     * and aggregation function, but Excel always writes it.
+     */
+    name?: string;
+    /** Index into the pivot table's {@link PivotField} array (and the cache's field array). */
+    fieldIndex: integer;
+    /**
+     * The aggregation function to apply (NB: not related to row/column subtotals configured
+     * via {@link PivotField.subtotalFunctions}).
+     *
+     * @default 'sum'
+     */
+    subtotal?: PivotDataFieldAggregation;
+    /**
+     * How to display the aggregated values.
+     *
+     * @default 'normal'
+     */
+    showDataAs?: PivotShowDataAs;
+    /**
+     * The index of the base field used for "show data as" calculations (e.g. percent difference).
+     * Only meaningful when {@link showDataAs} is set to a relative calculation mode.
+     *
+     * @default -1
+     */
+    baseField?: integer;
+    /**
+     * The index of the base item used for "show data as" calculations. Only meaningful when
+     * {@link showDataAs} is set to a relative calculation mode.
+     *
+     * @default 1048832
+     */
+    baseItem?: integer;
+    /** The number format code for this data field's values (e.g. `"General"`, `"#,##0"`). */
+    numFmt?: string;
+};
+
+/**
+ * The subtotal aggregation functions that can be applied to a pivot field.
+ *
+ * Beware of the `'count'` false cognate: here it means "count of numeric values" (like the COUNT
+ * worksheet function), while in {@link PivotDataFieldAggregation} `'count'` means "count of
+ * non-empty values" (like the COUNTA worksheet function).
+ *
+ * @group PivotTables
+ */
+type PivotSubtotalFunction = 'sum' | 'countA' | 'avg' | 'max' | 'min' | 'product' | 'count' | 'stdDev' | 'stdDevP' | 'var' | 'varP';
+
+/**
+ * The type of a pivot field item, indicating its role in the pivot table layout.
+ *
+ * - `'data'` — a regular data item representing a unique value from the field.
+ * - `'default'` — the default subtotal item.
+ * - Any {@link PivotSubtotalFunction} value — a specific subtotal aggregation item.
+ * - `'grand'` — a grand total item.
+ * - `'blank'` — a blank item (placeholder).
+ *
+ * @group PivotTables
+ */
+type PivotItemType = PivotSubtotalFunction | 'data' | 'default' | 'grand' | 'blank';
+
+/**
+ * An item within a pivot field. Items represent individual values, subtotals, or other special
+ * entries in a row or column field.
+ *
+ * @group PivotTables
+ */
+type PivotFieldItem = {
+    /**
+     * Index into the corresponding cache field's {@link PivotCacheField.sharedItems | sharedItems}
+     * array. Absent for non-data items (subtotals, grand totals, blanks).
+     */
+    itemIndex?: integer;
+    /**
+     * The type of this item.
+     *
+     * @default 'data'
+     */
+    itemType?: PivotItemType;
+    /**
+     * Whether this item is hidden (filtered out).
+     *
+     * @default false
+     */
+    hidden?: boolean;
+    /**
+     * Display name override for this item. When absent, the item's name is
+     * derived from the cache field's shared items.
+     */
+    name?: string;
+    /**
+     * Whether this item's children are expanded (visible).
+     *
+     * @default true
+     */
+    expanded?: boolean;
+    /**
+     * Whether this item refers to a value that is no longer in the source data (a "missing" item).
+     *
+     * @default false
+     */
+    missing?: boolean;
+};
+
+/**
+ * Configuration for a single field in a pivot table. There is one PivotField per cache field, in
+ * the same order as the cache fields.
+ *
+ * @group PivotTables
+ */
+type PivotField = {
+    /**
+     * Display name override for this field. When present, this replaces
+     * the cache field name in the pivot table's UI. Distinct from {@link PivotFieldItem.name} which
+     * overrides individual item labels.
+     */
+    name?: string;
+    /**
+     * Which axis this field is placed on. Absent if the field is not placed on a row, column, or
+     * page axis (e.g. fields used only as data fields, or fields not used in the layout at all).
+     */
+    axis?: PivotFieldAxis;
+    /**
+     * Whether this field is used as a data field. Data fields appear in the pivot table's
+     * {@link PivotDataField} list; this flag indicates
+     * that the field participates as a value source rather than being placed on a row/col/page axis.
+     *
+     * @default false
+     */
+    dataField?: boolean;
+    /**
+     * Whether to show all items for this field, including those with no data.
+     *
+     * @default true
+     */
+    showAll?: boolean;
+    /**
+     * The subtotal functions to show. When absent or empty, the default subtotal (typically sum or
+     * count) is used.
+     */
+    subtotalFunctions?: PivotSubtotalFunction[];
+    /**
+     * The sort order for this field's items.
+     *
+     * @default 'manual'
+     */
+    sortType?: 'manual' | 'ascending' | 'descending';
+    /** The items in this field, representing unique values and special entries. */
+    items?: PivotFieldItem[];
+    /**
+     * Whether the field uses compact layout (labels in the same column as child fields).
+     *
+     * @default true
+     */
+    compact?: boolean;
+    /**
+     * Whether the field uses outline layout (labels on their own row, above child data).
+     *
+     * @default true
+     */
+    outline?: boolean;
+    /**
+     * Whether subtotals appear at the top of each group (only meaningful in outline mode).
+     *
+     * @default true
+     */
+    subtotalTop?: boolean;
+    /**
+     * Whether to insert a blank row after each group in this field.
+     *
+     * @default false
+     */
+    insertBlankRow?: boolean;
+    /**
+     * Whether to show the default subtotal for this field.
+     *
+     * @default true
+     */
+    defaultSubtotal?: boolean;
+    /** Custom caption for the subtotal row. */
+    subtotalCaption?: string;
+    /** The number format code for this field's data (e.g. `"General"`, `"#,##0"`). */
+    numFmt?: string;
+    /**
+     * Whether filter dropdowns are shown for this field.
+     *
+     * @default true
+     */
+    showDropDowns?: boolean;
+    /**
+     * Whether the field can be dragged to the row axis.
+     *
+     * @default true
+     */
+    dragToRow?: boolean;
+    /**
+     * Whether the field can be dragged to the column axis.
+     *
+     * @default true
+     */
+    dragToCol?: boolean;
+    /**
+     * Whether the field can be dragged to the page (filter) axis.
+     *
+     * @default true
+     */
+    dragToPage?: boolean;
+    /**
+     * Whether the field can be dragged to the data area.
+     *
+     * @default true
+     */
+    dragToData?: boolean;
+    /**
+     * Whether the field can be dragged off the pivot table (removed).
+     *
+     * @default true
+     */
+    dragOff?: boolean;
+    /**
+     * Whether multiple items can be selected in this field's filter.
+     *
+     * @default false
+     */
+    multipleItemSelectionAllowed?: boolean;
+    /**
+     * Whether a page break is inserted after each group in this field.
+     *
+     * @default false
+     */
+    insertPageBreak?: boolean;
+    /**
+     * Whether newly added items are hidden by default.
+     *
+     * @default false
+     */
+    hideNewItems?: boolean;
+    /**
+     * Whether new items are included in the field's manual filter.
+     *
+     * @default false
+     */
+    includeNewItemsInFilter?: boolean;
+    /**
+     * Whether the auto-show (top/bottom N) filter is enabled.
+     *
+     * @default false
+     */
+    autoShow?: boolean;
+    /**
+     * Whether auto-show displays the top N items (true) or bottom N items (false).
+     *
+     * @default true
+     */
+    topAutoShow?: boolean;
+    /**
+     * Number of items to display when auto-show is enabled.
+     *
+     * @default 10
+     */
+    itemPageCount?: integer;
+    /** Whether sorting is deferred to the data source. */
+    dataSourceSort?: boolean;
+    /**
+     * Whether the field defaults to no auto-sort (manual sort).
+     *
+     * @default false
+     */
+    nonAutoSortDefault?: boolean;
+    /** Index of the data field used for ranking. */
+    rankBy?: integer;
+    /**
+     * Whether this field's hierarchy level is hidden.
+     *
+     * @default false
+     */
+    hiddenLevel?: boolean;
+    /** The unique member property for this field (OLAP). */
+    uniqueMemberProperty?: string;
+    /**
+     * Whether all items in this field are drilled down.
+     *
+     * @default false
+     */
+    allDrilled?: boolean;
+    /**
+     * Whether this is a server-based field.
+     *
+     * @default false
+     */
+    serverField?: boolean;
+    /**
+     * Whether the field supports measure filtering (OLAP).
+     *
+     * @default false
+     */
+    measureFilter?: boolean;
+    /**
+     * Whether member property values are shown in cells.
+     *
+     * @default false
+     */
+    showPropCell?: boolean;
+    /**
+     * Whether member property values are shown in tooltips.
+     *
+     * @default false
+     */
+    showPropTip?: boolean;
+    /**
+     * Whether member property values are used as captions.
+     *
+     * @default false
+     */
+    showPropAsCaption?: boolean;
+    /**
+     * Default drill state for member properties.
+     *
+     * @default false
+     */
+    defaultAttributeDrillState?: boolean;
+};
+
+/**
+ * The type of a pivot table filter.
+ *
+ * @group PivotTables
+ */
+type PivotFilterType = 'unknown' | 'count' | 'percent' | 'sum' | 'captionEqual' | 'captionNotEqual' | 'captionBeginsWith' | 'captionNotBeginsWith' | 'captionEndsWith' | 'captionNotEndsWith' | 'captionContains' | 'captionNotContains' | 'captionGreaterThan' | 'captionGreaterThanOrEqual' | 'captionLessThan' | 'captionLessThanOrEqual' | 'captionBetween' | 'captionNotBetween' | 'valueEqual' | 'valueNotEqual' | 'valueGreaterThan' | 'valueGreaterThanOrEqual' | 'valueLessThan' | 'valueLessThanOrEqual' | 'valueBetween' | 'valueNotBetween' | 'dateEqual' | 'dateNotEqual' | 'dateOlderThan' | 'dateOlderThanOrEqual' | 'dateNewerThan' | 'dateNewerThanOrEqual' | 'dateBetween' | 'dateNotBetween' | 'tomorrow' | 'today' | 'yesterday' | 'nextWeek' | 'thisWeek' | 'lastWeek' | 'nextMonth' | 'thisMonth' | 'lastMonth' | 'nextQuarter' | 'thisQuarter' | 'lastQuarter' | 'nextYear' | 'thisYear' | 'lastYear' | 'yearToDate' | 'Q1' | 'Q2' | 'Q3' | 'Q4' | 'M1' | 'M2' | 'M3' | 'M4' | 'M5' | 'M6' | 'M7' | 'M8' | 'M9' | 'M10' | 'M11' | 'M12';
+
+/**
+ * An advanced filter applied to a pivot table field.
+ *
+ * Pivot filters implement features like "Show Top 10", "Show items where value > X",
+ * and date-based filters.
+ *
+ * @group PivotTables
+ */
+type PivotFilter = {
+    /** Index of the pivot field this filter applies to. */
+    fieldIndex: integer;
+    /** The filter type. */
+    type: PivotFilterType;
+    /** Unique identifier for this filter within the pivot table. */
+    id: integer;
+    /**
+     * Evaluation order for multiple filters. Lower values are evaluated first.
+     *
+     * @default 0
+     */
+    evalOrder?: integer;
+    /** Member property field index (OLAP). */
+    mpFld?: integer;
+    /** Measure hierarchy index (OLAP). */
+    iMeasureHier?: integer;
+    /** Measure field index used for value-based filters. */
+    iMeasureFld?: integer;
+    /** Display name for the filter. */
+    name?: string;
+    /** Description of the filter. */
+    description?: string;
+    /** First string value for comparison-based filters. */
+    stringValue1?: string;
+    /** Second string value for between/not-between filters. */
+    stringValue2?: string;
+    /** Auto-filter criteria that implement this pivot filter. */
+    autoFilter?: {
+        /** The reference range for the auto-filter. */
+        ref?: string;
+        /** Filter columns with their criteria. */
+        filterColumns?: PivotAutoFilterColumn[];
+    };
+};
+
+/**
+ * Describes a page (filter) field in a pivot table. Page fields allow the user to filter the
+ * entire pivot table to show only data matching a selected item.
+ *
+ * @group PivotTables
+ */
+type PivotPageField = {
+    /** Index into the pivot table's {@link PivotField} array (and the cache's field array). */
+    fieldIndex: integer;
+    /**
+     * The index of the currently selected item in the field's items list. When absent, all items are
+     * shown (no filter applied).
+     */
+    selectedItem?: integer;
+    /**
+     * An optional name override for the page field. Identifies the field in formulas and
+     * programmatic access (e.g. GETPIVOTDATA).
+     */
+    name?: string;
+    /**
+     * Display caption for the page field. Shown in the pivot table UI but not used for programmatic
+     * field identification.
+     */
+    caption?: string;
+    /**
+     * Hierarchy index for OLAP page fields.
+     *
+     * @default -1
+     */
+    hierarchy?: integer;
+};
+
+/**
+ * A layout item in the row or column area, describing what each row or column header represents.
+ *
+ * @group PivotTables
+ */
+type PivotRowColItem = {
+    /**
+     * The type of this layout item (same enumeration as {@link PivotFieldItem.itemType}).
+     *
+     * @default 'data'
+     */
+    itemType?: PivotItemType;
+    /**
+     * The number of leading axis positions whose {@link itemIndices} entries are omitted because
+     * they are identical to the previous {@link PivotRowColItem}'s values (see
+     * {@link PivotTable | PivotTable's type description} for the level/axis model). The omitted
+     * entries are inherited from the preceding item in {@link PivotTable.rowItems | rowItems} or
+     * {@link PivotTable.colItems | colItems}.
+     *
+     * @default 0
+     */
+    repeatedItemCount?: integer;
+    /**
+     * Indices into each axis field's {@link PivotField.items | items} array. Entries correspond
+     * positionally to the fields listed in {@link PivotTable.rowFieldIndices | rowFieldIndices} (for
+     * row items) or {@link PivotTable.colFieldIndices | colFieldIndices} (for column items): entry
+     * *i* indexes into the *i*-th axis field's {@link PivotField.items | items}.
+     *
+     * When {@link repeatedItemCount} is greater than zero, the first that many entries are omitted
+     * (inherited from the previous {@link PivotRowColItem}), so the array starts at position
+     * {@link repeatedItemCount}.
+     */
+    itemIndices?: integer[];
+    /**
+     * Index into the pivot table's {@link PivotTable.dataFields | dataFields}, indicating which data
+     * field this item represents.
+     *
+     * @default 0
+     */
+    dataFieldIndex?: integer;
+};
+
+/**
+ * Describes the position of the pivot table's header and data areas within its output range
+ * ({@link PivotTable.ref | ref}).
+ *
+ * All offsets are 0-based from the top-left cell of {@link PivotTable.ref | ref}. The difference
+ * `firstDataRow - firstHeaderRow` equals the number of column-field header rows.
+ *
+ * @group PivotTables
+ */
+type PivotTableLocation = {
+    /**
+     * 0-based row offset from the top of {@link PivotTable.ref | ref} to the first row of the body
+     * area (column-field items, or data if there are no column fields).
+     */
+    firstHeaderRow: integer;
+    /**
+     * 0-based row offset from the top of {@link PivotTable.ref | ref} to the first row containing
+     * data values.
+     */
+    firstDataRow: integer;
+    /**
+     * 0-based column offset from the left of {@link PivotTable.ref | ref} to the first column
+     * containing data values.
+     */
+    firstDataCol: integer;
+    /**
+     * Number of rows occupied by the page field area (see {@link PivotTable | PivotTable's type
+     * description}). Layout depends on {@link PivotTable.pageOverThenDown | pageOverThenDown} and
+     * {@link PivotTable.pageWrap | pageWrap}.
+     *
+     * @default 0
+     */
+    rowPageCount?: integer;
+    /**
+     * Number of columns occupied by the page field area (see {@link PivotTable | PivotTable's type
+     * description}). Layout depends on {@link PivotTable.pageOverThenDown | pageOverThenDown} and
+     * {@link PivotTable.pageWrap | pageWrap}.
+     *
+     * @default 0
+     */
+    colPageCount?: integer;
+};
+
+/**
+ * Excel's built-in pivot table style names.
+ *
+ * @group PivotTables
+ */
+type PivotTableStyleName = 'PivotStyleDark1' | 'PivotStyleDark2' | 'PivotStyleDark3' | 'PivotStyleDark4' | 'PivotStyleDark5' | 'PivotStyleDark6' | 'PivotStyleDark7' | 'PivotStyleDark8' | 'PivotStyleDark9' | 'PivotStyleDark10' | 'PivotStyleDark11' | 'PivotStyleDark12' | 'PivotStyleDark13' | 'PivotStyleDark14' | 'PivotStyleDark15' | 'PivotStyleDark16' | 'PivotStyleDark17' | 'PivotStyleDark18' | 'PivotStyleDark19' | 'PivotStyleDark20' | 'PivotStyleDark21' | 'PivotStyleDark22' | 'PivotStyleDark23' | 'PivotStyleDark24' | 'PivotStyleDark25' | 'PivotStyleDark26' | 'PivotStyleDark27' | 'PivotStyleDark28' | 'PivotStyleLight1' | 'PivotStyleLight2' | 'PivotStyleLight3' | 'PivotStyleLight4' | 'PivotStyleLight5' | 'PivotStyleLight6' | 'PivotStyleLight7' | 'PivotStyleLight8' | 'PivotStyleLight9' | 'PivotStyleLight10' | 'PivotStyleLight11' | 'PivotStyleLight12' | 'PivotStyleLight13' | 'PivotStyleLight14' | 'PivotStyleLight15' | 'PivotStyleLight16' | 'PivotStyleLight17' | 'PivotStyleLight18' | 'PivotStyleLight19' | 'PivotStyleLight20' | 'PivotStyleLight21' | 'PivotStyleLight22' | 'PivotStyleLight23' | 'PivotStyleLight24' | 'PivotStyleLight25' | 'PivotStyleLight26' | 'PivotStyleLight27' | 'PivotStyleLight28' | 'PivotStyleMedium1' | 'PivotStyleMedium2' | 'PivotStyleMedium3' | 'PivotStyleMedium4' | 'PivotStyleMedium5' | 'PivotStyleMedium6' | 'PivotStyleMedium7' | 'PivotStyleMedium8' | 'PivotStyleMedium9' | 'PivotStyleMedium10' | 'PivotStyleMedium11' | 'PivotStyleMedium12' | 'PivotStyleMedium13' | 'PivotStyleMedium14' | 'PivotStyleMedium15' | 'PivotStyleMedium16' | 'PivotStyleMedium17' | 'PivotStyleMedium18' | 'PivotStyleMedium19' | 'PivotStyleMedium20' | 'PivotStyleMedium21' | 'PivotStyleMedium22' | 'PivotStyleMedium23' | 'PivotStyleMedium24' | 'PivotStyleMedium25' | 'PivotStyleMedium26' | 'PivotStyleMedium27' | 'PivotStyleMedium28';
+
+/**
+ * Presentation style settings for a pivot table.
+ *
+ * @group PivotTables
+ */
+type PivotTableStyle = {
+    /**
+     * The name of the pivot table style (e.g. `"PivotStyleMedium9"`).
+     *
+     * If the value is null or omitted the table should not be rendered with any special styling (note
+     * that this only applies if the style object itself is present).
+     *
+     * @default null
+     */
+    name?: PivotTableStyleName | null;
+    /**
+     * Whether row header formatting should be applied.
+     *
+     * @default false
+     */
+    showRowHeaders?: boolean;
+    /**
+     * Whether column header formatting should be applied.
+     *
+     * @default false
+     */
+    showColumnHeaders?: boolean;
+    /**
+     * Whether row stripe formatting should be applied.
+     *
+     * @default false
+     */
+    showRowStripes?: boolean;
+    /**
+     * Whether column stripe formatting should be applied.
+     *
+     * @default false
+     */
+    showColumnStripes?: boolean;
+    /**
+     * Whether the last column's formatting from the named style is applied to the grand total column.
+     *
+     * @default false
+     */
+    showLastColumn?: boolean;
+};
+
+/**
+ * A pivot table definition. Pivot tables dynamically group, filter, and aggregate source data,
+ * displaying the results in a structured layout on a worksheet.
+ *
+ * The layout is organized around **axes**: each {@link PivotField} can be placed on the row axis,
+ * column axis, or page (filter) axis via its {@link PivotField.axis | axis} property.
+ * {@link rowFieldIndices} and {@link colFieldIndices} list the fields on each axis in display
+ * order; each position in that list is sometimes called a **level**. The page axis fields appear
+ * in the **page field area**, a region above the pivot table body where filter dropdowns are
+ * displayed (see {@link pageFields}).
+ *
+ * {@link rowItems} and {@link colItems} describe the rendered layout: each
+ * {@link PivotRowColItem} represents one row or column header, with
+ * {@link PivotRowColItem.itemIndices | itemIndices} mapping positionally to the fields on that
+ * axis. The **data area** is the grid of aggregated values framed by those row and column
+ * headers; its contents are defined by the {@link dataFields}.
+ *
+ * ```
+ * +--------------------------------------------+
+ * |        Page field area (filters)           |  pageFields
+ * |        rowPageCount × colPageCount         |
+ * +----------------+---------------------------+  firstHeaderRow
+ * |                |     Column headers        |  colItems
+ * |  Row headers   +---------------------------+  firstDataRow
+ * |   (rowItems)   |        Data area          |
+ * |                |       (dataFields)        |
+ * +----------------+---------------------------+
+ *                  ^ firstDataCol
+ * ```
+ *
+ * {@link PivotTableLocation.firstHeaderRow | firstHeaderRow},
+ * {@link PivotTableLocation.firstDataRow | firstDataRow}, and
+ * {@link PivotTableLocation.firstDataCol | firstDataCol} locate these regions within the
+ * output range ({@link ref}).
+ *
+ * @see {@link https://support.microsoft.com/office/a9a84538-bfe9-40a9-a8e9-f99134456576}
+ *
+ * @group PivotTables
+ */
+type PivotTable = {
+    /**
+     * The name of the pivot table. Typically unique per workbook, but Excel allows duplicate names
+     * across different sheets.
+     */
+    name: string;
+    /** The name of the sheet where this pivot table's output is rendered. */
+    sheet: string;
+    /** The pivot cache that supplies source data for this pivot table. */
+    cache: PivotCache;
+    /** The A1-style range reference covering the pivot table's output area. */
+    ref: CellRange;
+    /** Position information for the pivot table's data within its output range. */
+    location: PivotTableLocation;
+    /**
+     * The pivot fields, paralleling the cache's {@link PivotCacheBase.fields | fields} array.
+     * Each field's configuration determines whether and how it participates in the pivot table
+     * layout.
+     */
+    fields: PivotField[];
+    /**
+     * Indices into {@link fields} identifying which fields appear on the row axis, in display order.
+     * Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual field,
+     * used when there are multiple data fields) and do not index into {@link fields}.
+     */
+    rowFieldIndices?: integer[];
+    /**
+     * Indices into {@link fields} identifying which fields appear on the column axis, in display
+     * order. Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual
+     * field) and do not index into {@link fields}.
+     */
+    colFieldIndices?: integer[];
+    /** The data fields, defining the aggregated values displayed in the pivot table's data area. */
+    dataFields?: PivotDataField[];
+    /** The page (filter) fields, allowing the pivot table to be filtered by specific field values. */
+    pageFields?: PivotPageField[];
+    /** Layout items for the row area, describing each row header. */
+    rowItems?: PivotRowColItem[];
+    /** Layout items for the column area, describing each column header. */
+    colItems?: PivotRowColItem[];
+    /** Presentation style for the pivot table. */
+    style?: PivotTableStyle;
+    /** Advanced filters applied to pivot fields. */
+    filters?: PivotFilter[];
+    /**
+     * Calculated field definitions. Each entry defines a formula-based field that derives its values
+     * from other cache fields.
+     */
+    calculatedFields?: PivotCalculatedField[];
+    /**
+     * Revision-tracking unique identifier. A GUID string like
+     * `"{93AACE53-8F3A-A04A-893A-A439866B3165}"` assigned by Excel 2014+ for revision tracking.
+     */
+    uid?: string;
+    /**
+     * Whether grand totals should be shown for rows.
+     *
+     * @default true
+     */
+    rowGrandTotals?: boolean;
+    /**
+     * Whether grand totals should be shown for columns.
+     *
+     * @default true
+     */
+    colGrandTotals?: boolean;
+    /**
+     * Whether the pivot table should automatically refresh when its source data changes.
+     *
+     * @default false
+     */
+    autoRefresh?: boolean;
+    /**
+     * Default compact flag for pivot fields. Fields inherit this unless they override
+     * {@link PivotField.compact | their own compact}.
+     *
+     * @default true
+     */
+    compact?: boolean;
+    /**
+     * Default outline flag for pivot fields. Fields inherit this unless they override
+     * {@link PivotField.outline | their own outline}.
+     *
+     * @default false
+     */
+    outline?: boolean;
+    /**
+     * Whether data-area values are repeated on outline header rows. When false (the default),
+     * values appear only on the innermost detail rows; when true, each outline-level header row
+     * also shows the aggregated values for its group.
+     *
+     * @default false
+     */
+    outlineData?: boolean;
+    /**
+     * Whether data fields in compact layout share a single column.
+     *
+     * @default true
+     */
+    compactData?: boolean;
+    /**
+     * Whether classic-style grid drop zones are shown. Drop zones are labeled regions (e.g.
+     * "Drop Row Fields Here") displayed in the pivot table area where fields can be dragged to
+     * assign them to an axis.
+     *
+     * @default false
+     */
+    gridDropZones?: boolean;
+    /**
+     * Number of character widths to indent row labels in compact layout.
+     *
+     * @default 1
+     */
+    indent?: integer;
+    /**
+     * Whether the data (values) axis runs along rows rather than columns.
+     *
+     * @default false
+     */
+    dataOnRows?: boolean;
+    /**
+     * Position of the "Values" virtual field within its axis. When absent, the Values field is placed
+     * at the end.
+     */
+    dataPosition?: integer;
+    /**
+     * Whether row and column headers are displayed.
+     *
+     * @default true
+     */
+    showHeaders?: boolean;
+    /**
+     * Whether empty rows are shown in the output.
+     *
+     * @default false
+     */
+    showEmptyRow?: boolean;
+    /**
+     * Whether empty columns are shown in the output.
+     *
+     * @default false
+     */
+    showEmptyCol?: boolean;
+    /**
+     * Whether drop zones for fields are displayed in the pivot table area.
+     *
+     * @default true
+     */
+    showDropZones?: boolean;
+    /**
+     * Whether member property tooltips are shown.
+     *
+     * @default true
+     */
+    showMemberPropertyTips?: boolean;
+    /**
+     * Whether drill-down (expand/collapse) is enabled on pivot field items.
+     *
+     * @default true
+     */
+    enableDrill?: boolean;
+    /**
+     * Whether the pivot table shows "Multiple Items" labels when a page field
+     * has more than one item selected.
+     *
+     * @default true
+     */
+    showMultipleLabel?: boolean;
+    /**
+     * Caption for the data (values) area. Excel always writes this (typically `"Data"` or a
+     * localized equivalent).
+     */
+    dataCaption?: string;
+    /** Custom label for grand total rows/columns. */
+    grandTotalCaption?: string;
+    /** Text to display in place of error values. */
+    errorCaption?: string;
+    /**
+     * Whether error captions are shown (when true, cells with errors display {@link errorCaption}).
+     *
+     * @default false
+     */
+    showError?: boolean;
+    /** Text to display in place of missing values. */
+    missingCaption?: string;
+    /**
+     * Whether missing-value captions are shown.
+     *
+     * @default true
+     */
+    showMissing?: boolean;
+    /** Caption for the row header area. */
+    rowHeaderCaption?: string;
+    /** Caption for the column header area. */
+    colHeaderCaption?: string;
+    /**
+     * Whether hidden items are included in subtotals.
+     *
+     * @default false
+     */
+    subtotalHiddenItems?: boolean;
+    /**
+     * Whether field names are printed on each page when the pivot table is printed.
+     *
+     * @default false
+     */
+    fieldPrintTitles?: boolean;
+    /**
+     * Whether item labels are printed on each page when the pivot table is printed.
+     *
+     * @default false
+     */
+    itemPrintTitles?: boolean;
+    /**
+     * Whether labels from outer row fields are merged across cells.
+     *
+     * @default false
+     */
+    mergeItem?: boolean;
+    /**
+     * Whether custom list ordering is used when sorting items.
+     *
+     * @default true
+     */
+    customListSort?: boolean;
+    /**
+     * Whether multiple filters can be applied to a single field simultaneously.
+     *
+     * @default true
+     */
+    multipleFieldFilters?: boolean;
+    /**
+     * Whether field items are shown in the pivot table body.
+     *
+     * @default true
+     */
+    showItems?: boolean;
+    /**
+     * Whether calculated members from OLAP data sources are shown.
+     *
+     * @default true
+     */
+    showCalcMbrs?: boolean;
+    /**
+     * Whether cell formatting is preserved on refresh.
+     *
+     * @default true
+     */
+    preserveFormatting?: boolean;
+    /**
+     * Number of page fields per column before wrapping to a new column.
+     *
+     * @default 0
+     */
+    pageWrap?: integer;
+    /**
+     * Whether page fields are laid out across then down (true) or down then across (false).
+     *
+     * @default false
+     */
+    pageOverThenDown?: boolean;
+    /** Built-in auto-format ID. */
+    autoFormatId?: integer;
+    /**
+     * Whether auto-formatting is applied.
+     *
+     * @default false
+     */
+    useAutoFormatting?: boolean;
+    /**
+     * Whether number formats from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyNumberFormats?: boolean;
+    /**
+     * Whether border formats from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyBorderFormats?: boolean;
+    /**
+     * Whether font formats from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyFontFormats?: boolean;
+    /**
+     * Whether pattern (fill) formats from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyPatternFormats?: boolean;
+    /**
+     * Whether alignment formats from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyAlignmentFormats?: boolean;
+    /**
+     * Whether width/height adjustments from the auto-format are applied.
+     *
+     * @default false
+     */
+    applyWidthHeightFormats?: boolean;
+};
+
+/**
+ * Directions on how formulas should be recalculated in the workbook.
+ *
+ * @group Workbooks
+ */
+type CalcProps = {
+    /**
+     * Specifies whether an attempt should be made to calculate formulas that contain circular
+     * references. Defaults to `false` in Excel.
+     */
+    iterate?: boolean;
+    /**
+     * The maximum number of calculation iterations, when {@link CalcProps.iterate} is `true`.
+     * Defaults to `100` in Excel.
+     */
+    iterateCount?: integer;
+    /**
+     * When a calculation iteration results in an absolute change that is less than iterateDelta,
+     * then no further iterations should be attempted. Defaults to `0.001` in Excel.
+     */
+    iterateDelta?: number;
+    /**
+     * Which of the two date systems the workbook uses. 1900 is the default.
+     *
+     * @see {@link https://support.microsoft.com/office/e7fe7167-48a9-4b96-bb53-5612a800b487 | Date systems in Excel}
+     */
+    epoch?: 1900 | 1904;
+    /**
+     * The calculation mode for the workbook.
+     *
+     * - `"auto"` (default when absent): recalculate all formulas automatically.
+     * - `"autoNoTable"`: recalculate automatically but exclude data tables.
+     * - `"manual"`: formulas are only recalculated when explicitly triggered.
+     *
+     * @defaultValue "auto"
+     */
+    calcMode?: 'auto' | 'autoNoTable' | 'manual';
+};
+
+/**
+ * A collection of default properties that apply to cells, rows, or columns in the worksheet.
+ *
+ * @group Workbooks
+ */
+type WorksheetDefaults = {
+    /** Default width of the UI-grid column. */
+    colWidth: PixelValue;
+    /** Default height of the UI-grid height. */
+    rowHeight: PixelValue;
+};
+
+/**
+ * Visual scale (aka zoom level, aka magnification) applied when displaying a worksheet.
+ *
+ * Each of the three layouts has its own scale. A scale is represented as a percentage, with `100`
+ * (100%) being the default 1:1 scale. When a layout has no explicit scale, use 100%.
+ *
+ * @group Workbooks
+ */
+type WorksheetLayoutScales = {
+    /**
+     * Zoom level for normal view.
+     *
+     * @min 10
+     * @max 400
+     * @defaultValue 100
+     * */
+    normal?: integer;
+    /**
+     * Zoom level for page layout view.
+     *
+     * @min 10
+     * @max 400
+     * @defaultValue 100
+     */
+    pageLayout?: integer;
+    /**
+     * Zoom level for page break preview (aka sheet layout view).
+     *
+     * @min 10
+     * @max 400
+     * @defaultValue 100
+     */
+    pageBreakPreview?: integer;
+};
+
+/**
+ * A worksheet view.
+ *
+ * A worksheet view is a display configuration for a particular worksheet. Worksheet view settings
+ * can include:
+ *
+ * - Active cell
+ * - Selected ranges
+ * - View type (normal, page layout, or page break layout)
+ * - Zoom level
+ *
+ * Currently JSF does not include all available settings for a worksheet.
+ *
+ * @group Workbooks
+ */
+type WorksheetView = {
+    /**
+     * The id of the workbook view this worksheet view belongs to.
+     *
+     * This is a zero-based index of the workbook view, as stored in the {@link Workbook.views} array.
+     *
+     * Within a single worksheet, each view must reference a distinct workbook view (i.e. no two views
+     * in the same worksheet can share the same `workbookView` id). However, views from different
+     * worksheets may reference the same workbook view.
+     */
+    workbookView: integer;
+    /** Cell that is selected by default when the sheet is visible. */
+    activeCell?: CellId;
+    /** Ranges of cells that are selected by default when the sheet is visible. */
+    activeRanges?: CellRange[];
+    /**
+     * The layout used to display the worksheet.
+     *
+     * @defaultValue "normal"
+     */
+    activeLayout?: 'normal' | 'pageLayout' | 'pageBreakPreview';
+    /**
+     * Scale (aka zoom level, aka magnification) applied when displaying a worksheet. Each different
+     * layout has its own scale.
+     */
+    layoutScales?: WorksheetLayoutScales;
+};
 
 /**
  * A rectangle of cells. A sheet within a spreadsheet.
+ *
+ * @group Workbooks
  */
 type Worksheet = {
     /** Name of the worksheet. */
@@ -1974,6 +3793,8 @@ type Worksheet = {
  * - Scroll bar visibility
  *
  * Currently JSF does not include all available settings for a workbook.
+ *
+ * @group Workbooks
  */
 type WorkbookView = {
     /**
@@ -1987,6 +3808,8 @@ type WorkbookView = {
 /**
  * A workbook is a collection of worksheets, styles, defined names, and other metadata. It's what's
  * commonly known as a spreadsheet.
+ *
+ * @group Workbooks
  */
 type Workbook = {
     /** Name of the workbook. In the case of a .xlsx file it will be the filename. */
@@ -1997,6 +3820,8 @@ type Workbook = {
     names?: DefinedName[];
     /** Metadata on the workbook's tables. */
     tables?: Table[];
+    /** Metadata on the workbook's pivot tables. */
+    pivotTables?: PivotTable[];
     /** Directions on how formulas should be recalculated in the workbook. */
     calculationProperties?: CalcProps;
     /** Styles for cells in the workbook. */
@@ -2044,4 +3869,4 @@ type Workbook = {
     images?: Record<string, string>;
 };
 
-export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HyperlinkTextRun, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PixelValue, Point, PositiveCoordinate, QuadraticBezierToCommand, RectAlignment, RelativeRect, Shape, ShapeRect, ShapeStyle, SolidFill, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup };
+export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HyperlinkTextRun, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PivotArea, PivotAreaAxis, PivotAreaReference, PivotAreaType, PivotAutoFilterColumn, PivotCache, PivotCacheBase, PivotCacheConsolidation, PivotCacheConsolidationRangeSet, PivotCacheConsolidationSource, PivotCacheExternal, PivotCacheField, PivotCacheFieldGroup, PivotCacheRangePr, PivotCacheRecord, PivotCacheRecordValue, PivotCacheScenario, PivotCacheSharedItem, PivotCacheSharedItemBool, PivotCacheSharedItemDate, PivotCacheSharedItemErr, PivotCacheSharedItemNil, PivotCacheSharedItemNum, PivotCacheSharedItemStr, PivotCacheSharedItemsMeta, PivotCacheWorksheet, PivotCacheWorksheetSource, PivotCacheWorksheetSourceName, PivotCacheWorksheetSourceRange, PivotCalculatedField, PivotCustomFilterCriterion, PivotCustomFilterOperator, PivotDataField, PivotDataFieldAggregation, PivotField, PivotFieldAxis, PivotFieldItem, PivotFilter, PivotFilterType, PivotGroupBy, PivotItemType, PivotPageField, PivotRowColItem, PivotShowDataAs, PivotSubtotalFunction, PivotTable, PivotTableLocation, PivotTableStyle, PivotTableStyleName, PixelValue, Point, PositiveCoordinate, QuadraticBezierToCommand, RectAlignment, RelativeRect, Shape, ShapeRect, ShapeStyle, SolidFill, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup, integer };