@jsfkit/types 1.3.0 → 1.4.1

package/dist/index.d.ts

@@ -236,6 +236,1241 @@ type Note = {
     text: string;
 };
 
+/**
+ * Base type for text runs that annotate ranges within threaded comment text.
+ *
+ * A text run identifies a contiguous range of characters in the comment text, specified by
+ * zero-indexed start and end positions. Text runs allow metadata to be attached to specific
+ * portions of text, enabling features such as hyperlinks, mentions, and formatting.
+ *
+ * ## How text runs work
+ *
+ * Each text run specifies a range within the comment text using `start` (inclusive) and `end`
+ * (exclusive) character positions. For example, in the text "Hello @foo", a mention text run
+ * for "@foo" would have `start: 6` and `end: 10`.
+ *
+ * Multiple text runs can exist within a single comment, allowing different types of annotations
+ * to coexist (a mention and a hyperlink in the same text, for example).
+ *
+ * @see {@link MentionTextRun} for mentions of people
+ * @see {@link HyperlinkTextRun} for hyperlinks
+ */
+type TextRun = {
+    /** Starting character position of the run in the text (zero-indexed). */
+    start: integer;
+    /** Ending character position of the run in the text (zero-indexed, exclusive). */
+    end: integer;
+};
+
+/**
+ * A {@link TextRun | text run} representing a hyperlink within a threaded comment's text.
+ */
+type HyperlinkTextRun = TextRun & {
+    /** Discriminator to identify this as a hyperlink text run. */
+    type: 'hyperlink';
+    /** The URL that the hyperlink points to. */
+    url: string;
+};
+
+/**
+ * A {@link TextRun | text run} representing a mention of a person within a threaded comment's text.
+ */
+type MentionTextRun = TextRun & {
+    /** Discriminator to identify this as a mention text run. */
+    type: 'mention';
+    /**
+     * Unique identifier of the person being mentioned. Use this to find the person's details in a
+     * {@link Workbook.people | workbook's list of people}.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    personId: string;
+};
+
+/**
+ * An author of a threaded comment, or a person mentioned in a threaded comment.
+ */
+type Person = {
+    /**
+     * A unique id for the person.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    id: string;
+    /** The person's name as it should be shown to other users. */
+    displayName: string;
+    /**
+     * Optional provider-issued user identifier that varies in format depending on the provider. See
+     * {@link Person.providerId} for details on possible values.
+     */
+    userId?: string;
+    /**
+     * Specifies where the person's information came from. Excel supports the following values:
+     *
+     * - `None`: no specific provider; {@link Person.userId} is expected to be the person's name.
+     * - `AD`: Active Directory; {@link Person.userId} will be Active Directory id.
+     * - `Windows Live`: Microsoft account; {@link Person.userId} will be a 64-bit signed decimal.
+     * - `PeoplePicker`: SharePoint People Picker; {@link Person.userId} will be an email address.
+     */
+    providerId?: string;
+};
+
+/**
+ * A threaded comment that is attached to an individual cell.
+ */
+type ThreadedComment = {
+    /**
+     * Unique identifier for the comment.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    id: string;
+    /**
+     * Unique identifier of the parent comment, if this is a reply in a thread.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    parentId?: string;
+    /** A1-style reference to the cell this comment is attached to. */
+    ref: CellId;
+    /** Date and time the comment was written, as an ISO formatted string. */
+    datetime?: string;
+    /**
+     * Unique identifier of the person who authored this comment. Use this to find the person's
+     * details in a {@link Workbook.people | workbook's list of people}.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    personId: string;
+    /** The comment text content. */
+    text: string;
+    /** Whether the comment has been marked as resolved. */
+    resolved?: boolean;
+    /** {@link TextRun | Text runs} that annotate ranges within the comment text. */
+    runs?: (MentionTextRun | HyperlinkTextRun)[];
+};
+
+/**
+ * Represents a one dimensional position or length in EMUs.
+ * Same as {@link Coordinate} but value must be 0 or higher.
+ *
+ * @min 0
+ * @max 27273042316900
+ */
+type PositiveCoordinate = number;
+
+/**
+ * Describes the length and width properties for how far drawing element should extend, in EMUs.
+ */
+type Extent = {
+    /** Horizontal size (X-axis). */
+    cx: PositiveCoordinate;
+    /** Vertical size (Y-axis). */
+    cy: PositiveCoordinate;
+};
+
+/**
+ * Represents a one dimensional value (usually position or length) in EMUs.
+ *
+ * EMUs (English Metric Units) are a high precision coordinate space originating from Microsoft
+ * Windows / Office graphics and printing. The unit bridges bridges English (inches) and metric (cm)
+ * units for layout.
+ *
+ * EMU is defined as: 91440 EMUs per 1 inch and 360000 EMUs per 1 cm. Thus EMUs can:
+ *
+ * - Stay integer-based (avoids floating-point rounding errors).
+ * - Convert cleanly to both inches and metric units.
+ * - Work well for screen/display and printer coordinate systems.
+ *
+ * EMUs can be converted to pixels or points by calculating EMUs * DPI / 914400.
+ * For example: At 96 DPI, 49600 EMUs correspond to 49600 * 96 / 914400 = 5.2 points.
+ *
+ * Excel files seem to be saved at 72 DPI, which means 12700 per pixel:
+ *
+ * - EMU to PX: `emu => emu / 12700;`
+ * - PX to PX: `emu => Math.round(emu * 12700);`
+ *
+ * @min -27273042329600
+ * @max 27273042316900
+ */
+type EmuValue = number;
+
+/**
+ * 2D position in EMUs.
+ *
+z * Represents a point in 2D space using absolute coordinates measured in EMUs.
+ */
+type Point = {
+    /** Horizontal position (X-axis). */
+    x: EmuValue;
+    /** Vertical position (Y-axis). */
+    y: EmuValue;
+};
+
+/**
+ * Specifies an absolute anchor placeholder for a group, a shape, or a drawing element.
+ */
+type GraphicAnchorAbsolute = {
+    /** Type discriminator for an absolute anchor. */
+    type: 'absolute';
+    /** The absolute position of the graphic in EMUs. */
+    pos: Point;
+    /** The size of the graphic in EMUs. */
+    ext: Extent;
+};
+
+/**
+ * Specifies a point in the cell grid.
+ */
+type CellOffset = {
+    /** The row in which the point occurs, 1 indexed. */
+    row: number;
+    /** The offset within the row in which the point occurs, in EMUs. */
+    rowOff: EmuValue;
+    /** The column in which the point occurs, 1 indexed. */
+    col: number;
+    /** The position within the column in which the point occurs, in EMUs. */
+    colOff: EmuValue;
+};
+
+/**
+ * Specifies a one cell anchor placeholder for a group, a shape, or a drawing element.
+ */
+type GraphicAnchorOneCell = {
+    /** Type discriminator for a one-cell anchor. */
+    type: 'oneCell';
+    /** The top/left position of the graphic in cell coordinates. */
+    from: CellOffset;
+    /** The size of the graphic in EMUs. */
+    ext: Extent;
+};
+
+/**
+ * Specifies a two-cell anchor placeholder for a group, a shape, or a drawing element.
+ */
+type GraphicAnchorTwoCell = {
+    /** Type discriminator for a two-cell anchor. */
+    type: 'twoCell';
+    /** The top/left position of the graphic in cell coordinates. */
+    from: CellOffset;
+    /** The bottom/right position of the graphic in cell coordinates. */
+    to: CellOffset;
+};
+
+/**
+ * Specifies an anchor placeholder for a group, a shape, or a drawing element.
+ */
+type GraphicAnchor = GraphicAnchorAbsolute | GraphicAnchorOneCell | GraphicAnchorTwoCell;
+
+/**
+ * Represents a percentage of a whole, usually [0-100].
+ */
+type Percentage = number;
+
+/**
+ * Relative rectangle with percentage-based insets.
+ *
+ * Defines a rectangle using relative offsets from each edge, expressed as percentages
+ * of the parent rectangle's dimensions.
+ */
+type RelativeRect = {
+    /** Top edge offset as percentage from top. */
+    t: Percentage;
+    /** Left edge offset as percentage from left. */
+    l: Percentage;
+    /** Bottom edge offset as percentage from bottom. */
+    b: Percentage;
+    /** Right edge offset as percentage from right. */
+    r: Percentage;
+};
+
+/**
+ * Specifies the direction(s) in which to flip a source image while tiling.
+ */
+type FlipAxis = 'none' | 'x' | 'xy' | 'y';
+
+/**
+ * Rectangle alignment position.
+ *
+ * Defines the alignment point within a rectangle, using a 3x3 grid:
+ *
+ * | Value | Position       |
+ * |-------|----------------|
+ * | `b`   | Bottom center  |
+ * | `bl`  | Bottom left    |
+ * | `br`  | Bottom right   |
+ * | `ctr` | Center         |
+ * | `l`   | Middle left    |
+ * | `r`   | Middle right   |
+ * | `t`   | Top center     |
+ * | `tl`  | Top left       |
+ * | `tr`  | Top right      |
+ */
+type RectAlignment = 'b' | 'bl' | 'br' | 'ctr' | 'l' | 'r' | 't' | 'tl' | 'tr';
+
+/**
+ * Tile settings for image fills.
+ *
+ * Defines how an image should be repeated (tiled) when used as a fill,
+ * including scaling, alignment, offset, and flip transformations.
+ */
+type Tile = {
+    /** Additional horizontal offset after alignment, in EMUs. */
+    tx?: EmuValue;
+    /** Additional vertical offset after alignment, in EMUs. */
+    ty?: EmuValue;
+    /** Horizontal scale factor to apply to the source image. */
+    sx?: Percentage;
+    /** Vertical scale factor to apply to the source image. */
+    sy?: Percentage;
+    /** Direction(s) in which to flip the source image while tiling. */
+    flip?: FlipAxis;
+    /**
+     * Alignment position for the first tile relative to the shape bounds (applied after
+     * sx/sy scaling, before tx/ty offset).
+     */
+    align?: RectAlignment;
+};
+
+/**
+ * Image/bitmap fill (blip fill).
+ *
+ * Defines a fill using an embedded or linked image, with options for
+ * tiling, stretching, cropping, and transparency.
+ */
+type BlipFill = {
+    /** Type discriminator for blip (image) fills. */
+    type: 'blip';
+    /**
+     * Reference to the media/image resource to use for this fill.
+     * @see {@link Workbook.images}.
+     */
+    mediaId: string;
+    /**
+     * Opacity value (0-100, where 100 is fully opaque).
+     * @min 0
+     * @max 100
+     * @defaultValue 0
+     */
+    alpha?: Percentage;
+    /**
+     * The DPI used to calculate the size of the blip.
+     * When this value is not present the DPI in the blip is used.
+     */
+    dpi?: integer;
+    /** Whether the blip should rotate when the shape is rotated. */
+    rotWithShape?: boolean;
+    /**
+     * Rectangle defining the source crop area of the image (relative coordinates).
+     */
+    srcRect?: RelativeRect;
+    /**
+     * Rectangle defining how the image should be stretched to fill the shape (relative coordinates).
+     */
+    stretchRect?: RelativeRect;
+    /** Tiling properties for repeating the image pattern across the fill area. */
+    tile?: Tile;
+};
+
+/**
+ * Represents an angle in 60,000ths of a degree (e.g., 5400000 = 90 degrees).
+ *
+ * Positive angles are clockwise (i.e., towards the positive y axis);
+ * negative angles are counter-clockwise (i.e., towards the negative y axis).
+ */
+type DmlAngle = number;
+
+/**
+ * A hex-encoded RGB or RGBA value that conforms to the CSS4 color specification (e.g. `"#3cb371"`).
+ *
+ * @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})$
+ */
+type Color = `#${string}`;
+
+/**
+ * Gradient color stop.
+ *
+ * Defines a color transition point within a gradient fill,
+ * specifying both the position and color at that point.
+ */
+type GradientColorStop = {
+    /**
+     * Position of this color stop within the gradient (0-100, where 0 is start and 100 is end).
+     * @min 0
+     * @max 100
+     */
+    offset: Percentage;
+    /**
+     * Color value at this gradient stop position.
+     */
+    color: Color;
+};
+
+/**
+ * Linear gradient fill.
+ *
+ * Defines a gradient fill that transitions between colors along a straight line,
+ * with configurable angle, flip behavior, and color stops.
+ */
+type GradientLinearFill = {
+    /** Type discriminator for linear gradient fills. */
+    type: 'linearGradient';
+    /** Direction(s) in which to flip the gradient pattern. */
+    flip?: FlipAxis;
+    /** Whether the gradient should rotate when the shape is rotated. */
+    rotWithShape?: boolean;
+    /** Array of color stops defining the gradient color transitions. */
+    colorStops: GradientColorStop[];
+    /** Angle of the gradient direction in 60,000ths of a degree. */
+    angle?: DmlAngle;
+    /** Whether the gradient should scale with the shape dimensions. */
+    scaled?: boolean;
+};
+
+/**
+ * Path gradient fill type.
+ *
+ * Defines the shape pattern used for path gradient fills:
+ * - '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.
+ */
+type PathFillType = 'circle' | 'rect' | 'shape';
+
+/**
+ * Path gradient fill (radial/shape gradient).
+ *
+ * Defines a gradient fill that radiates from a center point or follows
+ * the shape's contour, creating circular, rectangular, or shape-based gradients.
+ */
+type GradientPathFill = {
+    /** Type discriminator for path gradient fills. */
+    type: 'pathGradient';
+    /** Array of color stops defining the gradient color transitions. */
+    colorStops: GradientColorStop[];
+    /** Path type determining the gradient shape (circle, rectangle, or shape contour). */
+    path: PathFillType;
+    /** Rectangle defining the gradient's focus area (relative coordinates). */
+    fillToRect?: RelativeRect;
+    /** Direction(s) in which to flip the gradient pattern. */
+    flip?: FlipAxis;
+    /** Whether the gradient should rotate when the shape is rotated. */
+    rotWithShape?: boolean;
+};
+
+/**
+ * Group fill.
+ *
+ * Declares that the element is part of a group and should inherit the fill properties of the group.
+ */
+type GroupFill = {
+    /** Type discriminator for group fills. */
+    type: 'group';
+};
+
+/**
+ * No fill.
+ *
+ * Declares that the element should not be filled.
+ */
+type NoFill = {
+    /** Type discriminator for none-fills. */
+    type: 'none';
+};
+
+/**
+ * Pattern fill style presets.
+ */
+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';
+
+/**
+ * Pattern fill.
+ *
+ * Defines a fill using a repeating pattern (dots, stripes, crosshatch, etc.)
+ * with configurable foreground and background colors.
+ */
+type PatternFill = {
+    /** Type discriminator for pattern fills. */
+    type: 'pattern';
+    /** Foreground color of the pattern. */
+    fg?: Color;
+    /** Background color of the pattern. */
+    bg?: Color;
+    /** Pattern style defining the visual design (horizontal, vertical, diagonal, dots, etc.). */
+    style?: FillPatternStyle;
+};
+
+/**
+ * Solid color fill.
+ *
+ * Defines a fill using a single uniform color with no gradients, patterns, or images.
+ */
+type SolidFill = {
+    /** Type discriminator for solid fills. */
+    type: 'solid';
+    /** Background color for the solid fill. */
+    bg?: Color;
+};
+
+type Fill = PatternFill | SolidFill | GradientLinearFill | GradientPathFill | GroupFill | NoFill | BlipFill;
+
+/**
+ * A dash stop primitive consisting of a dash and a space.
+ */
+type DashStop = {
+    /**
+     * Length of the dash (relative to line width)
+     * @min 0
+    */
+    d: Percentage;
+    /**
+     * Length of the space (relative to line width)
+     * @min 0
+     */
+    sp: Percentage;
+};
+
+/**
+ * Determines the alignment of a line stroke against its shape path.
+ *
+ * | Value    | Presentation
+ * |----------|-------
+ * | `center` | Stroke is centered on the path.
+ * | `inside` | Stroke is drawn inside the path.
+ *
+ * These have been altered from DrawingML which used "ctr" for `center`, and "in" for `inside`.
+ */
+type LineAlignment = 'center' | 'inside';
+
+/**
+ * Determines how line endpoints are rendered. This is the same as SVG's `stroke-linecap` property.
+ *
+ * | Value    | Presentation
+ * |----------|------------------------------------------------
+ * | `butt`   | Stroke does not extend beyond its endpoints. Zero length line will not be rendered.
+ * | `round`  | Stroke is extended by a half circle with a diameter equal to the line width.
+ * | `square` | Ends of the stroke will be extended by a rectangle half the width of the stroke.
+ *
+ * These have been altered from DrawingML which used "flat" for `butt`, "rnd" for `round`,
+ * and "sq" for `square`.
+ */
+type LineCapType = 'butt' | 'rnd' | 'sq';
+
+/**
+ * Specifies the compound type that is to be used for lines.
+ *
+ * | Value       | Rendered as
+ * |-------------|---------------------------
+ * | `dbl`       | Double lines of equal width
+ * | `sng`       | Single line
+ * | `thickThin` | Double lines: one thick, one thin
+ * | `thinThick` | Double lines: one thin, one thick
+ * | `tri`       | Three lines: thin, thick, thin
+ */
+type LineCompoundType = 'dbl' | 'sng' | 'thickThin' | 'thinThick' | 'tri';
+
+/**
+ * Line ending decoration size: Large, medium, small.
+ */
+type LineEndSize = 'lg' | 'med' | 'sm';
+
+/** Line ending shape type. */
+type LineEndType = 'arrow' | 'diamond' | 'none' | 'oval' | 'stealth' | 'triangle';
+
+/**
+ * Defines a line ending decoration.
+ */
+type LineEnd = {
+    /**
+     * The type of decoration to render.
+     * @defaultValue "none"
+     */
+    type: LineEndType;
+    /**
+     * Width size of the ending decoration.
+     * @defaultValue "med"
+     */
+    width?: LineEndSize;
+    /**
+     * Length size of the ending decoration.
+     * @defaultValue "med"
+     */
+    len?: LineEndSize;
+};
+
+/**
+ * Defines the shape to be used at the corners of a stroked path.
+ * These are equivalent to their CSS/SVG linejoin value counterparts.
+ */
+type LineJoinType = 'bevel' | 'round' | 'miter';
+
+/**
+ * Line dash style.
+ *
+ * | Value           | Appearance
+ * |-----------------|---------------------------------------------
+ * | `dash`          | Equivalent to SVG dashArray of `[4,4]`
+ * | `dashDot`       | Equivalent to SVG dashArray of `[4,3,1,3]`
+ * | `dot`           | Equivalent to SVG dashArray of `[1,3]`
+ * | `lgDash`        | Equivalent to SVG dashArray of `[8,3]`
+ * | `lgDashDot`     | Equivalent to SVG dashArray of `[8,3,1,3]`
+ * | `lgDashDotDot`  | Equivalent to SVG dashArray of `[8,3,1,3,1,3]`
+ * | `solid`         | Equivalent to SVG dashArray of `null`
+ * | `sysDash`       | Equivalent to SVG dashArray of `[3,1]`
+ * | `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]`
+ */
+type LineStyle = 'dash' | 'dashDot' | 'dot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'solid' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot' | 'sysDot';
+
+/**
+ * Line styling properties.
+ *
+ * Defines the visual appearance of lines and shape outlines, including
+ * stroke style, width, caps, joins, and decorative line ends (arrows).
+ */
+type Line = {
+    /** Compound line type for creating multi-stroke effects. */
+    cmpd?: LineCompoundType;
+    /**
+     * Line cap style determining how line endpoints are rendered.
+     * @defaultValue "flat"
+     */
+    cap?: LineCapType;
+    /**
+     * Line join style determining how line segment connections are rendered.
+     * @defaultValue "miter"
+     */
+    join?: LineJoinType;
+    /**
+     * Line alignment relative to the shape path (centered on path or inset)
+     * @defaultValue "ctr"
+     */
+    align?: LineAlignment;
+    /**
+     * Fill style applied to the line stroke.
+     */
+    fill?: PatternFill | SolidFill | GradientLinearFill | GradientPathFill | NoFill;
+    /**
+     * Line width in EMUs.
+     * @min 0
+     * @max 20116800
+     */
+    width?: PositiveCoordinate;
+    /**
+     * Line dash/dot pattern style.
+     */
+    style?: LineStyle | DashStop[];
+    /** Arrow or decoration at the start of the line. */
+    head?: LineEnd;
+    /** Arrow or decoration type at the end of the line. */
+    tail?: LineEnd;
+};
+
+/** An identifier for a geometry guide */
+type GeomGuideName = string;
+
+type AdjustCoordinate = EmuValue | GeomGuideName;
+
+/**
+ * A path command to draw an elliptical arc to an endpoint.
+ */
+type ArcToCommand = ['A', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
+
+/**
+ * A path command to close the current subpath by drawing a line to the starting point.
+ */
+type CloseCommand = ['Z'];
+
+/**
+ * A path command to draw a cubic Bézier curve to an endpoint.
+ */
+type CubicBezierToCommand = ['C', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
+
+/**
+ * A path command to draw a line from the current position to a new one.
+ */
+type LineToCommand = ['L', AdjustCoordinate, AdjustCoordinate];
+
+/**
+ * A path command to move pen to a new position without drawing.
+ */
+type MoveToCommand = ['M', AdjustCoordinate, AdjustCoordinate];
+
+/**
+ * A path command to draw a quadratic Bézier curve to an endpoint.
+ */
+type QuadraticBezierToCommand = ['Q', AdjustCoordinate, AdjustCoordinate, AdjustCoordinate, AdjustCoordinate];
+
+/**
+ * Path command for shape geometry.
+ *
+ * Defines a single drawing command in a shape path, using a subset of SVG path commands.
+ */
+type PathCommand = ArcToCommand | CloseCommand | CubicBezierToCommand | LineToCommand | MoveToCommand | QuadraticBezierToCommand;
+
+/**
+ * Specifies the manner in which a path should be filled.
+ *
+ * | Value         | Effect on path fill
+ * |---------------|--------------------------------
+ * | `darken`      | darker shaded color applied to its fill.
+ * | `darkenLess`  | slightly darker shaded color applied to its fill.
+ * | `lighten`     | lightly shaded color applied to its fill.
+ * | `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.
+ */
+type PathFillMode = 'none' | 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess';
+
+/**
+ * Shape geometry path definition.
+ *
+ * Defines a single path within a custom shape's geometry, including
+ * the path commands and rendering properties for that path.
+ */
+type Path = {
+    /** Whether this path should be stroked (outlined). */
+    stroke: boolean;
+    /** Fill mode for the path. */
+    fill: PathFillMode;
+    /**
+     * Specifies the height, or maximum y coordinate that should be used for within the path
+     * coordinate system. This value determines the vertical placement of all points within the
+     * corresponding path as they will all be calculated using this height attribute as the max y
+     * coordinate.
+     */
+    height: PositiveCoordinate;
+    /**
+     * Specifies the width, or maximum x coordinate that should be used for within the path
+     * coordinate system. This value determines the horizontal placement of all points within
+     * the corresponding path as they will all be calculated using this width attribute as the max
+     * x coordinate.
+     */
+    width: PositiveCoordinate;
+    /** Array of path commands (moveTo, lineTo, etc.) defining the path geometry. */
+    d: PathCommand[];
+};
+
+/**
+ * Defines an inset or internal margins for a text box within a shape.
+ */
+type InsetRect = {
+    /**
+     * Top edge inset from shape bounds in EMUs.
+     * @defaultValue 45720
+     */
+    t?: EmuValue;
+    /**
+     * Left edge inset from shape bounds in EMUs.
+     * @defaultValue 91440
+     */
+    l?: EmuValue;
+    /**
+     * Bottom edge inset from shape bounds in EMUs.
+     * @defaultValue 45720
+     */
+    b?: EmuValue;
+    /**
+     * Right edge inset from shape bounds in EMUs.
+     * @defaultValue 91440
+     */
+    r?: EmuValue;
+};
+
+/** A paragraph of text. */
+type Paragraph = {
+    /** Text content. */
+    text: string;
+};
+
+/**
+ * Text vertical anchoring/alignment.
+ *
+ * Defines how text is vertically positioned within its container:
+ *
+ * | Value  | Position                                |
+ * |--------|-----------------------------------------|
+ * | `t`    | Top aligned                             |
+ * | `ctr`  | Center aligned                          |
+ * | `b`    | Bottom aligned                          |
+ * | `dist` | Distributed (evenly spaced lines)       |
+ * | `just` | Justified (stretched to fill container) |
+ */
+type TextAnchoring = 't' | 'b' | 'ctr' | 'dist' | 'just';
+
+/**
+ * Text horizontal overflow behavior.
+ *
+ * Defines how text is handled when it exceeds the horizontal bounds of its container:
+ *
+ * | Value      | Behavior                                      |
+ * |------------|-----------------------------------------------|
+ * | `overflow` | Text extends beyond container bounds          |
+ * | `clip`     | Text is clipped at container edge             |
+ */
+type TextHorzOverflow = 'overflow' | 'clip';
+
+/**
+ * If there is vertical text, determines what type of vertical text is going to be used.
+ *
+ * | Value            | Behavior
+ * |------------------|------------------------------
+ * | `horz`           | Horizontal text (default).
+ * | `vert`           | Line are rotated 90° clockwise, ordered from top to bottom.
+ * | `vert270`        | Lines are rotated 270° clockwise, ordered from bottom to top.
+ * | `wordArtVert`    | One letter on top of another.
+ * | `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.
+ */
+type TextVerticalType = 'horz' | 'vert' | 'vert270' | 'wordArtVert' | 'eaVert' | 'mongolianVert' | 'wordArtVertRtl';
+
+/**
+ * Text vertical overflow behavior.
+ *
+ * Defines how text is handled when it exceeds the vertical bounds of its container:
+ *
+ * | Value      | Behavior                                      |
+ * |------------|-----------------------------------------------|
+ * | `overflow` | Text extends beyond container bounds          |
+ * | `ellipsis` | Text is truncated with ellipsis indicator     |
+ * | `clip`     | Text is clipped at container edge             |
+ */
+type TextVertOverflow = 'overflow' | 'ellipsis' | 'clip';
+
+/**
+ * Text wrapping behavior.
+ *
+ * Defines how text wraps within its container:
+ *
+ * | Value    | Behavior                                    |
+ * |----------|---------------------------------------------|
+ * | `none`   | No wrapping (text runs on a single line)    |
+ * | `square` | Wrap text at container boundaries           |
+ */
+type TextWrapping = 'none' | 'square';
+
+/**
+ * Text body container.
+ *
+ * Defines the text content within a shape, including paragraphs and formatting properties
+ * such as alignment, overflow behavior, columns, rotation, and insets.
+ */
+type TextBody = {
+    /**
+     * Vertical anchoring/alignment of text within the shape.
+     * @defaultValue "t"
+     */
+    anchor?: TextAnchoring;
+    /**
+     * Whether text is centered at the anchor point.
+     * @defaultValue false
+     */
+    anchorCtr?: boolean;
+    /**
+     * Number of text columns.
+     * @defaultValue 1
+     */
+    numCol?: number;
+    /**
+     * Text rotation in 60,000ths of a degree (e.g., 5400000 = 90 degrees).
+     * @defaultValue 0
+     */
+    rot?: DmlAngle;
+    /**
+     * Whether columns flow right-to-left.
+     * @defaultValue false
+     */
+    rtlCol?: boolean;
+    /**
+     * Spacing between columns in EMUs.
+     * @defaultValue 0
+     */
+    spcCol?: PositiveCoordinate;
+    /**
+     * Whether to apply spacing before first and after last paragraph.
+     * @defaultValue false
+     */
+    spcFirstLastPara?: boolean;
+    /**
+     * Keep text upright regardless of shape rotation.
+     * @defaultValue false
+     */
+    upright?: boolean;
+    /**
+     * Text orientation is vertical (top-to-bottom).
+     * @defaultValue "horz"
+     */
+    vert?: TextVerticalType;
+    /**
+     * Horizontal overflow behavior.
+     * @defaultValue "overflow"
+     */
+    horzOverflow?: TextHorzOverflow;
+    /**
+     * Vertical overflow behavior.
+     * @defaultValue "overflow"
+     */
+    vertOverflow?: TextVertOverflow;
+    /**
+     * Text wrapping behavior.
+     * @defaultValue "square"
+     */
+    wrap?: TextWrapping;
+    /**
+     * Defines an inset or internal margins for a text box within a shape.
+     */
+    inset?: InsetRect;
+    /** Array of paragraphs containing the text content. */
+    p: Paragraph[];
+};
+
+type AdjustPoint = {
+    x: AdjustCoordinate;
+    y: AdjustCoordinate;
+};
+
+/**
+ * Polar adjustment handle for custom shapes.
+ *
+ * Defines an interactive handle that can be dragged to adjust shape geometry
+ * using polar coordinates (angle and radius from a center point).
+ */
+type AdjustValueHandlePolar = {
+    /** Type discriminator for polar adjustment handles. */
+    type: 'polar';
+    /** Name of the guide that this handle adjusts for angle. */
+    gdRefAng?: GeomGuideName;
+    /** Maximum angle value allowed for this handle (in degrees or reference to guide). */
+    maxAng?: GeomGuideName | DmlAngle;
+    /** Minimum angle value allowed for this handle (in degrees or reference to guide). */
+    minAng?: GeomGuideName | DmlAngle;
+    /** Name of the guide that this handle adjusts for radius. */
+    gdRefR?: GeomGuideName;
+    /** Maximum radius value allowed for this handle (in shape coordinates or reference to guide). */
+    maxR?: GeomGuideName | EmuValue;
+    /** Minimum radius value allowed for this handle (in shape coordinates or reference to guide). */
+    minR?: GeomGuideName | EmuValue;
+    /** Position of the adjustment handle in the shape's coordinate system. */
+    pos: AdjustPoint;
+};
+
+/**
+ * XY adjustment handle for custom shapes.
+ *
+ * Defines an interactive handle that can be dragged to adjust shape geometry
+ * using Cartesian coordinates (X and Y positions).
+ */
+type AdjustValueHandleXY = {
+    /** Type discriminator for XY adjustment handles. */
+    type: 'xy';
+    /** Name of the guide that this handle adjusts for the X axis. */
+    gdRefX?: GeomGuideName;
+    /** Maximum X coordinate value allowed for this handle (as coordinate or reference to guide). */
+    maxX?: GeomGuideName | EmuValue;
+    /** Minimum X coordinate value allowed for this handle (as coordinate or reference to guide). */
+    minX?: GeomGuideName | EmuValue;
+    /** Name of the guide that this handle adjusts for the Y axis. */
+    gdRefY?: GeomGuideName;
+    /** Maximum Y coordinate value allowed for this handle (as coordinate or reference to guide). */
+    maxY?: GeomGuideName | EmuValue;
+    /** Minimum Y coordinate value allowed for this handle (as coordinate or reference to guide). */
+    minY?: GeomGuideName | EmuValue;
+    /** Position of the adjustment handle in the shape's coordinate system. */
+    pos: AdjustPoint;
+};
+
+/**
+ * Specifies how an object should be rendered when specified to be in black and white mode
+ *
+ * | Value                          | Color rendering
+ * |--------------------------------|--------------------------------
+ * | `auto` (Automatic)             | Rendered with automatic coloring
+ * | `black` (Black)                | Rendered with black-only coloring
+ * | `blackGray` (Black and Gray)   | Rendered with black and gray coloring
+ * | `blackWhite` (Black and White) | Rendered within black and white coloring
+ * | `clr` (Color)                  | Rendered with normal coloring
+ * | `gray` (Gray)                  | Rendered with gray coloring
+ * | `grayWhite` (Gray and White)   | Rendered within gray and white coloring
+ * | `hidden` (Hidden)              | Rendered with hidden coloring
+ * | `invGray` (Inverse Gray)       | Rendered with inverse gray coloring
+ * | `ltGray` (Light Gray)          | Rendered with light gray coloring
+ * | `white` (White)                | Rendered within white coloring
+ */
+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.
+ */
+type ConnectionPoint = {
+    /** The position of the connection point on the shape */
+    pos: AdjustPoint;
+    /**
+     * The angle of the connection point, either as a specific angle or a reference
+     * to a geometry guide
+     */
+    ang?: DmlAngle | GeomGuideName;
+};
+
+type FontStyleIndex = 'major' | 'minor' | 'none';
+
+/**
+ * Guide point for custom shape geometry.
+ *
+ * Defines a named calculation point that can be referenced in shape paths
+ * and used to create parameterized, adjustable geometry.
+ */
+type GuidePoint = {
+    /**
+     * Name identifier for this guide point, used to reference it in formulas and paths.
+     */
+    name: string;
+    /**
+     * Formula expression defining the guide point's value (e.g., "val 50000" for a constant value).
+     */
+    fmla: string;
+};
+
+/**
+ * Shape text margin rectangle.
+ *
+ * Defines the inset rectangle within a shape where text should be positioned,
+ * specified using adjustable coordinates relative to the shape's geometry.
+ */
+type ShapeRect = {
+    /** Top edge inset from shape bounds. */
+    t: AdjustCoordinate;
+    /** Left edge inset from shape bounds. */
+    l: AdjustCoordinate;
+    /** Bottom edge inset from shape bounds. */
+    b: AdjustCoordinate;
+    /** Right edge inset from shape bounds. */
+    r: AdjustCoordinate;
+};
+
+/**
+ * Transform directions to be applied to drawn graphic objects.
+ */
+type Xfrm = {
+    /**
+     * Which axes the shape should be flipped about.
+     * @defaultValue "none"
+     */
+    flip?: FlipAxis;
+    /**
+     * Rotation angle in 60,000ths of a degree.
+     * @defaultValue 0
+     */
+    rot?: DmlAngle;
+    /**
+     * Offset/position of the graphic object.
+     */
+    off?: Point;
+    /** Extents/size of the graphic object. */
+    ext?: Extent;
+};
+
+type ShapeStyle = {
+    line?: {
+        color: Color;
+        index: number;
+    };
+    fill?: {
+        color: Color;
+        index: number;
+    };
+    effect?: {
+        color: Color;
+        index: number;
+    };
+    font?: {
+        color: Color;
+        index: FontStyleIndex;
+    };
+};
+
+/**
+ * Shape visual and geometric properties.
+ *
+ * Defines the complete visual styling and custom geometry for a shape,
+ * including fill, line, transformation, custom paths, and interactive handles.
+ */
+type Shape = {
+    /** 2D transformation (position, rotation, scale). */
+    xfrm?: Xfrm;
+    /** Black-and-white rendering mode for grayscale or duotone display. */
+    bwMode?: BlackWhiteMode;
+    /** Preset shape type identifier (e.g., "rect", "ellipse", "roundRect"). */
+    preset?: string;
+    /** Visual style references (fill, line, effect styles from theme). */
+    style?: ShapeStyle;
+    /** Custom geometry paths defining the shape outline. */
+    paths?: Path[];
+    /** Text margin rectangle (inset from shape bounds for text positioning). */
+    rect?: ShapeRect;
+    /** Adjustment handles, allowing interactive shape geometry modification. */
+    ah?: (AdjustValueHandleXY | AdjustValueHandlePolar)[];
+    /** Adjustment values (guide points that store user-adjustable parameters). */
+    av?: GuidePoint[];
+    /** Shape guides (calculated points used in geometry formulas). */
+    gd?: GuidePoint[];
+    /** Connection points for attaching connectors to the shape. */
+    cxn?: ConnectionPoint[];
+    /** Line/outline styling properties. */
+    line?: Line;
+    /** Fill styling (solid, gradient, pattern, image, or none). */
+    fill?: Fill;
+};
+
+/**
+ * Bitmap graphic / Picture.
+ */
+type GraphicBitmap = {
+    /** Type discriminator for bitmap graphics. */
+    type: 'bitmap';
+    /** Unique identifier for this bitmap object. */
+    id: string;
+    /** Display name of the bitmap. */
+    name: string;
+    /**
+     * Reference to the media/image resource to use.
+     * @see {@link Workbook.images}.
+     */
+    mediaId: string;
+    /** Optional description or alt text for the bitmap. */
+    desc?: string;
+    /** Visual styling properties (fill, line, effects, etc.). */
+    shape?: Shape;
+    /** Whether to lock the aspect ratio when resizing. */
+    noChangeAspect?: boolean;
+    /** 2D transformation (position, rotation, scale). */
+    xfrm?: Xfrm;
+    /** Optional text content overlaid on the bitmap. */
+    text?: TextBody;
+    /**
+     * Opacity value (0-100, where 100 is fully opaque).
+     * @min 0
+     * @max 100
+     * @defaultValue 0
+     */
+    alpha?: Percentage;
+    /** Rectangle defining how the image should be stretched (relative coordinates). */
+    stretchRect?: RelativeRect;
+    /** Rectangle defining the source crop area of the image (relative coordinates). */
+    srcRect?: RelativeRect;
+};
+
+/**
+ * A chart or plot.
+ */
+type GraphicChart = {
+    /** Type discriminator for a chart. */
+    type: 'chart';
+    /** Unique identifier for this chart. */
+    id: string;
+    /** Display name of the chart. */
+    name: string;
+    /** ID */
+    chartId: string;
+    /** 2D transformation (position, rotation, scale). */
+    xfrm?: Xfrm;
+};
+
+/**
+ * Connection shape (connector).
+ *
+ * Represents a connector or line shape that connects two other shapes,
+ * typically used for creating diagrams, flowcharts, and organizational charts.
+ */
+type GraphicConnectionShape = {
+    /** Type discriminator for connection shapes. */
+    type: 'connectionShape';
+    /** Unique identifier for this connection shape. */
+    id: string;
+    /** Display name of the connection shape. */
+    name: string;
+    /** Visual styling properties (line style, color, effects, etc.). */
+    shape?: Shape;
+    /** 2D transformation (position, rotation, scale). */
+    xfrm?: Xfrm;
+    /** Optional text content displayed on or near the connector. */
+    text?: TextBody;
+};
+
+/**
+ * Transform directions to be applied to group objects.
+ */
+type XfrmGroup = Xfrm & {
+    /** Child offset - position of child elements within a group. */
+    chOff?: Point;
+    /** Child extents - size of the child coordinate system within a group. */
+    chExt?: Extent;
+};
+
+/**
+ * Group shape container.
+ *
+ * Represents a collection of graphic objects grouped together as a single unit,
+ * allowing them to be transformed, moved, and manipulated collectively.
+ */
+type GraphicGroup = {
+    /** Type discriminator for group shapes. */
+    type: 'group';
+    /** Unique identifier for this group. */
+    id: string;
+    /** Display name of the group. */
+    name: string;
+    /** Array of graphic objects contained within this group. */
+    content: Graphic[];
+    /** 2D transformation applied to the group (position, rotation, scale). */
+    xfrm?: XfrmGroup;
+};
+
+/**
+ * Basic shape object.
+ *
+ * Represents a standard geometric shape (rectangle, circle, arrow, etc.)
+ * with customizable geometry, styling, and text content.
+ */
+type GraphicShape = {
+    /** Type discriminator for basic shapes. */
+    type: 'shape';
+    /** Unique identifier for this shape. */
+    id: string;
+    /** Display name of the shape. */
+    name: string;
+    /** 2D transformation (position, rotation, scale). */
+    xfrm?: Xfrm;
+    /** Visual styling properties (fill, line, effects, geometry preset, etc.). */
+    shape?: Shape;
+    /** Optional text content displayed within the shape. */
+    text?: TextBody;
+};
+
+/** A graphic element.  */
+type Graphic = GraphicChart | GraphicBitmap | GraphicShape | GraphicConnectionShape | GraphicGroup;
+
+/**
+ * A drawing.
+ *
+ * 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.
+ */
+type Drawing = {
+    /** Defines how the drawing is placed onto a worksheet's cell-grid. */
+    anchor: GraphicAnchor;
+    /** The graphical elements that make up the drawing. */
+    content: Graphic[];
+};
+
 /**
  * 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.
@@ -273,14 +1508,6 @@ type BorderStyle =
 /** Draw a 1px wide pixel continuous line.*/
 'thin';
 
-/**
- * A hex-encoded RGB or RGBA value that conforms to the CSS4 color specification (e.g. `"#3cb371"`).
- *
- * @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})$
- */
-type Color = `#${string}`;
-
 /**
  * Specifies the horizontal alignment of content (text) within a container (cell).
  */
@@ -578,125 +1805,6 @@ type Table = {
     style?: TableStyle;
 };
 
-/**
- * Base type for text runs that annotate ranges within threaded comment text.
- *
- * A text run identifies a contiguous range of characters in the comment text, specified by
- * zero-indexed start and end positions. Text runs allow metadata to be attached to specific
- * portions of text, enabling features such as hyperlinks, mentions, and formatting.
- *
- * ## How text runs work
- *
- * Each text run specifies a range within the comment text using `start` (inclusive) and `end`
- * (exclusive) character positions. For example, in the text "Hello @foo", a mention text run
- * for "@foo" would have `start: 6` and `end: 10`.
- *
- * Multiple text runs can exist within a single comment, allowing different types of annotations
- * to coexist (a mention and a hyperlink in the same text, for example).
- *
- * @see {@link MentionTextRun} for mentions of people
- * @see {@link HyperlinkTextRun} for hyperlinks
- */
-type TextRun = {
-    /** Starting character position of the run in the text (zero-indexed). */
-    start: integer;
-    /** Ending character position of the run in the text (zero-indexed, exclusive). */
-    end: integer;
-};
-
-/**
- * A {@link TextRun | text run} representing a hyperlink within a threaded comment's text.
- */
-type HyperlinkTextRun = TextRun & {
-    /** Discriminator to identify this as a hyperlink text run. */
-    type: 'hyperlink';
-    /** The URL that the hyperlink points to. */
-    url: string;
-};
-
-/**
- * A {@link TextRun | text run} representing a mention of a person within a threaded comment's text.
- */
-type MentionTextRun = TextRun & {
-    /** Discriminator to identify this as a mention text run. */
-    type: 'mention';
-    /**
-     * Unique identifier of the person being mentioned. Use this to find the person's details in a
-     * {@link Workbook.people | workbook's list of people}.
-     *
-     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
-     * no strict requirement.
-     */
-    personId: string;
-};
-
-/**
- * An author of a threaded comment, or a person mentioned in a threaded comment.
- */
-type Person = {
-    /**
-     * A unique id for the person.
-     *
-     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
-     * no strict requirement.
-     */
-    id: string;
-    /** The person's name as it should be shown to other users. */
-    displayName: string;
-    /**
-     * Optional provider-issued user identifier that varies in format depending on the provider. See
-     * {@link Person.providerId} for details on possible values.
-     */
-    userId?: string;
-    /**
-     * Specifies where the person's information came from. Excel supports the following values:
-     *
-     * - `None`: no specific provider; {@link Person.userId} is expected to be the person's name.
-     * - `AD`: Active Directory; {@link Person.userId} will be Active Directory id.
-     * - `Windows Live`: Microsoft account; {@link Person.userId} will be a 64-bit signed decimal.
-     * - `PeoplePicker`: SharePoint People Picker; {@link Person.userId} will be an email address.
-     */
-    providerId?: string;
-};
-
-/**
- * A threaded comment that is attached to an individual cell.
- */
-type ThreadedComment = {
-    /**
-     * Unique identifier for the comment.
-     *
-     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
-     * no strict requirement.
-     */
-    id: string;
-    /**
-     * Unique identifier of the parent comment, if this is a reply in a thread.
-     *
-     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
-     * no strict requirement.
-     */
-    parentId?: string;
-    /** A1-style reference to the cell this comment is attached to. */
-    ref: CellId;
-    /** Date and time the comment was written, as an ISO formatted string. */
-    datetime?: string;
-    /**
-     * Unique identifier of the person who authored this comment. Use this to find the person's
-     * details in a {@link Workbook.people | workbook's list of people}.
-     *
-     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
-     * no strict requirement.
-     */
-    personId: string;
-    /** The comment text content. */
-    text: string;
-    /** Whether the comment has been marked as resolved. */
-    resolved?: boolean;
-    /** {@link TextRun | Text runs} that annotate ranges within the comment text. */
-    runs?: (MentionTextRun | HyperlinkTextRun)[];
-};
-
 /**
  * Directions on how formulas should be recalculated in the workbook.
  */
@@ -705,23 +1813,33 @@ type CalcProps = {
      * Specifies whether an attempt should be made to calculate formulas that contain circular
      * references. Defaults to `false` in Excel.
      */
-    iterate: boolean;
+    iterate?: boolean;
     /**
      * The maximum number of calculation iterations, when {@link CalcProps.iterate} is `true`.
      * Defaults to `100` in Excel.
      */
-    iterateCount: integer;
+    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;
+    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';
 };
 
 /**
@@ -840,6 +1958,8 @@ type Worksheet = {
     showGridLines?: boolean;
     /** The different display configurations saved for the worksheet. */
     views?: WorksheetView[];
+    /** A list of drawings that appear in this worksheet. */
+    drawing?: Drawing[];
 };
 
 /**
@@ -898,6 +2018,30 @@ type Workbook = {
      * @see {@link ThreadedComment}
      */
     people?: Person[];
+    /**
+     * A simple dictionary of binary images used by this workbook.
+     *
+     * The keys should be the file paths of the images used to refer to them, commonly these will be
+     * the `mediaId` properties on drawing objects. The values should be data URI encoded binaries.
+     *
+     * The following is a table of formats you may be expected to encounter:
+     *
+     *  | Extension               | MIME type              | Common name
+     *  |-------------------------|------------------------|-------------
+     *  | `.png`                  | `image/png`            | Portable Network Graphics
+     *  | `.jpg`, `.jpeg`         | `image/jpeg`           | JPEG
+     *  | `.gif`                  | `image/gif`            | Graphics Interchange Format
+     *  | `.emf`                  | `image/emf`            | Enhanced Metafile
+     *  | `.wmf`                  | `image/wmf`            | Windows Metafile
+     *  | `.wdp`, `.jxr`, `.hdp`  | `image/vnd.ms-photo`   | Windows Media Photo / JPEG XR
+     *  | `.bmp`                  | `image/bmp`            | Bitmap
+     *  | `.tif`, `.tiff`         | `image/tiff`           | Tagged Image File Format
+     *  | `.svg`                  | `image/svg+xml`        | Scalable Vector Graphics
+     *
+     * @see {@link https://en.wikipedia.org/wiki/Data_URI_scheme}
+     * @see {@link https://www.rfc-editor.org/rfc/rfc2397}
+     */
+    images?: Record<string, string>;
 };
 
-export type { BorderStyle, CalcProps, Cell, CellId, CellRange, CellValueType, Color, Comment, DataTable, DefinedName, External, ExternalWorksheet, GridSize, HAlign, HyperlinkTextRun, MentionTextRun, Note, PatternStyle, Person, PixelValue, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextRun, ThreadedComment, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView };
+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 };