emf-converter 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -1,20 +1,109 @@
 /**
- * Public API, a single auto-detecting entry point consumed by the rest of
- * the application.
+ * A tiny, framework-agnostic SVG document model plus its serialisers.
  *
- * The conversion pipeline for both formats follows the same high-level steps:
- * 1. Parse the file header to determine logical bounds and canvas dimensions
+ * The SVG backend (`svg-context.ts`) records a metafile's drawing into an
+ * {@link SvgNode} tree rather than straight into markup, so the same result
+ * can be handed to whichever consumer needs it:
+ *
+ * - {@link svgTreeToString}: standalone SVG markup (`<svg xmlns=...>...</svg>`)
+ * - {@link svgTreeToDataUrl}: a `data:image/svg+xml;base64,...` URL, usable
+ *   anywhere an image URL is (`<img src>`, CSS `background-image`, ...)
+ * - {@link svgTreeToReact}: live elements for React (or Preact, Solid's
+ *   `h`, Vue's `h`, ...), built through a caller-supplied `createElement`,
+ *   so this package never depends on a UI framework
+ * - {@link svgTreeToJsx}: JSX/TSX component source code, for build-time code
+ *   generation in the style of SVGR
+ *
+ * Attribute names are stored in their SVG (kebab-case) spelling; the React
+ * and JSX serialisers convert them to the camelCase property names React
+ * expects (`stroke-width` → `strokeWidth`, `clip-path` → `clipPath`, and a
+ * `style` string becomes a style object).
+ *
+ * @module svg-tree
+ */
+/** One SVG element. Text content (for `<text>`) lives in {@link SvgNode.text}. */
+interface SvgNode {
+    /** Element name, e.g. `path`, `g`, `linearGradient`. */
+    tag: string;
+    /** Attributes in SVG spelling (`stroke-width`, `clip-path`, `style`). */
+    attrs: Record<string, string | number>;
+    /** Child elements, in paint order. */
+    children?: SvgNode[];
+    /** Character data for text-bearing elements. Mutually exclusive with children. */
+    text?: string;
+}
+/** Serialises a tree to SVG markup. The root should be an `<svg>` element. */
+declare function svgTreeToString(node: SvgNode): string;
+/** Serialises a tree to a base64 `data:image/svg+xml` URL. */
+declare function svgTreeToDataUrl(node: SvgNode): string;
+/**
+ * A `createElement`-compatible factory: `React.createElement`, Preact's `h`,
+ * and most hyperscript-style factories fit this shape.
+ */
+type CreateElement<E> = (type: string, props: Record<string, unknown> | null, ...children: unknown[]) => E;
+/**
+ * Builds live framework elements from a tree via `createElement`.
+ *
+ * ```tsx
+ * import { createElement } from 'react';
+ * const tree = await convertMetafileToSvgTree(buffer);
+ * return tree ? svgTreeToReact(tree, createElement, { className: 'figure', width: '100%' }) : null;
+ * ```
+ *
+ * @param node          - The tree (normally the root `<svg>`).
+ * @param createElement - `React.createElement` or a compatible factory.
+ * @param rootProps     - Extra props merged onto the root element (override
+ *                        `width`/`height`, add `className`, `role`, ...).
+ */
+declare function svgTreeToReact<E>(node: SvgNode, createElement: CreateElement<E>, rootProps?: Record<string, unknown>): E;
+/** Options for {@link svgTreeToJsx}. */
+interface SvgJsxOptions {
+    /** Component name. Default `Metafile`. */
+    componentName?: string;
+    /** Emit TypeScript (`SVGProps<SVGSVGElement>` typing). Default `true`. */
+    typescript?: boolean;
+    /**
+     * Spread the component's props onto the root `<svg>` (after the recorded
+     * attributes, so callers can override `width`/`height`). Default `true`.
+     */
+    spreadProps?: boolean;
+}
+/**
+ * Generates JSX/TSX source for a React component rendering the tree, for
+ * build-time code generation (write it to a `.tsx` file and import it).
+ *
+ * ```ts
+ * const tree = await convertMetafileToSvgTree(buffer, { idPrefix: 'logo-' });
+ * writeFileSync('Logo.tsx', svgTreeToJsx(tree!, { componentName: 'Logo' }));
+ * ```
+ *
+ * The output uses the automatic JSX runtime (no `import React` needed); with
+ * `typescript: true` it imports only the `SVGProps` type from `react`.
+ */
+declare function svgTreeToJsx(node: SvgNode, options?: SvgJsxOptions): string;
+
+/**
+ * Public API: auto-detecting EMF/WMF conversion to PNG or SVG.
+ *
+ * The conversion pipeline for both formats and both outputs follows the same
+ * high-level steps:
+ * 1. Parse the file header to determine logical bounds and output dimensions
  *    (tried as EMF first, then WMF, to auto-detect the format).
- * 2. Create an in-memory canvas (OffscreenCanvas preferred, HTMLCanvasElement
- *    fallback, or the optional `@napi-rs/canvas` Node.js backend).
- * 3. Replay every metafile record onto the canvas context in order.
+ * 2. Create a drawing surface: an in-memory canvas (OffscreenCanvas
+ *    preferred, HTMLCanvasElement fallback, or the optional `@napi-rs/canvas`
+ *    Node.js backend) for PNG output, or an {@link SvgContext} recorder for
+ *    SVG output.
+ * 3. Replay every metafile record onto the surface in order.
  * 4. Resolve "deferred images", bitmap / embedded-metafile draws that require
  *    async image decoding (via {@link createImageBitmap} or, in Node.js, the
- *    `@napi-rs/canvas` `loadImage` helper).
- * 5. Export the canvas contents as a `data:image/png;base64,...` URL.
+ *    `@napi-rs/canvas` `loadImage` helper). SVG output embeds PNG/JPEG/GIF/
+ *    WebP bytes verbatim and nested metafiles as nested SVG, with no decode.
+ * 5. Export: a `data:image/png;base64,...` URL, or an SVG tree that can be
+ *    serialised to markup, a data URL, React elements, or JSX source.
  *
  * @module emf-converter
  */
