@mkabatek/pptx-viewer 1.5.3 → 1.5.5

package/node_modules/pptx-viewer-core/dist/SvgExporter-BtZczTlB.d.ts

@@ -1,557 +0,0 @@
-import { m as PptxData, P as PptxElement, N as TextSegment, l as PptxSlide } from './presentation-nZxgWvXq.js';
-
-/**
- * Platform adapter for file system operations.
- *
- * Consumers must provide an implementation of this interface
- * when using the converter with file output (writing markdown
- * and extracting media to disk).
- *
- * For in-memory-only conversion (just getting the markdown string),
- * no adapter is required.
- */
-interface FileSystemAdapter {
-    /**
-     * Writes a UTF-8 text file at the given path, creating or overwriting as needed.
-     * @param path - Absolute or relative path for the output file.
-     * @param content - Text content to write.
-     */
-    writeFile(path: string, content: string): Promise<void>;
-    /**
-     * Writes a binary file (e.g. an extracted image) at the given path.
-     * @param path - Absolute or relative path for the output file.
-     * @param data - Raw binary content as a typed array.
-     */
-    writeBinaryFile(path: string, data: Uint8Array): Promise<void>;
-    /**
-     * Creates a directory (and any missing parents) at the given path.
-     * Should be a no-op if the directory already exists.
-     * @param path - Absolute or relative path for the directory.
-     */
-    createFolder(path: string): Promise<void>;
-}
-/**
- * Options shared by all document converters, controlling output paths,
- * media extraction folder names, and metadata inclusion.
- */
-interface ConversionOptions {
-    /** Optional file path to write the generated markdown. When omitted, only the string is returned. */
-    outputPath?: string;
-    /** Name of the sub-folder (relative to outputDir) where extracted media will be stored. */
-    mediaFolderName: string;
-    /** When true, a YAML front-matter block with document metadata is prepended to the output. */
-    includeMetadata: boolean;
-}
-/**
- * Summary of a completed conversion, including statistics about
- * the generated output and extracted media.
- */
-interface ConversionResult {
-    /** Whether the conversion completed without errors. */
-    success: boolean;
-    /** Path where the markdown output was written. */
-    outputPath: string;
-    /** Character length of the generated markdown string. */
-    markdownLength: number;
-    /** Number of images extracted and saved to the media folder. */
-    imagesExtracted: number;
-    /** Absolute path to the media folder, or null if no images were extracted. */
-    mediaFolder: string | null;
-    /** Allows additional converter-specific metadata fields. */
-    [key: string]: unknown;
-}
-
-/**
- * Parses a Base64-encoded `data:` URL and returns the decoded binary
- * content along with a suitable file extension.
- *
- * @param dataUrl - A complete `data:` URL in the form `data:<mime>;base64,<payload>`.
- * @returns An object with `bytes` (the decoded binary data) and `ext` (the file extension).
- * @throws Error if the data URL does not match the expected `data:<mime>;base64,<payload>` format.
- *
- * @example
- * ```ts
- * const { bytes, ext } = dataUrlToMediaBytes('data:image/png;base64,iVBOR...');
- * // bytes: Uint8Array of PNG data
- * // ext: 'png'
- * ```
- */
-declare function dataUrlToMediaBytes(dataUrl: string): {
-    bytes: Uint8Array;
-    ext: string;
-};
-/**
- * Generates a deterministic, zero-padded filename for an extracted image.
- *
- * @param index - The 1-based ordinal of the image within the conversion session.
- * @param ext - File extension (with or without leading dot).
- * @returns A filename like `"image-001.png"`.
- *
- * @example
- * ```ts
- * generateMediaFilename(7, 'jpg'); // "image-007.jpg"
- * ```
- */
-declare function generateMediaFilename(index: number, ext: string): string;
-/**
- * Manages the extraction and persistence of media files (images) during
- * a PPTX-to-Markdown conversion session.
- *
- * Each `MediaContext` tracks a running count of saved images and ensures
- * the target media directory is lazily created on first write. When no
- * {@link FileSystemAdapter} is provided, filenames are still generated
- * (for in-memory usage) but nothing is written to disk.
- */
-declare class MediaContext {
-    private readonly folderName;
-    private readonly fs?;
-    /** Running counter used to assign unique sequential filenames. */
-    private imageIndex;
-    /** Whether the media output directory has been created yet. */
-    private initialized;
-    /** Fully resolved path to the media output directory. */
-    private readonly resolvedMediaDir;
-    /**
-     * @param outputDir - Root output directory for the conversion.
-     * @param folderName - Sub-folder name for media files (e.g. `"media"`).
-     * @param fs - Optional file system adapter; omit for in-memory-only conversion.
-     */
-    constructor(outputDir: string, folderName: string, fs?: FileSystemAdapter | undefined);
-    /** Returns the total number of images saved so far in this session. */
-    get totalImages(): number;
-    /** Returns the absolute path to the media output directory. */
-    get mediaDir(): string;
-    /**
-     * Decodes a Base64 `data:` URL, saves the image to disk (if a FS adapter
-     * is available), and returns a relative path suitable for embedding in markdown.
-     *
-     * @param dataUrl - The Base64-encoded data URL of the image.
-     * @param prefix - Optional filename prefix (e.g. `"slide3"`) for disambiguation.
-     * @returns A relative path like `"./media/slide3-image-001.png"`.
-     * @throws Error if the data URL is malformed.
-     */
-    saveImage(dataUrl: string, prefix?: string): Promise<string>;
-    /**
-     * Saves raw image bytes to disk and returns a relative path for markdown embedding.
-     *
-     * @param bytes - Raw binary content of the image.
-     * @param ext - File extension (e.g. `"png"`, `"jpg"`).
-     * @param prefix - Optional filename prefix for disambiguation.
-     * @returns A relative path like `"./media/image-001.png"`.
-     */
-    saveImageBytes(bytes: Uint8Array, ext: string, prefix?: string): Promise<string>;
-    /**
-     * Lazily creates the media output directory on the first call.
-     * Subsequent calls are no-ops.
-     */
-    private ensureInitialized;
-}
-
-/**
- * Normalises a file path by trimming whitespace and converting
- * backslashes to forward slashes for cross-platform consistency.
- *
- * @param pathValue - The raw file path string.
- * @returns The normalised path with forward slashes.
- *
- * @example
- * ```ts
- * normalizePath('  C:\\Users\\docs\\file.md  ');
- * // "C:/Users/docs/file.md"
- * ```
- */
-declare function normalizePath(pathValue: string): string;
-/**
- * Extracts the directory portion of a file path (everything before the
- * last `/` separator).
- *
- * @param filePath - A file path (backslashes are normalised automatically).
- * @returns The parent directory, `"."` if there is no separator, or `"/"` for root paths.
- *
- * @example
- * ```ts
- * getDirectory('/home/user/doc.md'); // "/home/user"
- * getDirectory('file.txt');          // "."
- * ```
- */
-declare function getDirectory(filePath: string): string;
-/**
- * Derives a `.md` output path from a source file path when no explicit
- * output path has been provided. Simply replaces the source extension
- * with `.md`.
- *
- * @param sourcePath - Original source file path (e.g. `"presentation.pptx"`).
- * @param explicitPath - An explicit output path; if provided, it is returned as-is.
- * @returns The derived markdown path, the explicit path, or `undefined` if both inputs are absent.
- *
- * @example
- * ```ts
- * deriveOutputPath('slides.pptx', undefined); // "slides.md"
- * deriveOutputPath('slides.pptx', '/tmp/out.md'); // "/tmp/out.md"
- * ```
- */
-declare function deriveOutputPath(sourcePath: string | undefined, explicitPath: string | undefined): string | undefined;
-/**
- * Abstract base class for document-to-Markdown converters.
- *
- * Provides shared infrastructure for media extraction ({@link MediaContext}),
- * YAML front-matter generation, and file output. Concrete subclasses implement
- * the {@link convert} method to handle a specific document type.
- *
- * @typeParam TSource - The parsed document data structure that this converter consumes.
- */
-declare abstract class DocumentConverter<TSource> {
-    protected readonly outputDir: string;
-    protected readonly options: ConversionOptions;
-    protected readonly fs?: FileSystemAdapter | undefined;
-    /** Shared context for extracting and saving media (images) during conversion. */
-    protected readonly mediaContext: MediaContext;
-    /**
-     * @param outputDir - Root directory for all output files (markdown + media).
-     * @param options - Conversion options (output path, media folder name, metadata flag).
-     * @param fs - Optional file system adapter for writing files to disk.
-     */
-    protected constructor(outputDir: string, options: ConversionOptions, fs?: FileSystemAdapter | undefined);
-    /**
-     * Converts the given source document into a Markdown string.
-     *
-     * @param source - The parsed document data to convert.
-     * @returns The generated Markdown content.
-     */
-    abstract convert(source: TSource): Promise<string>;
-    /**
-     * Builds a YAML front-matter block from a key-value metadata dictionary.
-     * String values are quoted; numeric values are emitted bare.
-     *
-     * @param metadata - Key-value pairs to include in the front matter.
-     * @returns A complete front-matter string (including `---` delimiters and trailing blank lines).
-     */
-    protected buildFrontMatter(metadata: Record<string, string | number>): string;
-    /**
-     * Writes the generated markdown content to an output file using the
-     * configured {@link FileSystemAdapter}.
-     *
-     * @param content - The markdown string to write.
-     * @param outputPath - Destination file path.
-     * @throws Error if no `FileSystemAdapter` was provided at construction time.
-     */
-    protected writeOutput(content: string, outputPath: string): Promise<void>;
-}
-
-/**
- * Options specific to PPTX-to-Markdown conversion, extending the base
- * {@link ConversionOptions} with presentation-aware settings.
- */
-interface PptxConverterOptions extends ConversionOptions {
-    /** Human-readable name of the source file, used in front-matter metadata. */
-    sourceName: string;
-    /** Whether to append speaker notes (as blockquotes) below each slide. */
-    includeSpeakerNotes: boolean;
-    /**
-     * Optional 1-based slide range to limit conversion to a subset of the deck.
-     * Omit or leave fields undefined to convert all slides.
-     */
-    slideRange?: {
-        /** First slide to include (1-based, default 1). */
-        start?: number;
-        /** Last slide to include (1-based, default = last slide). */
-        end?: number;
-    };
-    /**
-     * When true, emit clean semantic markdown instead of CSS-positioned HTML.
-     * Default is false (positioned HTML layout for slide fidelity).
-     */
-    semanticMode?: boolean;
-}
-/**
- * Converts a parsed {@link PptxData} presentation into a Markdown document.
- *
- * This is the primary entry point for PPTX-to-Markdown conversion. It
- * orchestrates slide processing, media extraction, metadata generation,
- * and output assembly. Each slide element type is handled by a dedicated
- * {@link ElementProcessor} registered in the internal registry.
- *
- * @example
- * ```ts
- * const converter = new PptxMarkdownConverter('/output', {
- *   sourceName: 'deck.pptx',
- *   includeSpeakerNotes: true,
- *   mediaFolderName: 'media',
- *   includeMetadata: true,
- * });
- * const markdown = await converter.convert(pptxData);
- * ```
- */
-declare class PptxMarkdownConverter extends DocumentConverter<PptxData> {
-    /** Renderer for rich-text segments (bold, italic, hyperlinks, etc.). */
-    private readonly textRenderer;
-    /** Registry mapping element types to their dedicated processors. */
-    private readonly registry;
-    /** Delegate responsible for converting individual slides. */
-    private readonly slideProcessor;
-    /** Number of slides actually converted (after applying the slide range filter). */
-    private convertedSlides;
-    /** Total number of slides in the source presentation. */
-    private totalSlides;
-    /**
-     * @param outputDir - Root directory for output files.
-     * @param options - PPTX-specific conversion options.
-     * @param fs - Optional file system adapter for writing media to disk.
-     */
-    constructor(outputDir: string, options: PptxConverterOptions, fs?: FileSystemAdapter);
-    /** Returns the number of images extracted and saved during conversion. */
-    get imagesExtracted(): number;
-    /** Returns the media directory path, or `null` if no images were extracted. */
-    get mediaDir(): string | null;
-    /** Returns the number of slides that were actually converted. */
-    get slidesConverted(): number;
-    /** Returns the total number of slides in the source presentation. */
-    get presentationSlides(): number;
-    /**
-     * Converts the full PPTX presentation (or a slide subset) into Markdown.
-     *
-     * The conversion pipeline:
-     * 1. Resolves the slide range and selects the target slides.
-     * 2. Processes each slide through {@link SlideProcessor}, producing markdown sections.
-     * 3. Inserts section headings when slides belong to named sections.
-     * 4. Optionally prepends YAML front-matter with document metadata.
-     * 5. Appends header/footer information if present.
-     * 6. Writes the output file if an `outputPath` was configured.
-     *
-     * @param source - The parsed PPTX data structure.
-     * @returns The complete Markdown string.
-     */
-    convert(source: PptxData): Promise<string>;
-    /**
-     * Registers all element-type processors into the internal registry.
-     * Each processor handles one or more {@link PptxElement} types
-     * (text, image, table, chart, etc.).
-     */
-    private registerProcessors;
-    /**
-     * Assembles a YAML front-matter block containing presentation metadata
-     * such as title, author, slide count, theme, dimensions, and more.
-     *
-     * @param source - The parsed PPTX data.
-     * @returns A YAML front-matter string (including `---` delimiters).
-     */
-    private buildPptxFrontMatter;
-    /**
-     * Populates metadata entries from OPC core properties (title, author, subject, etc.).
-     *
-     * @param meta - The metadata dictionary to populate.
-     * @param props - Core document properties from the PPTX file.
-     */
-    private addCoreProperties;
-    /**
-     * Populates metadata entries from application-level properties
-     * (application name, editing time, word/paragraph counts).
-     *
-     * @param meta - The metadata dictionary to populate.
-     * @param props - Application properties from the PPTX file.
-     */
-    private addAppProperties;
-    /**
-     * Adds presentation-level metadata (custom properties, show type, theme,
-     * security warnings, embedded fonts, custom shows) to the front-matter dictionary.
-     *
-     * @param meta - The metadata dictionary to populate.
-     * @param source - The full parsed PPTX data.
-     */
-    private addPresentationMeta;
-    /**
-     * Renders the presentation-level header/footer settings (header text,
-     * footer text, date/time, slide numbers) into a pipe-delimited markdown string.
-     *
-     * @param hf - Header/footer configuration from the presentation.
-     * @returns A formatted string, or an empty string if no header/footer data is present.
-     */
-    private renderHeaderFooter;
-    /**
-     * Resolves and clamps the user-specified slide range to valid bounds.
-     * Defaults to the full deck if no range is configured.
-     *
-     * @param totalSlides - Total number of slides in the presentation.
-     * @returns A 1-based `{ start, end }` range guaranteed to be within bounds.
-     */
-    private resolveRange;
-    /** Casts the base `options` to the PPTX-specific options type. */
-    private getOptions;
-}
-
-interface ElementProcessorContext {
-    mediaContext: MediaContext;
-    slideNumber: number;
-    /** Slide canvas width in CSS pixels (for layout positioning). */
-    slideWidth: number;
-    /** Slide canvas height in CSS pixels (for layout positioning). */
-    slideHeight: number;
-    /** Scale factor applied to the layout container (for font/image sizing). */
-    layoutScale?: number;
-    /**
-     * When true, processors should emit clean markdown instead of HTML.
-     * Tables become markdown tables, images use `![alt](path)` syntax,
-     * and text uses markdown formatting (not `<strong>`, `<em>`, etc.).
-     */
-    semanticMode?: boolean;
-    processElements: (elements: PptxElement[]) => Promise<string[]>;
-}
-interface ElementProcessor {
-    readonly supportedTypes: ReadonlyArray<PptxElement['type']>;
-    process(element: PptxElement, ctx: ElementProcessorContext): Promise<string | null>;
-}
-declare class ElementProcessorRegistry {
-    private readonly processors;
-    register(processor: ElementProcessor): void;
-    getProcessor(type: PptxElement['type']): ElementProcessor | null;
-    processElement(element: PptxElement, ctx: ElementProcessorContext): Promise<string | null>;
-    private buildActionAnnotation;
-}
-
-/**
- * Options controlling how text segments are rendered.
- */
-interface TextSegmentRenderOptions {
-    paragraphIndents?: Array<{
-        marginLeft?: number;
-        indent?: number;
-    }>;
-    slideNumber?: number;
-    dateTimeText?: string;
-    inlineMode?: boolean;
-    disableLists?: boolean;
-    disableAlignment?: boolean;
-    /**
-     * When true, emit HTML formatting tags instead of Markdown syntax.
-     */
-    htmlFormatting?: boolean;
-}
-declare class TextSegmentRenderer {
-    private readonly ommlConverter;
-    render(segments: TextSegment[], options?: TextSegmentRenderOptions): string;
-    renderInline(segments: TextSegment[], options?: TextSegmentRenderOptions): string;
-    plainText(segments: TextSegment[], options?: TextSegmentRenderOptions): string;
-    private groupParagraphs;
-    private renderParagraph;
-    private renderSegment;
-    private resolvePlainSegmentText;
-    private resolveFieldSegment;
-    private wrapCode;
-    private renderLinkDestination;
-    private escapeLinkTitle;
-    private escapeMarkdown;
-    private escapeHtml;
-}
-
-/**
- * Options controlling how a single slide is processed into Markdown.
- */
-interface SlideProcessorOptions {
-    /** Whether to include speaker notes below the slide content. */
-    includeSpeakerNotes: boolean;
-    /** Slide canvas width in CSS pixels (used for layout positioning). */
-    slideWidth: number;
-    /** Slide canvas height in CSS pixels (used for layout positioning). */
-    slideHeight: number;
-    /** When true, emit clean semantic markdown instead of positioned HTML. */
-    semanticMode?: boolean;
-}
-/**
- * Converts a single {@link PptxSlide} into a Markdown section.
- */
-declare class SlideProcessor {
-    private readonly registry;
-    private readonly mediaContext;
-    private readonly textRenderer;
-    /** Delegate for rendering slide-level metadata sections. */
-    private readonly metadataRenderer;
-    /**
-     * @param registry - Registry of element-type processors.
-     * @param mediaContext - Shared media extraction context.
-     * @param textRenderer - Renderer for rich-text segments.
-     */
-    constructor(registry: ElementProcessorRegistry, mediaContext: MediaContext, textRenderer: TextSegmentRenderer);
-    /** Processes a slide into a complete Markdown section. */
-    processSlide(slide: PptxSlide, options: SlideProcessorOptions): Promise<string>;
-    /**
-     * Builds the Markdown heading line for a slide, including its number,
-     * detected title text, and flags (hidden, layout name).
-     */
-    private buildHeading;
-    /**
-     * Returns an HTML `<img>` for the slide background that can be
-     * placed as the bottom-most layer inside the positioned container.
-     */
-    private renderBackgroundHtml;
-    /** Detects the slide's title from placeholder or first text element. */
-    private detectTitle;
-    /**
-     * Extracts the placeholder type from an element, if present.
-     */
-    private getPlaceholderType;
-    /** Processes elements as clean semantic markdown. */
-    private processElementsSemantic;
-    /** Processes elements using CSS absolute positioning. */
-    private processElementsWithLayout;
-    /** Sorts elements into natural reading order (top-to-bottom, left-to-right). */
-    private sortElementsByReadingOrder;
-}
-
-/**
- * Headless SVG exporter — converts parsed {@link PptxSlide} data to
- * SVG XML strings without requiring a browser DOM.
- *
- * All output is generated via string concatenation so the exporter
- * works in any JavaScript runtime (Node, Bun, Deno, Workers, etc.).
- *
- * @module converter/SvgExporter
- */
-
-/**
- * Options controlling SVG export behaviour.
- */
-interface SvgExportOptions {
-    /** Include hidden slides when exporting all. Default `false`. */
-    includeHidden?: boolean;
-    /** Slide indices to export (0-based). If omitted, all slides are exported. */
-    slideIndices?: number[];
-    /** Default font family when the element does not specify one. */
-    defaultFontFamily?: string;
-    /** Default font size in points when the element does not specify one. */
-    defaultFontSize?: number;
-}
-/**
- * Pure-TypeScript SVG exporter for parsed PPTX data.
- *
- * Generates well-formed SVG XML strings without any DOM dependency.
- *
- * @example
- * ```ts
- * const svgs = SvgExporter.exportAll(pptxData);
- * for (const [i, svg] of svgs.entries()) {
- *   fs.writeFileSync(`slide_${i + 1}.svg`, svg);
- * }
- * ```
- */
-declare class SvgExporter {
-    /**
-     * Export a single slide to an SVG XML string.
-     *
-     * @param slide  - The parsed slide.
-     * @param width  - SVG viewport width (pixels).
-     * @param height - SVG viewport height (pixels).
-     * @param options - Optional export settings.
-     * @returns A complete SVG document as a string.
-     */
-    static exportSlide(slide: PptxSlide, width: number, height: number, options?: SvgExportOptions): string;
-    /**
-     * Export all (or selected) slides to SVG XML strings.
-     *
-     * @param data    - The fully parsed PPTX data.
-     * @param options - Optional export settings.
-     * @returns An array of SVG strings (one per exported slide).
-     */
-    static exportAll(data: PptxData, options?: SvgExportOptions): string[];
-}
-
-export { type ConversionOptions as C, DocumentConverter as D, type FileSystemAdapter as F, MediaContext as M, type PptxConverterOptions as P, SlideProcessor as S, TextSegmentRenderer as T, type ConversionResult as a, PptxMarkdownConverter as b, type SlideProcessorOptions as c, type SvgExportOptions as d, SvgExporter as e, dataUrlToMediaBytes as f, deriveOutputPath as g, generateMediaFilename as h, getDirectory as i, normalizePath as n };