html-native-pptx 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+import { Browser } from 'puppeteer';
+
+/**
+ * Intermediate Representation (IR) AST for html-native-pptx.
+ * Decouples the DOM crawler (Harvester) from the PresentationML generator (Compiler).
+ */
+declare const UNITS: {
+    readonly DPI: 96;
+    readonly PT_PER_INCH: 72;
+    readonly EMU_PER_INCH: 914400;
+    readonly SLIDE_16_9_WIDTH_INCHES: 13.333333;
+    readonly SLIDE_16_9_HEIGHT_INCHES: 7.5;
+    readonly SLIDE_16_9_WIDTH_EMU: 12192000;
+    readonly SLIDE_16_9_HEIGHT_EMU: 6858000;
+    readonly SLIDE_4_3_WIDTH_INCHES: 10;
+    readonly SLIDE_4_3_HEIGHT_INCHES: 7.5;
+    readonly SLIDE_4_3_WIDTH_EMU: 9144000;
+    readonly SLIDE_4_3_HEIGHT_EMU: 6858000;
+};
+type ElementType = 'container' | 'text' | 'image' | 'table';
+type TextAlign = 'left' | 'center' | 'right' | 'justify';
+/**
+ * Normalized bounding box in Inches.
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Visual styling for rectangular containers and shapes.
+ */
+interface ShapeStyle {
+    fillColor?: string;
+    fillOpacity?: number;
+    borderColor?: string;
+    borderWidth?: number;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    radius?: number;
+    shadow?: {
+        color: string;
+        blur: number;
+        offsetX: number;
+        offsetY: number;
+        opacity?: number;
+    };
+}
+/**
+ * Individual formatted text run inside a paragraph (maps to OpenXML <a:r>).
+ */
+interface TextRun {
+    content: string;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+/**
+ * Paragraph containing one or more formatted text runs (maps to OpenXML <a:p>).
+ */
+interface ParagraphIR {
+    align?: TextAlign;
+    lineHeight?: number;
+    spaceBefore?: number;
+    spaceAfter?: number;
+    runs: TextRun[];
+}
+/**
+ * Flat text style convenience interface (for simple, single-style text elements).
+ */
+interface TextStyle {
+    fontFamily: string;
+    fontSize: number;
+    color: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    align?: TextAlign;
+}
+/**
+ * Primary Abstract Syntax Tree (AST) node.
+ */
+interface IRNode {
+    id?: string | number;
+    name?: string;
+    type: ElementType;
+    box: BoundingBox;
+    zIndex?: number;
+    shapeStyle?: ShapeStyle;
+    content?: string;
+    textStyle?: TextStyle;
+    paragraphs?: ParagraphIR[];
+    children?: IRNode[];
+}
+/**
+ * Embedded font IR representing a portable font stream for OpenXML (.fntdata).
+ */
+interface EmbeddedFontIR {
+    typeface: string;
+    fntData: Buffer;
+}
+/**
+ * Complete Intermediate Representation for a single slide.
+ */
+interface SlideIR {
+    width: number;
+    height: number;
+    backgroundColor?: string;
+    elements: IRNode[];
+    fonts?: EmbeddedFontIR[];
+}
+/**
+ * Multi-slide presentation IR container with global presentation metadata.
+ */
+interface PresentationIR {
+    slides: SlideIR[];
+    fonts?: EmbeddedFontIR[];
+}
+
+type SlideAspect = '16:9' | '4:3';
+interface ViewportOptions {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+interface EmbeddedFontOption {
+    /**
+     * Font family / typeface name (e.g. "Telkomsel Batik Sans").
+     */
+    typeface: string;
+    /**
+     * Source font file path (.ttf, .otf, .eot, .fntdata), HTTP(S) URL, data URI, or raw Buffer.
+     */
+    src: string | Buffer;
+}
+interface ConvertOptions {
+    /**
+     * Presentation aspect ratio. Defaults to '16:9'.
+     */
+    aspect?: SlideAspect;
+    /**
+     * Browser viewport dimensions for headless layout resolution.
+     * Defaults to 1920x1080 for 16:9, or 1024x768 for 4:3.
+     */
+    viewport?: ViewportOptions;
+    /**
+     * CSS selector for the root container element to capture as slide.
+     * Defaults to 'body'.
+     */
+    selector?: string;
+    /**
+     * Optional CSS selector to detect and extract multi-slide presentations.
+     * e.g., '.slide' or 'section.slide'. If matching elements are found,
+     * every slide will be extracted into a separate slide in the presentation.
+     */
+    slideSelector?: string;
+    /**
+     * Timeout in milliseconds for rendering/waiting.
+     * Defaults to 30000ms (30s).
+     */
+    timeout?: number;
+    /**
+     * Wait until specific condition before harvesting DOM.
+     * 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
+     */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    /**
+     * Optional pre-existing Puppeteer browser instance.
+     * If supplied, html-native-pptx will reuse it rather than launching a new Chromium process.
+     */
+    browser?: Browser;
+    /**
+     * Optional WebSocket endpoint to connect to a remote Chromium (e.g. Browserless.io).
+     */
+    browserWSEndpoint?: string;
+    /**
+     * Optional list of custom fonts to embed into the PowerPoint presentation.
+     */
+    fonts?: EmbeddedFontOption[];
+    /**
+     * Whether to automatically detect @font-face rules in HTML/CSS and embed them.
+     * Defaults to true.
+     */
+    autoEmbedFonts?: boolean;
+    /**
+     * Base directory path used to resolve relative font paths and asset URLs.
+     * Defaults to process.cwd().
+     */
+    basePath?: string;
+}
+
+/**
+ * Convert pixels to inches given a DPI and optional coordinate scale factor.
+ */
+declare function pxToInches(px: number, dpi?: number, scale?: number): number;
+/**
+ * Convert inches to English Metric Units (EMU).
+ * 1 inch = 914,400 EMU.
+ */
+declare function inchesToEmu(inches: number): number;
+/**
+ * Direct conversion from pixels to EMU.
+ */
+declare function pxToEmu(px: number, dpi?: number, scale?: number): number;
+/**
+ * Convert pixel font size to points (pt).
+ * 1 inch = 72 pt = 96 px -> 1 px = 0.75 pt.
+ */
+declare function pxToPt(px: number, dpi?: number): number;
+/**
+ * Convert points to hundredths of a point (used by OpenXML sz attribute).
+ * e.g., 16pt -> 1600.
+ */
+declare function ptToHundredthPt(pt: number): number;
+/**
+ * Convert CSS border-radius (in pixels) to OpenXML rounded rectangle adjustment guide value (0 - 50000).
+ * In OpenXML, an adj value of 50000 represents a radius equal to half the shortest dimension.
+ */
+declare function borderRadiusToGuide(radiusPx: number, widthPx: number, heightPx: number): number;
+
+interface ColorResult {
+    hex: string;
+    opacity?: number;
+}
+/**
+ * Normalizes any CSS color string (rgb, rgba, hex, named) into a 6-character uppercase hex string.
+ * Returns undefined if transparent or invalid.
+ */
+declare function normalizeHexColor(cssColor?: string): ColorResult | undefined;
+/**
+ * Normalizes CSS font-weight into a boolean representing bold.
+ */
+declare function normalizeFontWeight(fontWeight?: string | number): boolean;
+/**
+ * Normalizes CSS font-style into a boolean representing italic.
+ */
+declare function normalizeFontStyle(fontStyle?: string): boolean;
+/**
+ * Normalizes CSS font-family string by extracting the primary font family without quotes.
+ */
+declare function normalizeFontFamily(fontFamily?: string): string;
+/**
+ * Normalizes CSS text-align to IR TextAlign.
+ */
+declare function normalizeTextAlign(textAlign?: string): TextAlign;
+/**
+ * Normalizes CSS border-style to supported IR border types.
+ */
+declare function normalizeBorderStyle(borderStyle?: string): 'solid' | 'dashed' | 'dotted';
+
+/**
+ * Normalizes a typeface name by stripping quotes and taking the primary family.
+ */
+declare function cleanTypeface(name: string): string;
+/**
+ * Checks if a buffer contains Microsoft Embedded OpenType (EOT) binary data.
+ */
+declare function isEotBuffer(buf: Buffer): boolean;
+/**
+ * Converts TrueType (TTF) or OpenType (OTF) font buffer into Microsoft EOT format.
+ */
+declare function convertTtfToEot(buf: Buffer): Buffer;
+/**
+ * Loads font data from a buffer, data URI, web URL, or local file path.
+ */
+declare function loadFontBuffer(src: string | Buffer, basePath?: string): Promise<Buffer | null>;
+/**
+ * Extracts @font-face rules from raw HTML string or CSS text.
+ */
+declare function extractFontFacesFromHtml(html: string): Array<{
+    typeface: string;
+    src: string;
+}>;
+/**
+ * Resolves, deduplicates, and converts font options and discovered @font-face rules into EmbeddedFontIR items.
+ */
+declare function resolveAndEmbedFonts(options: {
+    html?: string;
+    userFonts?: EmbeddedFontOption[];
+    autoEmbedFonts?: boolean;
+    basePath?: string;
+    discoveredFonts?: Array<{
+        typeface: string;
+        src: string;
+    }>;
+}): Promise<EmbeddedFontIR[]>;
+
+declare function harvestHtmlToIR(htmlOrUrl: string, options?: ConvertOptions): Promise<SlideIR | SlideIR[]>;
+
+interface HarvestOptions {
+    selector?: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    aspect?: '16:9' | '4:3';
+}
+/**
+ * In-browser evaluation function to harvest DOM tree and compile it to SlideIR.
+ * Designed to execute inside Puppeteer's page.evaluate().
+ */
+declare function extractDomToSlideIR(options: HarvestOptions): SlideIR;
+
+interface CompileOptions {
+    fonts?: EmbeddedFontIR[];
+}
+/**
+ * Compiles a single SlideIR, an array of SlideIRs, or a PresentationIR into a valid PowerPoint (.pptx) file Buffer using OpenXML and JSZip.
+ */
+declare function compileSlideToPptx(slideOrSlidesOrPres: SlideIR | SlideIR[] | PresentationIR, options?: CompileOptions): Promise<Buffer>;
+
+/**
+ * Compiles a container IRNode into OpenXML <p:sp> element.
+ */
+declare function compileContainerShape(node: IRNode, id: number): string;
+
+/**
+ * Compiles a text IRNode into an OpenXML <p:sp> textbox element with zero internal margins.
+ */
+declare function compileTextShape(node: IRNode, id: number): string;
+
+/**
+ * Main conversion API: Converts an HTML string or URL into a native, editable PowerPoint (.pptx) buffer.
+ *
+ * @param html - Raw HTML string or valid http(s) URL.
+ * @param options - Configuration options for viewport, aspect ratio, or browser instance.
+ * @returns Promise resolving to a Node.js Buffer representing the .pptx file.
+ */
+declare function convertHtmlToPptx(html: string, options?: ConvertOptions): Promise<Buffer>;
+/**
+ * Helper to construct a blank SlideIR with standard 16:9 or 4:3 dimensions.
+ */
+declare function createSlideIR(aspect?: '16:9' | '4:3'): SlideIR;
+
+export { type BoundingBox, type ColorResult, type ConvertOptions, type ElementType, type EmbeddedFontIR, type EmbeddedFontOption, type IRNode, type ParagraphIR, type PresentationIR, type ShapeStyle, type SlideAspect, type SlideIR, type TextAlign, type TextRun, type TextStyle, UNITS, type ViewportOptions, borderRadiusToGuide, cleanTypeface, compileContainerShape, compileSlideToPptx, compileTextShape, convertHtmlToPptx, convertTtfToEot, createSlideIR, extractDomToSlideIR, extractFontFacesFromHtml, harvestHtmlToIR, inchesToEmu, isEotBuffer, loadFontBuffer, normalizeBorderStyle, normalizeFontFamily, normalizeFontStyle, normalizeFontWeight, normalizeHexColor, normalizeTextAlign, ptToHundredthPt, pxToEmu, pxToInches, pxToPt, resolveAndEmbedFonts };