+
 /**
  * Configuration options for EMF/WMF conversion.
  */
@@ -25,8 +114,8 @@ interface EmfConvertOptions {
     maxHeight?: number;
     /**
      * DPI scale factor for higher-resolution output.
-     * Default is 2 (HiDPI). Set to 1 for 1:1 pixel mapping.
-     * Values above 4 are clamped to 4 to prevent excessive memory usage.
+     * Default is 1 (1:1 pixel mapping). Values above 4 are clamped to 4 to
+     * prevent excessive memory usage.
      */
     dpiScale?: number;
     /**
@@ -46,6 +135,48 @@ interface EmfConvertOptions {
      * 'ms shell dlg': 'Tahoma' }`. Applied to GDI, WMF, and EMF+ text.
      */
     fontFamilyMap?: Record<string, string>;
+    /**
+     * Antialias plain-GDI (EMF) vector shapes: Rectangle, Ellipse, RoundRect,
+     * Polygon, Polyline, arcs, and bracketed paths. Default `true`, Canvas's
+     * own smooth edges. `false` rasterises their fills and strokes the way
+     * Windows GDI does, without antialiasing and on GDI's own pixel grid, for
+     * output that matches what Windows paints pixel for pixel. It reads back
+     * and rewrites each shape's bounding box, so it is noticeably slower on
+     * shape-heavy files. EMF+ drawing and text are unaffected.
+     */
+    gdiAntialias?: boolean;
+}
+/**
+ * Options for the SVG outputs ({@link convertMetafileToSvg} and friends).
+ * `maxWidth`/`maxHeight`/`dpiScale`/`maxCanvasDimension` set the SVG's
+ * coordinate space (its `viewBox` and default `width`/`height`) and the
+ * resolution of any embedded raster content; vector content stays sharp at
+ * any display size.
+ */
+interface SvgConvertOptions extends EmfConvertOptions {
+    /**
+     * Evaluate raster operations that read the destination (exact ROP3 blits,
+     * exact bitwise ROP2) against a hidden raster mirror of the drawing, and
+     * embed the pixels they change as image patches. Needs a canvas backend
+     * (browser/worker canvas, or `@napi-rs/canvas` in Node.js); without one,
+     * or when set to `false`, those operations fall back to SVG blend modes
+     * (`mix-blend-mode`), which are exact for the common mask ROPs on
+     * black/white masks and approximate otherwise. Default `true`.
+     */
+    exactRasterOps?: boolean;
+    /**
+     * Emit `width`/`height` attributes on the root `<svg>` (the `viewBox` is
+     * always emitted). Set `false` for a fluid SVG that fills its container.
+     * Default `true`.
+     */
+    includeSize?: boolean;
+    /**
+     * Prefix for every generated element id (clip paths, gradients,
+     * patterns). Ids must be unique within an HTML document, so give each
+     * inlined SVG its own prefix. Defaults to a per-process counter
+     * (`emf1-`, `emf2-`, ...).
+     */
+    idPrefix?: string;
 }
 /**
  * Converts an EMF (Enhanced Metafile) or WMF (Windows Metafile) binary buffer
@@ -56,23 +187,12 @@ interface EmfConvertOptions {
  * starts with a valid `EMR_HEADER` record, so it doubles as a safe format
  * sniff. When that probe fails, the buffer is parsed as WMF instead.
  *
- * For EMF: parses the EMF header, iterates over all EMR records, and replays
- * them onto an in-memory canvas. Embedded EMF+ (GDI+) records found inside
- * EMR_COMMENT payloads are handled transparently.
- *
- * For WMF: parses the optional Aldus placeable header and the standard WMF
- * header, then replays all META_* records onto a canvas.
- *
- * The canvas is rendered at a configurable DPI scale (default 1x, 1:1 pixel
- * mapping) via {@link EmfConvertOptions.dpiScale}. On the first call in a
- * given process, the optional Node.js canvas backend (`@napi-rs/canvas`) is
- * loaded once and cached; see {@link ensureNodeCanvasModule}.
- *
  * Returns `null` when:
  * - The buffer matches neither a valid EMF header nor a valid WMF header.
  * - The logical bounds are zero-sized or negative.
  * - No canvas API is available (browser/worker canvas, or the optional
- *   `@napi-rs/canvas` package in plain Node.js).
+ *   `@napi-rs/canvas` package in plain Node.js). SVG output
+ *   ({@link convertMetafileToSvg}) needs no canvas at all.
  *
  * @param buffer  - The raw EMF or WMF file bytes.
  * @param options - Optional {@link EmfConvertOptions} controlling output size,
@@ -81,6 +201,36 @@ interface EmfConvertOptions {
  * @returns A `data:image/png;base64,...` string, or `null` on failure.
  */
 declare function convertMetafileToDataUrl(buffer: ArrayBuffer, options?: EmfConvertOptions, recursionDepth?: number): Promise<string | null>;
