@silurus/ooxml 0.2.0 → 0.4.0

package/dist/types/index.d.ts

@@ -7,6 +7,31 @@ declare interface ArrowEnd {
     len: string;
 }
 
+/**
+ * Observe an element's size and invoke a render callback, coalescing bursts to
+ * one call per animation frame and serializing overlapping async renders.
+ *
+ * Framework-agnostic: call from any mount/setup hook and invoke the returned
+ * disposer in the corresponding teardown hook.
+ *
+ * @example
+ * const detach = autoResize(
+ *   (width) => pres.renderSlide(canvas, 0, { width }),
+ *   canvas,
+ * );
+ * // later
+ * detach();
+ */
+declare function autoResize(render: (width: number, height: number) => void | Promise<void>, element: Element, opts?: AutoResizeOptions): () => void;
+
+declare interface AutoResizeOptions {
+    /**
+     * Skip rendering while `document.hidden` is true and fire once with the latest
+     * observed size when the tab becomes visible again. Default: true.
+     */
+    pauseWhenHidden?: boolean;
+}
+
 declare type BodyElement = {
     type: 'paragraph';
 } & DocParagraph | {
@@ -218,6 +243,24 @@ declare interface ChartElement {
     catAxisHidden: boolean;
     valAxisHidden: boolean;
     plotAreaBg: string | null;
+    /** Outer chartSpace background (hex without '#'). null when noFill/absent. */
+    chartBg: string | null;
+    /** True when <c:legend> is declared; false suppresses the legend entirely. */
+    showLegend: boolean;
+    /** catAx crossBetween: "between" (default, 0.5-step padding) or "midCat". */
+    catAxisCrossBetween: 'between' | 'midCat' | string;
+    /** `<c:valAx><c:majorTickMark>`. "cross" (default) | "out" | "in" | "none". */
+    valAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:catAx><c:majorTickMark>`. */
+    catAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** Title font size in OOXML hundredths of a point (1600 = 16pt). null = default. */
+    titleFontSizeHpt: number | null;
+    /** `<c:catAx><c:txPr>` font size (hpt). null = proportional default. */
+    catAxisFontSizeHpt: number | null;
+    /** `<c:valAx><c:txPr>` font size (hpt). null = proportional default. */
+    valAxisFontSizeHpt: number | null;
+    /** `<c:dLbls><c:txPr>` font size (hpt) for data-point value labels. */
+    dataLabelFontSizeHpt: number | null;
 }
 
 declare interface ChartSeries {
@@ -249,7 +292,12 @@ declare interface ConditionalFormat {
 }
 
 declare interface DocParagraph {
-    alignment: 'left' | 'center' | 'right' | 'justify';
+    /**
+     * ECMA-376 §17.18.44 ST_Jc. Renderer honors left, start, center, right, end,
+     * both, distribute. Other values (kashida variants, numTab, thaiDistribute)
+     * are treated as start-aligned.
+     */
+    alignment: 'left' | 'start' | 'center' | 'right' | 'end' | 'justify' | 'both' | 'distribute' | string;
     indentLeft: number;
     indentRight: number;
     indentFirst: number;
@@ -265,6 +313,12 @@ declare interface DocParagraph {
     pageBreakBefore?: boolean;
     /** Suppress spacing between adjacent same-style paragraphs (w:contextualSpacing) */
     contextualSpacing?: boolean;
+    /** Keep paragraph on same page as the next paragraph (w:keepNext) */
+    keepNext?: boolean;
+    /** Keep all lines of this paragraph on the same page (w:keepLines) */
+    keepLines?: boolean;
+    /** Widow/orphan control (w:widowControl). ECMA-376 default is true. */
+    widowControl?: boolean;
     /** Paragraph borders (w:pBdr) */
     borders?: ParagraphBorders | null;
     /** Style ID of the applied paragraph style */
@@ -282,7 +336,9 @@ declare type DocRun = {
     breakType: 'line' | 'page' | 'column';
 } | {
     type: 'field';
-} & FieldRun;
+} & FieldRun | {
+    type: 'shape';
+} & ShapeRun;
 
 declare interface DocTable {
     colWidths: number[];
@@ -321,6 +377,8 @@ export declare namespace docx {
     export {
         DocxDocument,
         DocxViewer,
+        autoResize,
+        AutoResizeOptions,
         Document_2 as Document,
         SectionProps,
         DocParagraph,
@@ -422,6 +480,13 @@ declare interface GradientStop {
     color: string;
 }
 
+declare interface GradientStop_2 {
+    /** 0.0–1.0 */
+    position: number;
+    /** hex 6-char */
+    color: string;
+}
+
 declare interface HeaderFooter {
     body: BodyElement[];
 }
@@ -522,6 +587,24 @@ declare interface LoadOptions {
     useGoogleFonts?: boolean;
 }
 
+declare interface MediaElement {
+    type: 'media';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** "audio" or "video" */
+    mediaKind: 'audio' | 'video';
+    /** Poster image zip path (e.g. "ppt/media/image2.png"). Empty when no poster. */
+    posterPath: string;
+    /** Poster image MIME type (empty when no poster). */
+    posterMimeType: string;
+    /** Path inside the pptx zip (e.g. "ppt/media/media2.mp4"). Used by getMedia. */
+    mediaPath: string;
+    /** MIME type of the underlying media (e.g. "audio/mpeg", "video/mp4"). */
+    mimeType: string;
+}
+
 declare interface MergeCell {
     top: number;
     left: number;
@@ -621,6 +704,32 @@ declare type PathCmd = {
     cmd: 'close';
 };
 
+declare type PathCmd_2 = {
+    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';
+};
+
 declare interface PictureElement {
     type: 'picture';
     x: number;
@@ -644,6 +753,8 @@ declare interface PictureElement {
         r?: number;
         b?: number;
     };
+    /** a:blip > a:alphaModFix@amt as 0..1. Undefined = fully opaque. */
+    alpha?: number;
 }
 
 export declare namespace pptx {
@@ -655,6 +766,8 @@ export declare namespace pptx {
         RenderSlideOptions,
         renderSlide,
         RenderOptions,
+        autoResize,
+        AutoResizeOptions,
         Presentation,
         Slide,
         SlideElement,
@@ -691,6 +804,8 @@ declare class PptxPresentation {
     private readonly _worker;
     private _presentation;
     private _pendingParseCallbacks;
+    private _pendingMediaCallbacks;
+    private _mediaCache;
     private _nextId;
     private _workerReady;
     private _workerReadyCallbacks;
@@ -707,6 +822,19 @@ declare class PptxPresentation {
     get slideHeight(): number;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
+    /**
+     * Extract raw media bytes for a zip path referenced by {@link MediaElement}.
+     * Results are cached by path for the lifetime of this instance.
+     */
+    getMedia(mediaPath: string): Promise<Blob>;
+    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.
+     */
+    presentSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<PresentationHandle>;
     /** Terminate the worker and release all resources. */
     destroy(): void;
 }
@@ -764,12 +892,31 @@ declare interface Presentation {
     minorFont: string | null;
 }
 
+declare interface PresentationHandle {
+    play(mediaPath?: string): void;
+    pause(mediaPath?: string): void;
+    dispose(): void;
+}
+
 declare interface RenderOptions {
     width?: number;
     defaultTextColor?: string | null;
     dpr?: number;
     majorFont?: string | null;
     minorFont?: string | null;
+    /**
+     * Lazily resolve an archive-internal asset (by zip path) to a Blob. The
+     * renderer uses this to fetch posters and other large embedded assets on
+     * demand, keeping the parse output free of inlined base64.
+     */
+    fetchMedia?: (path: string) => Promise<Blob>;
+    /**
+     * When true, renderMedia draws only the poster frame — play/pause badges
+     * and progress bars are left to the caller. Set by the pptx presentSlide
+     * API so its interactive handle can own all control chrome without
+     * the static renderer drawing a duplicate play badge.
+     */
+    skipMediaControls?: boolean;
 }
 
 declare interface RenderPageOptions {
@@ -791,6 +938,12 @@ declare interface RenderSlideOptions {
     width?: number;
     /** Device pixel ratio. Defaults to window.devicePixelRatio or 1. */
     dpr?: number;
+    /**
+     * Skip drawing the play badge overlay on media elements. Used internally by
+     * {@link PptxPresentation.presentSlide} so its interactive handle can draw
+     * its own play/pause chrome without duplication.
+     */
+    skipMediaControls?: boolean;
 }
 
 declare interface RenderViewportOptions {
@@ -886,6 +1039,38 @@ declare interface ShapeElement {
     shadow: Shadow | null;
 }
 
+declare type ShapeFill = {
+    fillType: 'solid';
+    color: string;
+} | {
+    fillType: 'gradient';
+    stops: GradientStop_2[];
+    angle: number;
+    gradType: string;
+};
+
+declare interface ShapeRun {
+    widthPt: number;
+    heightPt: number;
+    /** X offset in pt */
+    anchorXPt: number;
+    /** Y offset in pt */
+    anchorYPt: number;
+    anchorXFromMargin: boolean;
+    anchorYFromPara: boolean;
+    /** Draw behind text when true (wp:anchor behindDoc="1"). */
+    behindDoc?: boolean;
+    /** Document-order index within a group; lower values render first. */
+    zOrder: number;
+    /** Normalized [0,1] custom-geometry sub-paths */
+    subpaths: PathCmd_2[][];
+    fill: ShapeFill | null;
+    stroke: string | null;
+    strokeWidth?: number;
+    rotation?: number;
+    wrapMode?: string | null;
+}
+
 declare interface SharedString {
     text: string;
     runs?: Run[];
@@ -905,7 +1090,7 @@ declare interface Slide {
     elements: SlideElement[];
 }
 
-declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement;
+declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
 
 declare interface SolidFill {
     fillType: 'solid';
@@ -1106,6 +1291,8 @@ export declare namespace xlsx {
         XlsxWorkbook,
         XlsxViewer,
         XlsxViewerOptions,
+        autoResize,
+        AutoResizeOptions,
         Workbook,
         SheetMeta,
         Worksheet,

package/dist/types/pptx.d.ts

@@ -7,6 +7,31 @@ declare interface ArrowEnd {
     len: string;
 }
 
+/**
+ * Observe an element's size and invoke a render callback, coalescing bursts to
+ * one call per animation frame and serializing overlapping async renders.
+ *
+ * Framework-agnostic: call from any mount/setup hook and invoke the returned
+ * disposer in the corresponding teardown hook.
+ *
+ * @example
+ * const detach = autoResize(
+ *   (width) => pres.renderSlide(canvas, 0, { width }),
+ *   canvas,
+ * );
+ * // later
+ * detach();
+ */
+export declare function autoResize(render: (width: number, height: number) => void | Promise<void>, element: Element, opts?: AutoResizeOptions): () => void;
+
+export declare interface AutoResizeOptions {
+    /**
+     * Skip rendering while `document.hidden` is true and fire once with the latest
+     * observed size when the tab becomes visible again. Default: true.
+     */
+    pauseWhenHidden?: boolean;
+}
+
 declare type Bullet = {
     type: 'none';
 } | {
@@ -45,6 +70,24 @@ declare interface ChartElement {
     catAxisHidden: boolean;
     valAxisHidden: boolean;
     plotAreaBg: string | null;
+    /** Outer chartSpace background (hex without '#'). null when noFill/absent. */
+    chartBg: string | null;
+    /** True when <c:legend> is declared; false suppresses the legend entirely. */
+    showLegend: boolean;
+    /** catAx crossBetween: "between" (default, 0.5-step padding) or "midCat". */
+    catAxisCrossBetween: 'between' | 'midCat' | string;
+    /** `<c:valAx><c:majorTickMark>`. "cross" (default) | "out" | "in" | "none". */
+    valAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** `<c:catAx><c:majorTickMark>`. */
+    catAxisMajorTickMark: 'cross' | 'out' | 'in' | 'none' | string;
+    /** Title font size in OOXML hundredths of a point (1600 = 16pt). null = default. */
+    titleFontSizeHpt: number | null;
+    /** `<c:catAx><c:txPr>` font size (hpt). null = proportional default. */
+    catAxisFontSizeHpt: number | null;
+    /** `<c:valAx><c:txPr>` font size (hpt). null = proportional default. */
+    valAxisFontSizeHpt: number | null;
+    /** `<c:dLbls><c:txPr>` font size (hpt) for data-point value labels. */
+    dataLabelFontSizeHpt: number | null;
 }
 
 declare interface ChartSeries {
@@ -104,6 +147,24 @@ export declare interface LoadOptions {
     useGoogleFonts?: boolean;
 }
 
+declare interface MediaElement {
+    type: 'media';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** "audio" or "video" */
+    mediaKind: 'audio' | 'video';
+    /** Poster image zip path (e.g. "ppt/media/image2.png"). Empty when no poster. */
+    posterPath: string;
+    /** Poster image MIME type (empty when no poster). */
+    posterMimeType: string;
+    /** Path inside the pptx zip (e.g. "ppt/media/media2.mp4"). Used by getMedia. */
+    mediaPath: string;
+    /** MIME type of the underlying media (e.g. "audio/mpeg", "video/mp4"). */
+    mimeType: string;
+}
+
 export declare interface NoFill {
     fillType: 'none';
 }
@@ -182,6 +243,8 @@ export declare interface PictureElement {
         r?: number;
         b?: number;
     };
+    /** a:blip > a:alphaModFix@amt as 0..1. Undefined = fully opaque. */
+    alpha?: number;
 }
 
 /**
@@ -203,6 +266,8 @@ export declare class PptxPresentation {
     private readonly _worker;
     private _presentation;
     private _pendingParseCallbacks;
+    private _pendingMediaCallbacks;
+    private _mediaCache;
     private _nextId;
     private _workerReady;
     private _workerReadyCallbacks;
@@ -219,6 +284,19 @@ export declare class PptxPresentation {
     get slideHeight(): number;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
+    /**
+     * Extract raw media bytes for a zip path referenced by {@link MediaElement}.
+     * Results are cached by path for the lifetime of this instance.
+     */
+    getMedia(mediaPath: string): Promise<Blob>;
+    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.
+     */
+    presentSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<PresentationHandle>;
     /** Terminate the worker and release all resources. */
     destroy(): void;
 }
@@ -276,12 +354,31 @@ export declare interface Presentation {
     minorFont: string | null;
 }
 
+declare interface PresentationHandle {
+    play(mediaPath?: string): void;
+    pause(mediaPath?: string): void;
+    dispose(): void;
+}
+
 export declare interface RenderOptions {
     width?: number;
     defaultTextColor?: string | null;
     dpr?: number;
     majorFont?: string | null;
     minorFont?: string | null;
+    /**
+     * Lazily resolve an archive-internal asset (by zip path) to a Blob. The
+     * renderer uses this to fetch posters and other large embedded assets on
+     * demand, keeping the parse output free of inlined base64.
+     */
+    fetchMedia?: (path: string) => Promise<Blob>;
+    /**
+     * When true, renderMedia draws only the poster frame — play/pause badges
+     * and progress bars are left to the caller. Set by the pptx presentSlide
+     * API so its interactive handle can own all control chrome without
+     * the static renderer drawing a duplicate play badge.
+     */
+    skipMediaControls?: boolean;
 }
 
 /**
@@ -296,6 +393,12 @@ export declare interface RenderSlideOptions {
     width?: number;
     /** Device pixel ratio. Defaults to window.devicePixelRatio or 1. */
     dpr?: number;
+    /**
+     * Skip drawing the play badge overlay on media elements. Used internally by
+     * {@link PptxPresentation.presentSlide} so its interactive handle can draw
+     * its own play/pause chrome without duplication.
+     */
+    skipMediaControls?: boolean;
 }
 
 declare interface Shadow {
@@ -349,7 +452,7 @@ export declare interface Slide {
     elements: SlideElement[];
 }
 
-export declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement;
+export declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
 
 export declare interface SolidFill {
     fillType: 'solid';

package/dist/types/xlsx.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Observe an element's size and invoke a render callback, coalescing bursts to
+ * one call per animation frame and serializing overlapping async renders.
+ *
+ * Framework-agnostic: call from any mount/setup hook and invoke the returned
+ * disposer in the corresponding teardown hook.
+ *
+ * @example
+ * const detach = autoResize(
+ *   (width) => pres.renderSlide(canvas, 0, { width }),
+ *   canvas,
+ * );
+ * // later
+ * detach();
+ */
+export declare function autoResize(render: (width: number, height: number) => void | Promise<void>, element: Element, opts?: AutoResizeOptions): () => void;
+
+export declare interface AutoResizeOptions {
+    /**
+     * Skip rendering while `document.hidden` is true and fire once with the latest
+     * observed size when the tab becomes visible again. Default: true.
+     */
+    pauseWhenHidden?: boolean;
+}
+
 export declare interface Border {
     left: BorderEdge | null;
     right: BorderEdge | null;