@silurus/ooxml 0.1.0

package/dist/types/pptx.d.ts

@@ -0,0 +1,450 @@
+declare interface ArrowEnd {
+    /** OOXML type: "none" | "triangle" | "stealth" | "diamond" | "oval" | "arrow" */
+    type: string;
+    /** Width multiplier: "sm" | "med" | "lg" */
+    w: string;
+    /** Length multiplier: "sm" | "med" | "lg" */
+    len: string;
+}
+
+declare type Bullet = {
+    type: 'none';
+} | {
+    type: 'inherit';
+} | {
+    type: 'char';
+    char: string;
+    color: string | null;
+    sizePct: number | null;
+    fontFamily: string | null;
+} | {
+    type: 'autoNum';
+    numType: string;
+    startAt: number | null;
+};
+
+/**
+ * PPTX chart element. The Rust parser emits ChartModel fields flat at the
+ * top level, alongside the element position (x/y/width/height in EMU).
+ * Pass this straight to `renderChart` from `@silurus/ooxml-core`.
+ */
+declare interface ChartElement {
+    type: 'chart';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    chartType: string;
+    title: string | null;
+    categories: string[];
+    series: ChartSeries[];
+    valMax: number | null;
+    valMin: number | null;
+    subtotalIndices: number[];
+    showDataLabels: boolean;
+    catAxisHidden: boolean;
+    valAxisHidden: boolean;
+    plotAreaBg: string | null;
+}
+
+declare interface ChartSeries {
+    name: string;
+    /** Hex without '#'. null = fall back to palette. */
+    color: string | null;
+    /** Numeric values; null = missing data point. */
+    values: (number | null)[];
+    /**
+     * Per-data-point colors (pie / doughnut). Hex without '#'. null inside the
+     * array = use palette for that slice. Omit entirely for non-pie series.
+     */
+    dataPointColors?: (string | null)[] | null;
+    /**
+     * Mixed chart: per-series chart type override. Currently only "line" (XLSX)
+     * is honoured; other values are treated as the chart's primary type.
+     */
+    seriesType?: string | null;
+    /**
+     * Scatter-only X values (as strings). When null the series uses
+     * `ChartModel.categories` as X.
+     */
+    categories?: string[] | null;
+}
+
+export declare type Fill = SolidFill | NoFill | GradientFill;
+
+declare interface GradientFill {
+    fillType: 'gradient';
+    stops: GradientStop[];
+    /** degrees: 0 = left→right, 90 = top→bottom */
+    angle: number;
+    /** 'linear' | 'radial' */
+    gradType: string;
+}
+
+declare interface GradientStop {
+    position: number;
+    color: string;
+}
+
+export declare interface LineBreak {
+    type: 'break';
+}
+
+export declare interface NoFill {
+    fillType: 'none';
+}
+
+export declare interface Paragraph {
+    /** Alignment: "l" | "ctr" | "r" | "just" */
+    alignment: string;
+    /** Left margin in EMU */
+    marL: number;
+    /** Right margin in EMU */
+    marR: number;
+    /** First-line indent in EMU (negative = hanging indent) */
+    indent: number;
+    spaceBefore: number | null;
+    spaceAfter: number | null;
+    spaceLine: SpaceLine | null;
+    /** List nesting level (0–8) */
+    lvl: number;
+    bullet: Bullet;
+    defFontSize: number | null;
+    defColor: string | null;
+    defBold: boolean | null;
+    defItalic: boolean | null;
+    defFontFamily: string | null;
+    /** Tab stops from pPr > tabLst */
+    tabStops: TabStop[];
+    runs: TextRun[];
+}
+
+declare type PathCmd = {
+    cmd: 'moveTo';
+    x: number;
+    y: number;
+} | {
+    cmd: 'lineTo';
+    x: number;
+    y: number;
+} | {
+    cmd: 'cubicBezTo';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    cmd: 'arcTo';
+    wr: number;
+    hr: number;
+    stAng: number;
+    swAng: number;
+} | {
+    cmd: 'close';
+};
+
+export declare interface PictureElement {
+    type: 'picture';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    flipH: boolean;
+    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;
+    /**
+     * ECMA-376 a:srcRect — source image crop as fractions (0..1) of the source
+     * width/height. Omitted when the image is not cropped.
+     */
+    srcRect?: {
+        l?: number;
+        t?: number;
+        r?: number;
+        b?: number;
+    };
+}
+
+/**
+ * Headless PPTX rendering engine.
+ *
+ * Parses `.pptx` archives in a background worker (WASM) but renders slides
+ * synchronously on the main thread, so the canvas shares the document's
+ * `FontFaceSet` — avoiding subtle wrap differences between system fallback
+ * fonts and theme-declared webfonts (e.g. Nunito Sans).
+ *
+ * Construct via the static `load` factory. A single instance can drive any
+ * number of canvases (scroll view, thumbnail grid, master-detail, etc.).
+ *
+ * @example
+ * const pres = await PptxPresentation.load(buffer);
+ * await pres.renderSlide(canvas, 0, { width: 960 });
+ */
+export declare class PptxPresentation {
+    private readonly _worker;
+    private _presentation;
+    private _pendingParseCallbacks;
+    private _nextId;
+    private _workerReady;
+    private _workerReadyCallbacks;
+    private constructor();
+    /** Parse a PPTX from URL or ArrayBuffer. */
+    static load(source: string | ArrayBuffer): Promise<PptxPresentation>;
+    private _waitForWorker;
+    private _parse;
+    /** Total number of slides in the loaded presentation. */
+    get slideCount(): number;
+    /** Slide width in EMU. */
+    get slideWidth(): number;
+    /** Slide height in EMU. */
+    get slideHeight(): number;
+    /** Render a slide onto the given canvas. */
+    renderSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
+    /** Terminate the worker and release all resources. */
+    destroy(): void;
+}
+
+/**
+ * Opinionated single-canvas PPTX viewer.
+ *
+ * Creates a <canvas> element, appends it to the provided container, and manages
+ * slide navigation.
+ *
+ * For custom layouts (multi-canvas, thumbnails, scroll view) use PptxPresentation directly.
+ */
+export declare class PptxViewer {
+    private readonly canvas;
+    private engine;
+    private readonly opts;
+    private currentSlide;
+    constructor(container: HTMLElement, opts?: PptxViewerOptions);
+    /** Load a PPTX from URL or ArrayBuffer and render the first slide. */
+    load(source: string | ArrayBuffer): Promise<void>;
+    /** Navigate to a specific slide (0-indexed). */
+    goToSlide(index: number): Promise<void>;
+    nextSlide(): Promise<void>;
+    prevSlide(): Promise<void>;
+    get slideIndex(): number;
+    get slideCount(): number;
+    /** The underlying <canvas> element. */
+    get canvasElement(): HTMLCanvasElement;
+    private renderCurrentSlide;
+    /** Clean up the viewer and terminate the background worker. */
+    destroy(): void;
+}
+
+export declare interface PptxViewerOptions extends RenderOptions {
+    /** Called when a slide finishes rendering */
+    onSlideChange?: (index: number, total: number) => void;
+    /** Called on parse or render errors */
+    onError?: (err: Error) => void;
+}
+
+export declare interface Presentation {
+    slideWidth: number;
+    slideHeight: number;
+    slides: Slide[];
+    /** Theme dk1 color (e.g. "383838"). Used as fallback text color when no explicit color is set. */
+    defaultTextColor: string | null;
+    /** Theme major (heading) font family name (e.g. "Aptos Display", "Nunito Sans"). Null if not set. */
+    majorFont: string | null;
+    /** Theme minor (body) font family name (e.g. "Aptos", "Nunito Sans"). Null if not set. */
+    minorFont: string | null;
+}
+
+export declare interface RenderOptions {
+    width?: number;
+    defaultTextColor?: string | null;
+    dpr?: number;
+    majorFont?: string | null;
+    minorFont?: string | null;
+}
+
+/**
+ * Render a single slide onto a <canvas> element.
+ * Returns the canvas for convenience.
+ */
+export declare function renderSlide(canvas: HTMLCanvasElement | OffscreenCanvas, slide: Slide, slideWidth: number, slideHeight: number, opts?: RenderOptions): Promise<HTMLCanvasElement | OffscreenCanvas>;
+
+/** Options for rendering a single slide onto a canvas. */
+export declare interface RenderSlideOptions {
+    /** Display width in CSS pixels. Defaults to canvas.offsetWidth or 960. */
+    width?: number;
+    /** Device pixel ratio. Defaults to window.devicePixelRatio or 1. */
+    dpr?: number;
+}
+
+declare interface Shadow {
+    color: string;
+    alpha: number;
+    blur: number;
+    dist: number;
+    /** degrees clockwise from East */
+    dir: number;
+}
+
+export declare interface ShapeElement {
+    type: 'shape';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Rotation in degrees, clockwise */
+    rotation: number;
+    /** Horizontal mirror (a:xfrm flipH) */
+    flipH: boolean;
+    /** Vertical mirror (a:xfrm flipV) */
+    flipV: boolean;
+    /** OOXML preset name or "custGeom" when custom paths are used */
+    geometry: string;
+    fill: Fill | null;
+    stroke: Stroke | null;
+    textBody: TextBody | null;
+    /** Default text color from p:style > fontRef (hex). Used when run/para has no explicit color. */
+    defaultTextColor: string | null;
+    /** Custom geometry sub-paths (set only when geometry === "custGeom").
+     *  Outer array: one entry per <a:path>; inner: path commands with coords in [0,1]. */
+    custGeom: PathCmd[][] | null;
+    /** First adjustment value from prstGeom avLst (e.g. trapezoid inset). Range 0–100000. */
+    adj: number | null;
+    /** Second adjustment value from prstGeom avLst (e.g. arrow head width). Range 0–100000. */
+    adj2: number | null;
+    /** Third adjustment value from prstGeom avLst (e.g. callout tip x). Range 0–100000. */
+    adj3: number | null;
+    /** Fourth adjustment value from prstGeom avLst (e.g. callout tip y). Range 0–100000. */
+    adj4: number | null;
+    /** Drop shadow from effectLst > outerShdw (null if not present). */
+    shadow: Shadow | null;
+}
+
+export declare interface Slide {
+    index: number;
+    /** 1-based slide number (index + 1); used to render slidenum fields */
+    slideNumber: number;
+    background: Fill | null;
+    elements: SlideElement[];
+}
+
+export declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement;
+
+export declare interface SolidFill {
+    fillType: 'solid';
+    color: string;
+}
+
+declare type SpaceLine = {
+    type: 'pct';
+    val: number;
+} | {
+    type: 'pts';
+    val: number;
+};
+
+export declare interface Stroke {
+    color: string;
+    /** Width in EMU */
+    width: number;
+    /** OOXML prstDash value: "dash", "dot", "dashDot", "lgDash", "lgDashDot", etc. */
+    dashStyle?: string;
+    /** Arrow head at the start of the line */
+    headEnd?: ArrowEnd;
+    /** Arrow head at the end of the line */
+    tailEnd?: ArrowEnd;
+}
+
+declare interface TableCell {
+    textBody: TextBody | null;
+    fill: Fill | null;
+    borderL: Stroke | null;
+    borderR: Stroke | null;
+    borderT: Stroke | null;
+    borderB: Stroke | null;
+    /** Diagonal from top-left to bottom-right */
+    diagonalTL?: Stroke | null;
+    /** Diagonal from top-right to bottom-left */
+    diagonalTR?: Stroke | null;
+    /** Column span */
+    gridSpan: number;
+    /** Row span */
+    rowSpan: number;
+    /** Horizontal merge continuation */
+    hMerge: boolean;
+    /** Vertical merge continuation */
+    vMerge: boolean;
+}
+
+declare interface TableElement {
+    type: 'table';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Column widths in EMU */
+    cols: number[];
+    rows: TableRow[];
+}
+
+declare interface TableRow {
+    /** Row height in EMU */
+    height: number;
+    cells: TableCell[];
+}
+
+declare interface TabStop {
+    /** Position in EMU from the left edge of the text area (after lIns) */
+    pos: number;
+    /** Alignment: "l" | "r" | "ctr" | "dec" */
+    algn: string;
+}
+
+export declare interface TextBody {
+    /** Vertical anchor: "t" | "ctr" | "b" */
+    verticalAnchor: string;
+    paragraphs: Paragraph[];
+    /** Default pt size from lstStyle (overrides renderer default when present) */
+    defaultFontSize: number | null;
+    /** Inherited bold from layout/master defRPr (null = not set, use false as final default) */
+    defaultBold: boolean | null;
+    /** Inherited italic from layout/master defRPr (null = not set, use false as final default) */
+    defaultItalic: boolean | null;
+    /** Text insets in EMU (defaults: lIns=rIns=91440, tIns=bIns=45720) */
+    lIns: number;
+    rIns: number;
+    tIns: number;
+    bIns: number;
+    /** "square" = wrap, "none" = no wrap */
+    wrap: string;
+    /** Text direction: "horz" | "vert" | "vert270" | "eaVert" etc. */
+    vert: string;
+    /** Auto-fit: "sp" = shape grows to fit text, "norm" = font shrinks, "none" = no fit */
+    autoFit: string;
+}
+
+export declare type TextRun = TextRunData | LineBreak;
+
+export declare interface TextRunData {
+    type: 'text';
+    text: string;
+    /** null = not set, inherit from paragraph/body defaults */
+    bold: boolean | null;
+    /** null = not set, inherit from paragraph/body defaults */
+    italic: boolean | null;
+    underline: boolean;
+    /** true when rPr strike = "sngStrike" or "dblStrike" */
+    strikethrough: boolean;
+    /** Font size in points */
+    fontSize: number | null;
+    color: string | null;
+    fontFamily: string | null;
+    /** Baseline shift in thousandths of a point. Positive = superscript, negative = subscript. */
+    baseline?: number;
+    /** Set for OOXML field runs (e.g. "slidenum"). When set, renderer replaces text with field value. */
+    fieldType?: string;
+}
+
+export { }