pptx-glimpse 3.0.0 → 3.1.1

package/dist/font-collector-BYuaCG-o.d.ts

@@ -0,0 +1,547 @@
+import { SourceHandle, PptxSourceModel } from '@pptx-glimpse/document';
+
+/**
+ * Mapping from PPTX font family names to replacement font family names.
+ *
+ * Keys are font names found in PPTX files. Values are font names that should be
+ * present in the rendering environment, commonly open-source alternatives to
+ * proprietary Microsoft Office fonts.
+ */
+type FontMapping = Record<string, string>;
+/**
+ * Default replacement mapping for common Microsoft Office fonts.
+ *
+ * The table maps fonts such as Calibri, Arial, Meiryo, and MS Gothic to
+ * open-source alternatives used during text measurement, SVG path generation,
+ * and font lookup.
+ */
+declare const DEFAULT_FONT_MAPPING: Readonly<FontMapping>;
+/**
+ * Create a font mapping table by merging defaults with user overrides.
+ *
+ * @param userMapping Custom PPTX font name to replacement font name entries.
+ * User-specified entries take precedence over `DEFAULT_FONT_MAPPING`.
+ * @returns A new mutable mapping object.
+ */
+declare function createFontMapping(userMapping?: FontMapping): FontMapping;
+/**
+ * Look up the replacement font for a PPTX font family.
+ *
+ * Matching is case-insensitive and normalizes full-width alphanumeric
+ * characters used by some Japanese Office font names.
+ *
+ * @param fontFamily PPTX font family name to resolve.
+ * @param mapping Mapping table, usually from `createFontMapping`.
+ * @returns The replacement font name, or `null` when no mapping exists.
+ */
+declare function getMappedFont(fontFamily: string | null | undefined, mapping: FontMapping): string | null;
+
+/**
+ * Controls how unsupported-feature warnings are collected and printed.
+ *
+ * `"off"` disables collection, `"warn"` collects entries and prints summaries,
+ * and `"debug"` also prints each warning as it is recorded.
+ */
+type LogLevel = "off" | "warn" | "debug";
+/**
+ * One unsupported or approximated feature encountered during conversion.
+ */
+interface WarningEntry {
+    /**
+     * Stable feature key, for example `"sp.style"` or `"bodyPr@vert"`.
+     */
+    feature: string;
+    /**
+     * Human-readable warning message.
+     */
+    message: string;
+    /**
+     * Optional location context, for example `"Slide 1"`.
+     */
+    context?: string;
+}
+/**
+ * Aggregated warnings from the most recent conversion cycle.
+ */
+interface WarningSummary {
+    /**
+     * Total number of warning entries.
+     */
+    totalCount: number;
+    /**
+     * Warning counts grouped by feature key.
+     */
+    features: {
+        feature: string;
+        message: string;
+        count: number;
+    }[];
+}
+interface WarningLogger {
+    warn(feature: string, message: string, context?: string): void;
+    debug(feature: string, message: string, context?: string): void;
+    getWarningSummary(): WarningSummary;
+    flushWarnings(): WarningSummary;
+    getWarningEntries(): readonly WarningEntry[];
+    getLogLevel(): LogLevel;
+}
+/**
+ * Return a grouped summary of currently collected warnings.
+ *
+ * This reads the active warning logger state. The public conversion APIs flush
+ * warnings at the end of a conversion so summaries can be printed; after that
+ * flush, this returns an empty summary until new warnings are recorded. It is
+ * mainly useful for lower-level renderer workflows, tests, and integrations
+ * that manage the warning cycle directly.
+ */
+declare function getWarningSummary(): WarningSummary;
+/**
+ * Return individual warning entries collected in the current warning cycle.
+ *
+ * Entries include optional slide or element context when available. The public
+ * conversion APIs flush entries at the end of a conversion, so this is mainly
+ * useful for lower-level renderer workflows, tests, and integrations that
+ * manage the warning cycle directly.
+ */
+declare function getWarningEntries(): readonly WarningEntry[];
+
+interface TextMeasurementContext {
+    readonly fontMapping?: FontMapping;
+    readonly warningLogger?: WarningLogger;
+    readonly fontWarningCache?: Set<string>;
+}
+/**
+ * Interface for measuring text width and line height.
+ * By default, measurement uses static font metrics.
+ * Users can pass their own implementation to ConvertOptions.textMeasurer
+ * Can be replaced with any measurement backend such as Canvas API or opentype.js.
+ */
+interface TextMeasurer {
+    /**
+     * Returns the estimated width of the text in pixels.
+     * @param text - text to measure
+     * @param fontSizePt - font size (points)
+     * @param bold - whether the text is bold
+     * @param fontFamily - font family name for Latin text
+     * @param fontFamilyEa - font family name for East Asian text
+     */
+    measureTextWidth(text: string, fontSizePt: number, bold: boolean, fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+    /**
+     * Returns the font's natural line height ratio (line height / font size).
+     * Returns 1.2 as a fallback value if the metric is unknown.
+     * @param fontFamily - font family name for Latin text
+     * @param fontFamilyEa - font family name for East Asian text
+     */
+    getLineHeightRatio(fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+    /**
+     * Font ascender ratio (ascender / unitsPerEm) .
+     * Used for baseline offset calculation in the first row.
+     * Returns 1.0 as a fallback value if the metric is unknown.
+     * @param fontFamily - font family name for Latin text
+     * @param fontFamilyEa - font family name for East Asian text
+     */
+    getAscenderRatio(fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+}
+
+/**
+ * Font resolver context for text-to-path conversion.
+ * Provides access to a Font object with the opentype.js getPath() method.
+ */
+
+interface OpentypePath {
+    toPathData(decimalPlaces?: number): string;
+}
+interface OpentypeFullFont {
+    unitsPerEm: number;
+    ascender: number;
+    descender: number;
+    getPath(text: string, x: number, y: number, fontSize: number): OpentypePath;
+    getAdvanceWidth(text: string, fontSize: number): number;
+}
+interface TextPathFontResolver {
+    resolveFont(fontFamily: string | null | undefined, fontFamilyEa: string | null | undefined, jpanFallback?: string | null, context?: TextPathFontResolverContext): OpentypeFullFont | null;
+}
+interface TextPathFontResolverContext {
+    readonly fontMapping?: FontMapping;
+    readonly warningLogger?: WarningLogger;
+    readonly fontWarningCache?: Set<string>;
+}
+
+interface OpentypeGlyph {
+    advanceWidth?: number;
+}
+interface OpentypeFont {
+    unitsPerEm: number;
+    ascender: number;
+    descender: number;
+    stringToGlyphs(text: string): OpentypeGlyph[];
+}
+declare class OpentypeTextMeasurer implements TextMeasurer {
+    private readonly fontMapping?;
+    private fonts;
+    private defaultFont;
+    private warnedFonts;
+    /**
+     * @param fonts - font name -> opentype.js Map of Font objects
+     * @param defaultFont - fallback font (optional)
+     */
+    constructor(fonts: Map<string, OpentypeFont>, defaultFont?: OpentypeFont, fontMapping?: FontMapping | undefined);
+    measureTextWidth(text: string, fontSizePt: number, bold: boolean, fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+    getLineHeightRatio(fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+    getAscenderRatio(fontFamily?: string | null, fontFamilyEa?: string | null, context?: TextMeasurementContext): number;
+    private resolveBoldFont;
+    private resolveFont;
+    private getMappedFont;
+}
+
+/**
+ * Font file data supplied directly by the caller.
+ *
+ * Use this when system font scanning is unavailable or undesirable, such as in
+ * browsers, Edge Runtime, or serverless environments. `name` can be used to
+ * register TTF/OTF buffers under a specific family name; family names from the
+ * font names table are also registered when available.
+ */
+interface FontBuffer {
+    /**
+     * Optional font family name to register for this buffer.
+     */
+    name?: string;
+    /**
+     * Raw TTF, OTF, or TTC font file bytes.
+     */
+    data: ArrayBuffer | Uint8Array;
+}
+/**
+ * Font services created from OpenType font data.
+ */
+interface OpentypeSetup {
+    /**
+     * Measures text width for layout and wrapping.
+     */
+    measurer: OpentypeTextMeasurer;
+    /**
+     * Resolves fonts for converting text to SVG path outlines.
+     */
+    fontResolver: TextPathFontResolver;
+}
+/**
+ * Create a text measurer from caller-provided font buffers.
+ *
+ * This low-level helper is useful when rendering in an environment where fonts
+ * are bundled as bytes instead of discovered from the OS. It dynamically imports
+ * `opentype.js` and returns `null` if no fonts can be parsed or the optional
+ * dependency is unavailable.
+ *
+ * @param fontBuffers Font file bytes to parse.
+ * @param fontMapping Optional PPTX font name to replacement font mapping.
+ * @returns A text measurer, or `null` when setup is not possible.
+ */
+declare function createOpentypeTextMeasurerFromBuffers(fontBuffers: FontBuffer[], fontMapping?: FontMapping): Promise<OpentypeTextMeasurer | null>;
+/**
+ * Create font measurement and SVG path resolution services from font buffers.
+ *
+ * Use this for integrations that need to provide fonts explicitly instead of
+ * relying on Node.js system font directories.
+ *
+ * @param fontBuffers TTF, OTF, or TTC font file bytes.
+ * @param fontMapping Optional PPTX font name to replacement font mapping.
+ * @returns Font services, or `null` when no usable font setup can be created.
+ */
+declare function createOpentypeSetupFromBuffers(fontBuffers: FontBuffer[], fontMapping?: FontMapping): Promise<OpentypeSetup | null>;
+/**
+ * Clear the module-level cache of parsed system fonts.
+ *
+ * Conversion APIs cache parsed font objects for repeated calls with the same
+ * font options. Call this after installing, removing, or replacing fonts in a
+ * long-running process when subsequent conversions must reload font files.
+ */
+declare function clearFontCache(): void;
+
+/**
+ * Options shared by PPTX-to-SVG and PPTX-to-PNG conversion.
+ */
+interface ConvertOptions {
+    /**
+     * Target slide numbers to convert, using PowerPoint-style 1-based numbering.
+     *
+     * When omitted, every slide in the presentation is converted. Missing or
+     * out-of-range slide numbers produce no output for those entries.
+     */
+    slides?: number[];
+    /**
+     * Output width in pixels.
+     *
+     * PNG output rasterizes to this width while preserving the slide aspect
+     * ratio. Defaults to 960. SVG output keeps the slide's native pixel size from
+     * the PPTX slide dimensions and does not use this option.
+     */
+    width?: number;
+    /**
+     * Output height in pixels.
+     *
+     * PNG rasterization currently always uses `width`, either the provided value
+     * or the default width, so this option is ignored by the public conversion
+     * APIs. SVG output keeps the slide's native pixel size and does not use this
+     * option.
+     */
+    height?: number;
+    /**
+     * Warning log level for unsupported or approximated PPTX features.
+     *
+     * Defaults to `"off"`. Diagnostics are always collected in the conversion
+     * report; this option only controls console output. Use `"warn"` to print
+     * summaries, or `"debug"` to print individual warning entries as they are
+     * recorded.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Additional directories that are scanned for font files.
+     *
+     * These directories are searched in addition to system font directories unless
+     * `skipSystemFonts` is true. This option uses Node.js filesystem APIs; use
+     * `fonts` when rendering in browsers, Edge Runtime, or other environments
+     * where filesystem access is unavailable.
+     */
+    fontDirs?: string[];
+    /**
+     * Font file bytes supplied directly by the caller.
+     *
+     * Use this browser-safe option when fonts are fetched from a URL, bundled by
+     * an application, or otherwise loaded without Node.js filesystem APIs. When
+     * provided, these font buffers are used instead of system font scanning.
+     */
+    fonts?: FontBuffer[];
+    /**
+     * Custom PPTX font name to replacement font name mapping.
+     *
+     * Entries are merged with `DEFAULT_FONT_MAPPING`; user-provided entries take
+     * precedence. This is useful when a PPTX references proprietary or corporate
+     * fonts that should render with installed alternatives.
+     */
+    fontMapping?: FontMapping;
+    /**
+     * Skip OS system font directories and only scan `fontDirs`.
+     *
+     * This is useful in containers or serverless environments where bundled fonts
+     * should be the only fonts used.
+     */
+    skipSystemFonts?: boolean;
+    /**
+     * Text output mode for SVG conversion.
+     *
+     * Defaults to `"path"`, which emits glyph outlines as `<path>` elements and
+     * does not require fonts in the SVG viewing environment. `"text"` emits native
+     * `<text>` elements with subset-font `@font-face` data URIs, enabling browser
+     * text selection and native text rendering for inline SVG.
+     *
+     * Embedded fonts and native text may not render as expected when the SVG is
+     * loaded through `<img src="...svg">` or sanitized. `convertPptxToPng` ignores
+     * this option and always renders with `"path"` output because resvg does not
+     * interpret the embedded `@font-face` rules used by SVG text output.
+     */
+    textOutput?: "path" | "text";
+}
+/**
+ * SVG conversion result for one slide.
+ */
+interface SlideSvg {
+    /**
+     * Original slide number in the PPTX file, using 1-based numbering.
+     */
+    slideNumber: number;
+    /**
+     * Complete SVG document string for the slide.
+     */
+    svg: string;
+}
+interface ConversionDiagnostic {
+    readonly source: "document" | "computed-view" | "renderer-adapter" | "renderer";
+    readonly severity: "info" | "warning" | "error";
+    readonly code: string;
+    readonly message: string;
+    readonly slideNumber?: number;
+    readonly sourcePartPath?: string;
+    readonly context?: string;
+    readonly handle?: SourceHandle;
+}
+interface SupportCoverageCounts {
+    /**
+     * Number of PPTX source/computed elements considered for rendering.
+     */
+    readonly inputElements: number;
+    /**
+     * Number of renderer-model elements produced for SVG / PNG output.
+     */
+    readonly outputElements: number;
+    /**
+     * Elements or raw nodes skipped because they are outside the supported render subset.
+     */
+    readonly skippedElements: number;
+    /**
+     * Elements skipped because a referenced PPTX part or relationship could not be resolved.
+     */
+    readonly unresolvedElements: number;
+    /**
+     * Elements or properties rendered with a fallback or ignored unsupported property.
+     */
+    readonly fallbackElements: number;
+    /**
+     * Diagnostics with warning severity that affect support/renderability confidence.
+     */
+    readonly warnings: number;
+}
+interface SlideSupportCoverage extends SupportCoverageCounts {
+    readonly slideNumber: number;
+}
+interface SupportCoverage {
+    /**
+     * Support/renderability coverage summary. This is not a visual-match or pixel accuracy metric.
+     */
+    readonly overall: SupportCoverageCounts;
+    readonly slides: readonly SlideSupportCoverage[];
+}
+interface SvgConversionReport {
+    readonly slides: readonly SlideSvg[];
+    readonly diagnostics: readonly ConversionDiagnostic[];
+    readonly supportCoverage: SupportCoverage;
+}
+type SystemFontSetupLoader = (options: ConvertOptions | undefined) => Promise<OpentypeSetup | null>;
+
+/**
+ * Convert a PPTX file to SVG documents.
+ *
+ * @param input PPTX binary data.
+ * @param options Conversion options. `slides` uses 1-based slide numbers; when
+ * omitted, all slides are converted.
+ * @returns A conversion report containing converted slides, diagnostics, and support coverage.
+ *
+ * Text is emitted as SVG paths by default for portable rendering. Set
+ * `textOutput: "text"` to emit native `<text>` elements with embedded subset
+ * fonts for inline browser SVG use. Font directories and font mapping options
+ * control how PPTX font names are resolved for text measurement and text output.
+ */
+declare function convertPptxToSvg$1(input: Uint8Array, options?: ConvertOptions, loadSystemFontSetup?: SystemFontSetupLoader): Promise<SvgConversionReport>;
+/**
+ * Render SVG documents from an already parsed PptxSourceModel.
+ *
+ * This avoids re-reading PPTX bytes when callers keep the result of `readPptx()`
+ * and need to render one or more slides repeatedly.
+ */
+declare function renderPptxSourceModelToSvg$1(source: PptxSourceModel, options?: ConvertOptions, loadSystemFontSetup?: SystemFontSetupLoader): Promise<SvgConversionReport>;
+
+/**
+ * PNG conversion result for one slide.
+ */
+interface SlideImage {
+    /**
+     * Original slide number in the PPTX file, using 1-based numbering.
+     */
+    slideNumber: number;
+    /**
+     * PNG image bytes for the rendered slide.
+     */
+    png: Uint8Array;
+    /**
+     * Actual output image width in pixels after rasterization.
+     */
+    width: number;
+    /**
+     * Actual output image height in pixels after rasterization.
+     */
+    height: number;
+}
+interface PngConversionReport {
+    readonly slides: readonly SlideImage[];
+    readonly diagnostics: SvgConversionReport["diagnostics"];
+    readonly supportCoverage: SupportCoverage;
+}
+/**
+ * Convert a PPTX file to SVG documents.
+ *
+ * @param input PPTX binary data.
+ * @param options Conversion options. `slides` uses 1-based slide numbers; when
+ * omitted, all slides are converted.
+ * @returns A conversion report containing converted slides, diagnostics, and support coverage.
+ *
+ * Text is emitted as SVG paths by default for portable rendering. Set
+ * `textOutput: "text"` to emit native `<text>` elements with embedded subset
+ * fonts for inline browser SVG use. Font directories and font mapping options
+ * control how PPTX font names are resolved for text measurement and text output.
+ */
+declare function convertPptxToSvg(input: Uint8Array, options?: ConvertOptions): Promise<SvgConversionReport>;
+/**
+ * Render SVG documents from an already parsed PptxSourceModel.
+ *
+ * Use this with `readPptx()` from `@pptx-glimpse/document` to repeatedly render
+ * slides without unzipping and parsing the PPTX bytes again.
+ */
+declare function renderPptxSourceModelToSvg(source: PptxSourceModel, options?: ConvertOptions): Promise<SvgConversionReport>;
+/**
+ * Convert a PPTX file to PNG images.
+ *
+ * @param input PPTX binary data.
+ * @param options Conversion options. `slides` uses 1-based slide numbers; when
+ * omitted, all slides are converted.
+ * @returns A conversion report containing converted PNG slides, diagnostics, and support coverage.
+ *
+ * PNG conversion first renders each slide to SVG and then rasterizes it with
+ * resvg. The `textOutput` option is intentionally ignored: PNG rendering always
+ * uses path-based text output because resvg does not interpret the embedded
+ * `@font-face` rules used by SVG text mode. Font directories and font mapping
+ * options are still used to resolve glyph outlines and text metrics.
+ */
+declare function convertPptxToPng(input: Uint8Array, options?: ConvertOptions): Promise<PngConversionReport>;
+
+/**
+ * Font names discovered in a PPTX file.
+ */
+interface UsedFonts {
+    /**
+     * Theme font slots resolved from the presentation's default theme.
+     */
+    theme: {
+        /**
+         * Major Latin theme font.
+         */
+        majorFont: string;
+        /**
+         * Minor Latin theme font.
+         */
+        minorFont: string;
+        /**
+         * Major East Asian theme font, when present.
+         */
+        majorFontEa: string | null;
+        /**
+         * Minor East Asian theme font, when present.
+         */
+        minorFontEa: string | null;
+        /**
+         * Major complex-script theme font, when present.
+         */
+        majorFontCs: string | null;
+        /**
+         * Minor complex-script theme font, when present.
+         */
+        minorFontCs: string | null;
+    };
+    /**
+     * Unique sorted font names used by text runs, bullets, and theme font slots.
+     */
+    fonts: string[];
+}
+/**
+ * Parse a PPTX file and collect the font names it references.
+ *
+ * This is a lightweight preflight helper: it reads the document model and text
+ * styles but does not render slides or load font files. Use it to decide which
+ * fonts should be installed, bundled, or mapped before calling the conversion
+ * APIs.
+ *
+ * @param input PPTX binary data.
+ * @returns Theme font slots and a unique sorted list of referenced font names.
+ */
+declare function collectUsedFonts(input: Uint8Array): UsedFonts;
+
+export { type ConversionDiagnostic as C, DEFAULT_FONT_MAPPING as D, type FontBuffer as F, type LogLevel as L, type OpentypeSetup as O, type PngConversionReport as P, type SlideImage as S, type UsedFonts as U, type WarningEntry as W, type ConvertOptions as a, type FontMapping as b, type SlideSupportCoverage as c, type SlideSvg as d, type SupportCoverage as e, type SupportCoverageCounts as f, type SvgConversionReport as g, type WarningSummary as h, clearFontCache as i, collectUsedFonts as j, convertPptxToPng as k, convertPptxToSvg as l, convertPptxToSvg$1 as m, createFontMapping as n, createOpentypeSetupFromBuffers as o, createOpentypeTextMeasurerFromBuffers as p, getMappedFont as q, getWarningEntries as r, getWarningSummary as s, renderPptxSourceModelToSvg as t, renderPptxSourceModelToSvg$1 as u };