@silurus/ooxml 0.56.0 → 0.57.0

package/dist/types/pptx.d.ts

@@ -32,7 +32,20 @@ export declare interface AutoResizeOptions {
     pauseWhenHidden?: boolean;
 }
 
-declare type Bullet = {
+/**
+ * `<a:bevel>` — ECMA-376 §20.1.5.3 (`CT_Bevel`). Lengths in EMU; `w`/`h`
+ * default to 76200 EMU and `prst` to "circle".
+ */
+export declare interface Bevel3d {
+    /** Bevel width in EMU. */
+    w: number;
+    /** Bevel height in EMU. */
+    h: number;
+    /** Bevel preset name (`ST_BevelPresetType`). */
+    prst: string;
+}
+
+export declare type Bullet = {
     type: 'none';
 } | {
     type: 'inherit';
@@ -48,6 +61,21 @@ declare type Bullet = {
     startAt: number | null;
 };
 
+/**
+ * `<a:camera>` — ECMA-376 §20.1.5.5 (`CT_Camera`). `prst` selects one of the
+ * 62 preset cameras (§20.1.10.47); `fov`/`zoom`/`rot` optionally override it.
+ */
+export declare interface Camera3d {
+    /** Preset camera name (`ST_PresetCameraType`), e.g. "perspectiveRelaxed". */
+    prst: string;
+    /** Field-of-view override in degrees. Omitted = preset default. */
+    fov?: number;
+    /** Zoom factor as a unit ratio (1.0 = 100%). Omitted = 1.0. */
+    zoom?: number;
+    /** Camera rotation override. Omitted = preset base orientation. */
+    rot?: Rot3d;
+}
+
 declare interface ChartDataLabelOverride {
     idx: number;
     /** Empty string = label deleted (skip drawing). */
@@ -75,7 +103,7 @@ declare interface ChartDataPointOverride {
  * top level, alongside the element position (x/y/width/height in EMU).
  * Pass this straight to `renderChart` from `@silurus/ooxml-core`.
  */
-declare interface ChartElement {
+export declare interface ChartElement {
     type: 'chart';
     x: number;
     y: number;
@@ -185,7 +213,170 @@ declare interface ChartManualLayout {
     h?: number;
 }
 
-declare interface ChartSeries {
+export declare interface ChartModel {
+    chartType: ChartType;
+    title: string | null;
+    categories: string[];
+    series: ChartSeries[];
+    /** Show data labels on bars / points / slices. */
+    showDataLabels: boolean;
+    /** Explicit Y-axis minimum (OOXML `<c:valAx><c:min>`). */
+    valMin: number | null;
+    /** Explicit Y-axis maximum (OOXML `<c:valAx><c:max>`). */
+    valMax: number | null;
+    catAxisTitle: string | null;
+    valAxisTitle: string | null;
+    /** `<c:catAx><c:delete val="1"/>`. */
+    catAxisHidden: boolean;
+    /** `<c:valAx><c:delete val="1"/>`. */
+    valAxisHidden: boolean;
+    /** `<c:catAx><c:spPr><a:ln><a:noFill>` — hide just the axis LINE; labels
+     *  and tick marks still render. Distinct from `catAxisHidden` (which
+     *  removes everything via `<c:delete val="1"/>`). */
+    catAxisLineHidden: boolean;
+    /** `<c:valAx><c:spPr><a:ln><a:noFill>` — hide just the axis LINE; labels
+     *  and tick marks still render. */
+    valAxisLineHidden: boolean;
+    /** Hex without '#'. From `<c:plotArea><c:spPr><a:solidFill>`. */
+    plotAreaBg: string | null;
+    /** Outer chartSpace background (hex without '#'). null when noFill/absent. */
+    chartBg: string | null;
+    /** True when `<c:legend>` is declared in the chart XML. False = no legend. */
+    showLegend: boolean;
+    /** `<c:legend><c:legendPos val>` — "r"|"l"|"t"|"b"|"tr". null = default (r). */
+    legendPos: 'r' | 'l' | 't' | 'b' | 'tr' | null;
+    /** `<c:catAx><c:crossBetween val="..."/>`. "between" inserts 0.5-step padding
+     *  on each end of the category axis; "midCat" anchors endpoints to the axes. */
+    catAxisCrossBetween: 'between' | 'midCat' | string;
+    /** `<c:valAx><c:majorTickMark>`. ECMA-376 default is "cross". */
+    valAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:catAx><c:majorTickMark>`. */
+    catAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:valAx | catAx><c:minorTickMark>`. ECMA-376 default is "none". */
+    valAxisMinorTickMark?: 'cross' | 'out' | 'in' | 'none' | string | null;
+    catAxisMinorTickMark?: 'cross' | 'out' | 'in' | 'none' | string | null;
+    /** Title font size in OOXML hundredths of a point (1600 = 16pt). null = default. */
+    titleFontSizeHpt: number | null;
+    /** Title font color as a hex string without '#' (e.g. "1B4332"). null = default. */
+    titleFontColor: string | null;
+    /** Title font family from `<a:latin typeface>` (ECMA-376 §20.1.4.2.24). null = default. */
+    titleFontFace: string | null;
+    /** `<c:catAx><c:txPr>` font size (hpt). null = fall back to proportional default. */
+    catAxisFontSizeHpt: number | null;
+    /** `<c:valAx><c:txPr>` font size (hpt). null = fall back to proportional default. */
+    valAxisFontSizeHpt: number | null;
+    /** `<c:catAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#').
+     *  null = renderer default. Lets templates color category labels gray. */
+    catAxisFontColor?: string | null;
+    /** `<c:valAx><c:txPr>…<a:solidFill>` tick-label color (hex without '#'). */
+    valAxisFontColor?: string | null;
+    /** `<c:dLbls><c:txPr>` font size (hpt) for data-point value labels. */
+    dataLabelFontSizeHpt: number | null;
+    /** Waterfall subtotal category indices. */
+    subtotalIndices: number[];
+    /** `<c:legend><c:manualLayout>` absolute placement fractions of the chart
+     *  space (ECMA-376 §21.2.2.31). Overrides the default side-based legend
+     *  rectangle while still letting `legendPos` decide which side of the plot
+     *  gets the reserved band. null = use default layout. */
+    legendManualLayout?: LegendManualLayout | null;
+    /**
+     * `<c:valAx><c:numFmt@formatCode>` — format code applied to value-axis tick
+     * labels (ECMA-376 §21.2.2.21). null = plain numeric formatting.
+     */
+    valAxisFormatCode?: string | null;
+    /**
+     * `<c:barChart><c:gapWidth>` — space between category groups as a
+     * percentage of bar width (ECMA-376 §21.2.2.13). Default per spec is 150.
+     * null = renderer default.
+     */
+    barGapWidth?: number | null;
+    /**
+     * `<c:barChart><c:overlap>` — signed percentage overlap between bars in the
+     * same category cluster (ECMA-376 §21.2.2.25). Negative = gap, positive =
+     * overlap, 0 = flush. Range [-100, 100]. null = renderer default (0).
+     */
+    barOverlap?: number | null;
+    /**
+     * `<c:dLbls><c:dLblPos>` — data label position (ECMA-376 §21.2.2.16).
+     * "ctr"|"inBase"|"inEnd"|"outEnd"|"l"|"r"|"t"|"b"|"bestFit" etc.
+     */
+    dataLabelPosition?: string | null;
+    /** Hex (no `#`) for data label text, resolved from `<c:dLbls><c:txPr>`. */
+    dataLabelFontColor?: string | null;
+    /**
+     * `<c:dLbls><c:numFmt@formatCode>` — chart-level override for data label
+     * number format (ECMA-376 §21.2.2.35). When absent, `valFormatCode` on each
+     * series is used.
+     */
+    dataLabelFormatCode?: string | null;
+    /** `<c:title>...defRPr@b>` chart title bold flag. */
+    titleFontBold?: boolean | null;
+    /** `<c:catAx><c:txPr>...defRPr@b>` X-axis tick label bold flag. */
+    catAxisFontBold?: boolean | null;
+    /** `<c:valAx><c:txPr>...defRPr@b>` Y-axis tick label bold flag. */
+    valAxisFontBold?: boolean | null;
+    /**
+     * `<c:catAx><c:crosses val>` (`autoZero` | `min` | `max`). Drives the Y
+     * coordinate where the X axis is drawn. Default `autoZero` puts the X
+     * axis at y=0 — that's how Excel "Project Timeline" templates split
+     * milestones (positive Y) above and tasks (negative Y) below the axis.
+     */
+    catAxisCrosses?: string | null;
+    /** `<c:catAx><c:crossesAt val>` — explicit numeric override for the
+     *  crossing point. Takes precedence over `catAxisCrosses`. */
+    catAxisCrossesAt?: number | null;
+    valAxisCrosses?: string | null;
+    valAxisCrossesAt?: number | null;
+    /** Axis line color (hex without `#`) and width in EMU from
+     *  `<c:catAx|valAx><c:spPr><a:ln>`. */
+    catAxisLineColor?: string | null;
+    catAxisLineWidthEmu?: number | null;
+    valAxisLineColor?: string | null;
+    valAxisLineWidthEmu?: number | null;
+    /**
+     * `<c:catAx><c:numFmt@formatCode>` (or scatter X-axis valAx). When set,
+     * the renderer formats X-axis tick labels with this code (e.g. dates).
+     */
+    catAxisFormatCode?: string | null;
+    /**
+     * `<c:catAx><c:scaling><c:min/max>` — explicit X-axis range. Used by
+     * scatter / bubble charts whose X axis is numeric. null = derive from
+     * data extents.
+     */
+    catAxisMin?: number | null;
+    catAxisMax?: number | null;
+    /**
+     * `<c:title><c:layout><c:manualLayout>` (ECMA-376 §21.2.2.27) absolute
+     * placement for the chart title.
+     */
+    titleManualLayout?: ChartManualLayout | null;
+    /**
+     * `<c:plotArea><c:layout><c:manualLayout>` absolute placement for the
+     * plot area. `layoutTarget="inner"` (default) describes the inner plot
+     * rect (no axes / labels); `outer` describes the outer rect (axes
+     * included).
+     */
+    plotAreaManualLayout?: ChartManualLayout | null;
+    /**
+     * `<c:scatterChart><c:scatterStyle val>` (ECMA-376 §21.2.2.42). Drives
+     * whether scatter charts connect points with lines and whether those
+     * lines are smoothed. Values: "marker" (markers only — Excel default
+     * "Scatter"), "line" / "lineMarker" (straight segments), "smooth" /
+     * "smoothMarker" (cubic Bézier through points), "lineNoMarker",
+     * "smoothNoMarker". null = renderer default ("marker"). Only consulted
+     * for `chartType === "scatter"`; bubble ignores it.
+     */
+    scatterStyle?: string | null;
+    /**
+     * `<c:radarChart><c:radarStyle val>` (ECMA-376 §21.2.3.10). Controls
+     * whether radar series render as line + markers ("standard" / "marker")
+     * or as a closed polygon with area fill ("filled"). null = default
+     * ("standard" — line, no fill). Only consulted for `chartType === "radar"`.
+     */
+    radarStyle?: string | null;
+}
+
+export declare interface ChartSeries {
     name: string;
     /** Hex without '#'. null = fall back to palette. */
     color: string | null;
@@ -299,6 +490,13 @@ declare interface ChartSeriesDataLabels {
     fontSizeHpt?: number;
 }
 
+/**
+ * Canonical chart type vocabulary. Embeds direction (`H` = horizontal) and
+ * grouping (`Pct` = percent-stacked) so renderers do not need to inspect
+ * separate `barDir`/`grouping` fields.
+ */
+declare type ChartType = 'line' | 'stackedLine' | 'stackedLinePct' | 'clusteredBar' | 'clusteredBarH' | 'stackedBar' | 'stackedBarH' | 'stackedBarPct' | 'stackedBarHPct' | 'area' | 'stackedArea' | 'stackedAreaPct' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'radar' | 'waterfall' | string;
+
 /**
  * An OMML equation embedded in a paragraph (ECMA-376 §22.1). Parsed into the
  * shared math AST and rendered by `@silurus/ooxml-core`'s math engine.
@@ -319,14 +517,14 @@ declare interface EquationRun {
 export declare type Fill = SolidFill | NoFill | GradientFill | PatternFill;
 
 /** ECMA-376 §20.1.8.17 (CT_GlowEffect) — coloured halo with blur radius. */
-declare interface Glow {
+export declare interface Glow {
     color: string;
     alpha: number;
     /** Blur radius in EMU. */
     radius: number;
 }
 
-declare interface GradientFill {
+export declare interface GradientFill {
     fillType: 'gradient';
     stops: GradientStop[];
     /** degrees: 0 = left→right, 90 = top→bottom */
@@ -335,11 +533,36 @@ declare interface GradientFill {
     gradType: string;
 }
 
-declare interface GradientStop {
+export declare interface GradientStop {
     position: number;
     color: string;
 }
 
+declare interface LegendManualLayout {
+    /** `"edge"` = `x`/`y` are fractions from top-left of chart space;
+     *  `"factor"` = fractions offset from the default position. */
+    xMode: string;
+    yMode: string;
+    /** Fractions of chart space width/height. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+/**
+ * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Parsed for Phase B
+ * (lighting/bevel shading); the Phase A camera renderer ignores it.
+ */
+export declare interface LightRig {
+    /** Light-rig preset (`ST_LightRigType`), e.g. "threePt". */
+    rig: string;
+    /** Light direction (`ST_LightRigDirection`): tl/t/tr/l/r/bl/b/br. */
+    dir: string;
+    /** Optional rotation override of the rig. */
+    rot?: Rot3d;
+}
+
 export declare interface LineBreak {
     type: 'break';
 }
@@ -521,7 +744,7 @@ declare interface MathSvg {
     descentEm: number;
 }
 
-declare interface MediaElement {
+export declare interface MediaElement {
     type: 'media';
     x: number;
     y: number;
@@ -574,7 +797,7 @@ export declare interface Paragraph {
     runs: TextRun[];
 }
 
-declare type PathCmd = {
+export declare type PathCmd = {
     cmd: 'moveTo';
     x: number;
     y: number;
@@ -625,8 +848,29 @@ export declare interface PictureElement {
     flipV: boolean;
     /** Data URL, e.g. "data:image/png;base64,..." */
     dataUrl: string;
-    /** OOXML adj value (0–100000) for roundRect clip, null = plain rectangle */
-    clipAdjust: number | null;
+    /**
+     * Border line from `<p:pic><p:spPr><a:ln>` (ECMA-376 §20.1.2.2.24). A
+     * `p:pic`'s spPr is `CT_ShapeProperties` (§19.3.1.37), so a picture carries
+     * the same line model as a shape. `null` when there is no `<a:ln>` or it
+     * resolves to `<a:noFill/>` (border explicitly suppressed). The border is
+     * stroked along the picture's clip silhouette (roundRect / custGeom / rect).
+     */
+    stroke: Stroke | null;
+    /**
+     * `<p:spPr><a:prstGeom prst="…">` preset name (e.g. `"roundRect"`,
+     * `"ellipse"`). ECMA-376 §20.1.9.18: a picture's preset geometry is its clip
+     * silhouette and the path its border / contour hug. Undefined / omitted = a
+     * plain rectangle (`prst="rect"` or no prstGeom). When set, the renderer
+     * builds the silhouette via the shared preset-geometry engine (any of the 186
+     * presets). `custGeom` takes priority when both are present.
+     */
+    prstGeom?: string;
+    /**
+     * Adjust guides from the prstGeom `<a:avLst>` (1/1000-of-a-percent OOXML
+     * units), in `gd@name` declaration order (index 0 = adj/adj1, 1 = adj2, …).
+     * Omitted when avLst is empty — the preset's own declared defaults then apply.
+     */
+    prstAdjust?: number[];
     /**
      * ECMA-376 a:srcRect — source image crop as fractions (0..1) of the source
      * width/height. Omitted when the image is not cropped.
@@ -647,6 +891,27 @@ export declare interface PictureElement {
      * trimmed to the laptop / device silhouette declared in the file.
      */
     custGeom?: PathCmd[][] | null;
+    /**
+     * Drop shadow from `spPr > effectLst > outerShdw`. A `p:pic`'s `spPr` is
+     * `CT_ShapeProperties` (ECMA-376 §19.3.1.37), so the same effects shapes
+     * carry apply to images. ECMA-376 §20.1.8.45 (CT_OuterShadowEffect).
+     */
+    shadow?: Shadow;
+    /** Inner (inset) shadow from effectLst > innerShdw. ECMA-376 §20.1.8.40. */
+    innerShadow?: Shadow;
+    /** Coloured glow halo from effectLst > glow. ECMA-376 §20.1.8.32. */
+    glow?: Glow;
+    /** Soft (feathered) edge from effectLst > softEdge. ECMA-376 §20.1.8.53. */
+    softEdge?: SoftEdge;
+    /** Mirrored reflection from effectLst > reflection. ECMA-376 §20.1.8.50. */
+    reflection?: Reflection;
+    /** `<a:scene3d>` 3D camera scene (ECMA-376 §20.1.5.5). A `p:pic`'s spPr is
+     *  `CT_ShapeProperties`, so 3D scenes apply to images. When non-identity the
+     *  renderer projects the picture through the camera homography (Phase A). */
+    scene3d?: Scene3d;
+    /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
+     *  rendered in Phase A. */
+    sp3d?: Sp3d;
 }
 
 /**
@@ -696,9 +961,9 @@ export declare class PptxPresentation {
     private _findMimeTypeForPath;
     /**
      * Render a slide and attach canvas-native playback controls for any
-     * embedded audio/video. Returns a disposable handle that owns the RAF loop,
-     * media elements, and object URLs. Unlike {@link renderSlide}, this method
-     * is stateful — always call `handle.dispose()` when leaving the slide.
+     * embedded audio/video. Returns a {@link PresentationHandle} that owns the
+     * RAF loop, media elements, and object URLs. Unlike {@link renderSlide}, this
+     * method is stateful — always call `handle.destroy()` when leaving the slide.
      */
     presentSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<PresentationHandle>;
     /** Terminate the worker and release all resources. */
@@ -814,16 +1079,22 @@ export declare interface Presentation {
     folHlinkColor?: string;
 }
 
-declare interface PresentationHandle {
+export declare interface PresentationHandle {
     play(mediaPath?: string): void;
     pause(mediaPath?: string): void;
-    dispose(): void;
+    /**
+     * Stop the playback RAF loop, detach pointer listeners and release every
+     * media blob URL. Named `destroy()` to match the teardown method on the
+     * viewers/documents (`PptxViewer.destroy()`, `XlsxWorkbook.destroy()`, …)
+     * so the public API uses one consistent teardown verb.
+     */
+    destroy(): void;
 }
 
 /** ECMA-376 §20.1.8.27 (CT_ReflectionEffect) — mirrored copy below the
  *  shape with a linear alpha gradient. Carries the spec attributes whose
  *  defaults the renderer needs to interpret correctly. */
-declare interface Reflection {
+export declare interface Reflection {
     blur: number;
     dist: number;
     /** Direction in degrees, clockwise from East. */
@@ -887,7 +1158,31 @@ export declare interface RenderSlideOptions {
     skipMediaControls?: boolean;
 }
 
-declare interface Shadow {
+/**
+ * 3D rotation in sphere coordinates — ECMA-376 §20.1.5.11 (`CT_SphereCoords`).
+ * Angles are in **degrees** (the XML carries 60000ths of a degree; the parser
+ * divides once). Per the spec, `lat`/`lon` are latitude/longitude and `rev` is
+ * the revolution about the resulting view axis.
+ */
+export declare interface Rot3d {
+    /** Latitude — rotation about the horizontal (X) axis, degrees. */
+    lat: number;
+    /** Longitude — rotation about the vertical (Y) axis, degrees. */
+    lon: number;
+    /** Revolution — in-plane rotation about the view (Z) axis, degrees. */
+    rev: number;
+}
+
+/**
+ * `<a:scene3d>` — ECMA-376 §20.1.4.1.41 (`CT_Scene3D`). Camera + light rig for
+ * a shape's 3D scene.
+ */
+export declare interface Scene3d {
+    camera: Camera3d;
+    lightRig?: LightRig;
+}
+
+export declare interface Shadow {
     color: string;
     alpha: number;
     blur: number;
@@ -945,6 +1240,13 @@ export declare interface ShapeElement {
      *  same space as x/y/width/height). When present the renderer lays text out in
      *  this rectangle instead of the preset/ellipse-derived text rectangle. */
     textRect?: TextRect;
+    /** `<a:scene3d>` 3D camera scene (ECMA-376 §20.1.5.5). When the camera is
+     *  non-identity the renderer projects the shape through the camera
+     *  homography (Phase A). */
+    scene3d?: Scene3d;
+    /** `<a:sp3d>` 3D shape properties (ECMA-376 §20.1.5.12). Parsed but not
+     *  rendered in Phase A. */
+    sp3d?: Sp3d;
 }
 
 export declare interface Slide {
@@ -968,7 +1270,7 @@ declare type SlideRenderOptions = RenderOptions & {
 };
 
 /** ECMA-376 §20.1.8.31 (CT_SoftEdgesEffect) — feather radius in EMU. */
-declare interface SoftEdge {
+export declare interface SoftEdge {
     radius: number;
 }
 
@@ -977,7 +1279,32 @@ export declare interface SolidFill {
     color: string;
 }
 
-declare type SpaceLine = {
+/**
+ * `<a:sp3d>` — ECMA-376 §20.1.5.12 (`CT_Shape3D`). Parsed in full but **not
+ * rendered in Phase A** (camera-only). bevel/contour/extrusion are Phase B.
+ * Numeric fields are omitted from JSON when zero.
+ */
+export declare interface Sp3d {
+    /** Z position of the front face in EMU (default 0). */
+    z?: number;
+    /** Extrusion (depth) height in EMU (default 0). */
+    extrusionH?: number;
+    /** Contour (outline) width in EMU (default 0). */
+    contourW?: number;
+    /** Contour colour (`<a:contourClr>`, ECMA-376 §20.1.5.12) as a hex string
+     *  (e.g. "969696"). Omitted when absent. The renderer draws a flat
+     *  approximation of the 3D contour edge (uniform-width outline, no bevel
+     *  shading) when both `contourW` and `contourClr` are present. */
+    contourClr?: string;
+    /** Preset surface material (`ST_PresetMaterialType`), default "warmMatte". */
+    prstMaterial: string;
+    /** Top bevel. */
+    bevelT?: Bevel3d;
+    /** Bottom bevel. */
+    bevelB?: Bevel3d;
+}
+
+export declare type SpaceLine = {
     type: 'pct';
     val: number;
 } | {
@@ -1002,7 +1329,7 @@ export declare interface Stroke {
     cmpd?: string;
 }
 
-declare interface TableCell {
+export declare interface TableCell {
     textBody: TextBody | null;
     fill: Fill | null;
     /** Default run text colour inherited from the table style (`<a:tcTxStyle>`); hex, no `#`. */
@@ -1025,7 +1352,7 @@ declare interface TableCell {
     vMerge: boolean;
 }
 
-declare interface TableElement {
+export declare interface TableElement {
     type: 'table';
     x: number;
     y: number;
@@ -1038,13 +1365,13 @@ declare interface TableElement {
     rtl?: boolean;
 }
 
-declare interface TableRow {
+export declare interface TableRow {
     /** Row height in EMU */
     height: number;
     cells: TableCell[];
 }
 
-declare interface TabStop {
+export declare interface TabStop {
     /** Position in EMU from the left edge of the text area (after lIns) */
     pos: number;
     /** Alignment: "l" | "r" | "ctr" | "dec" */
@@ -1115,7 +1442,7 @@ declare interface TextOutline {
 }
 
 /** Absolute text-frame rectangle in EMU (from SmartArt `<dsp:txXfrm>`). */
-declare interface TextRect {
+export declare interface TextRect {
     x: number;
     y: number;
     width: number;