+/**
+ * Converts an EMF or WMF buffer (format auto-detected) into an SVG document
+ * tree, the common source for every SVG output form: serialise it with
+ * {@link svgTreeToString} / {@link svgTreeToDataUrl}, render it in React
+ * with {@link svgTreeToReact}, or generate component source with
+ * {@link svgTreeToJsx}.
+ *
+ * Unlike PNG output this needs no canvas implementation: vectors, text,
+ * gradients, clipping, and bitmaps are all recorded in pure JavaScript. A
+ * canvas backend, when present, is used only to evaluate destination-
+ * reading raster operations exactly (see {@link SvgConvertOptions.exactRasterOps})
+ * and to measure text.
+ *
+ * @returns The root `<svg>` node, or `null` for an invalid/empty metafile.
+ */
+declare function convertMetafileToSvgTree(buffer: ArrayBuffer, options?: SvgConvertOptions, recursionDepth?: number): Promise<SvgNode | null>;
+/**
+ * Converts an EMF or WMF buffer into standalone SVG markup
+ * (`<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>`).
+ *
+ * @returns The SVG markup, or `null` for an invalid/empty metafile.
+ */
+declare function convertMetafileToSvg(buffer: ArrayBuffer, options?: SvgConvertOptions): Promise<string | null>;
+/**
+ * Converts an EMF or WMF buffer into a base64 SVG data URL
+ * (`data:image/svg+xml;base64,...`), usable directly as an `<img src>`.
+ *
+ * @returns The data URL, or `null` for an invalid/empty metafile.
+ */
+declare function convertMetafileToSvgDataUrl(buffer: ArrayBuffer, options?: SvgConvertOptions): Promise<string | null>;
 
 /**
  * The default DPI scale factor used for EMF/WMF rendering.
@@ -89,4 +239,4 @@ declare function convertMetafileToDataUrl(buffer: ArrayBuffer, options?: EmfConv
  */
 declare const DEFAULT_DPI_SCALE = 1;
 
-export { DEFAULT_DPI_SCALE, type EmfConvertOptions, convertMetafileToDataUrl };
+export { type CreateElement, DEFAULT_DPI_SCALE, type EmfConvertOptions, type SvgConvertOptions, type SvgJsxOptions, type SvgNode, convertMetafileToDataUrl, convertMetafileToSvg, convertMetafileToSvgDataUrl, convertMetafileToSvgTree, svgTreeToDataUrl, svgTreeToJsx, svgTreeToReact, svgTreeToString };