@zumer/snapdom 1.9.9 → 1.9.10-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom",
-  "version": "1.9.9",
+  "version": "1.9.10-dev.1",
   "description": "snapDOM captures HTML elements to images with exceptional speed and accuracy.",
   "main": "dist/snapdom.js",
   "module": "dist/snapdom.mjs",

package/types/snapdom.d.ts

@@ -1,67 +1,178 @@
-declare module "@zumer/snapdom" {
-  export interface SnapOptions {
-    compress?: boolean;
-    embedFonts?: boolean;
-    localFonts?: Array<{ family: string; src: string; weight?: string; style?: string }>;
-    iconFonts?: string | RegExp | Array<string | RegExp>;
-    fast?: boolean;
-    scale?: number;
-    width?: number;
-    height?: number;
-    backgroundColor?: string;
-    format?: "png" | "jpeg" | "jpg" | "webp" | "svg";
-    type?: "png" | "jpeg" | "jpg" | "webp" | "svg";
-    filename?: string;
-    dpr?: number;
-    quality?: number;
-    useProxy?: string;
-    exclude?: string[];
-    filter?: (element: Element, originalElement: Element) => boolean;
-  }
-
-  export interface SnapResult {
-    url: string;
-    options: SnapOptions;
-    toRaw(): string;
-    toImg(): Promise<HTMLImageElement>;
-    toCanvas(): Promise<HTMLCanvasElement>;
-    toBlob(options?: SnapOptions): Promise<Blob>;
-    toPng(options?: SnapOptions): Promise<HTMLImageElement>;
-    toJpg(options?: SnapOptions): Promise<HTMLImageElement>;
-    toWebp(options?: SnapOptions): Promise<HTMLImageElement>;
-    download(options?: SnapOptions): Promise<void>;
-  }
+/**
+ * snapDOM – ultra-fast DOM-to-image capture
+ * TypeScript definitions
+ * 
+ * Notes:
+ * - Style compression is always enabled internally (no user option).
+ * - Icon fonts are always embedded; `embedFonts` controls non-icon fonts only.
+ */
+
+export type RasterMime = "png" | "jpg" | "jpeg" | "webp";
+export type BlobType = "svg" | RasterMime;
+
+export type IconFontMatcher = string | RegExp;
+
+export interface LocalFontDescriptor {
+  /** CSS font-family name (e.g. "Inter") */
+  family: string;
+  /** URL to the font source (woff2/woff/ttf). Data URLs are allowed. */
+  src: string;
+  /** CSS font-weight value (e.g. 400, "bold"). */
+  weight?: string | number;
+  /** CSS font-style value (e.g. "normal", "italic"). */
+  style?: string;
+  /** CSS font-stretch as percentage (e.g. 100 for normal). */
+  stretchPct?: number;
+}
+
+export interface CaptureOptions {
+  /**
+   * Skip small idle delays for faster overall capture on some browsers.
+   * Default: true
+   */
+  fast?: boolean;
+
+  /**
+   * Inline non-icon fonts that are detected as used within the captured subtree.
+   * Icon fonts are always embedded.
+   * Default: false
+   */
+  embedFonts?: boolean;
+
+  /**
+   * Additional local fonts to be considered during embedding.
+   */
+  localFonts?: LocalFontDescriptor[];
+
+  /**
+   * Extra icon font family matchers (by name or regex). Helpful for custom icon sets.
+   */
+  iconFonts?: IconFontMatcher | IconFontMatcher[];
+
+  /**
+   * Output scale multiplier. If set, takes precedence over width/height.
+   * Default: 1
+   */
+  scale?: number;
+
+  /**
+   * Device pixel ratio to use for raster exports.
+   * Default: `window.devicePixelRatio` at capture time.
+   */
+  dpr?: number;
+
+  /** Target width for the exported image. Ignored if `scale` is provided. */
+  width?: number;
+
+  /** Target height for the exported image. Ignored if `scale` is provided. */
+  height?: number;
+
+  /** Fallback color for JPG/WebP exports (no alpha). Default: "#fff". */
+  backgroundColor?: string;
+
+  /** Quality for JPG/WebP (0..1). Default: 1. */
+  quality?: number;
+
+  /**
+   * Proxy base URL used as a fallback for CORS-restricted images/fonts.
+   * Example: "https://corsproxy.io/?url="
+   */
+  useProxy?: string;
+
+  /** Preferred Blob type for `toBlob`. Default: "svg". */
+  type?: BlobType;
+
+  /**
+   * CSS selectors for elements to exclude entirely from capture.
+   * They are removed from the cloned subtree before processing.
+   */
+  exclude?: string[];
 
   /**
-   * Captura un elemento del DOM como imagen SVG + métodos de exportación.
+   * Advanced filter; return false to exclude a node.
+   * Applied to the cloned subtree during traversal.
    */
-  export function snapdom(
-    element: HTMLElement,
-    options?: SnapOptions
-  ): Promise<SnapResult>;
-
-  export namespace snapdom {
-    function capture(element: HTMLElement, options?: SnapOptions): Promise<SnapResult>;
-    function toRaw(element: HTMLElement, options?: SnapOptions): Promise<string>;
-    function toImg(element: HTMLElement, options?: SnapOptions): Promise<HTMLImageElement>;
-    function toCanvas(element: HTMLElement, options?: SnapOptions): Promise<HTMLCanvasElement>;
-    function toBlob(element: HTMLElement, options?: SnapOptions): Promise<Blob>;
-    function toPng(element: HTMLElement, options?: SnapOptions): Promise<HTMLImageElement>;
-    function toJpg(element: HTMLElement, options?: SnapOptions): Promise<HTMLImageElement>;
-    function toWebp(element: HTMLElement, options?: SnapOptions): Promise<HTMLImageElement>;
-    function download(element: HTMLElement, options?: SnapOptions): Promise<void>;
-  }
+  filter?: (el: Element) => boolean;
 
   /**
-   * Precarga imágenes, fondos y fuentes para acelerar capturas posteriores.
+   * Reset mode for internal caches at the beginning of capture.
+   * - "soft" (default): clear ephemeral/session caches (computed styles, per-capture maps).
+   * - "hard": clear all caches including images/resources/fonts/base styles.
+   * - "none": do not reset anything (fastest, may reuse stale resources).
    */
-  export function preCache(
-    root?: Document | HTMLElement,
-    options?: {
-      embedFonts?: boolean;
-      useProxy?: string;
-      reset?: boolean;
-      localFonts?: Array<{ family: string; src: string; weight?: string; style?: string }>;
-    }
-  ): Promise<void>;
+  reset?: "soft" | "hard" | "none";
+}
+
+export interface BlobOptions {
+  /** Blob type to export. Default: "svg". */
+  type?: BlobType;
+  /** JPG/WebP quality (0..1). */
+  quality?: number;
+  /** Background override for lossy formats. */
+  backgroundColor?: string;
 }
+
+export interface DownloadOptions {
+  /** File format. Default: "png". */
+  format?: "svg" | RasterMime;
+  /** Base filename without extension. Default: "capture". */
+  filename?: string;
+  /** Background override for lossy formats. */
+  backgroundColor?: string;
+  /** Quality for JPG/WebP (0..1). */
+  quality?: number;
+}
+
+export interface CaptureResult {
+  /** SVG data URL representing the captured element. */
+  url: string;
+  /** Returns the raw SVG markup as string. */
+  toRaw(): string;
+  /** Creates an HTMLImageElement from the SVG. */
+  toImg(): Promise<HTMLImageElement>;
+  /** Renders into a Canvas element (sized appropriately). */
+  toCanvas(): Promise<HTMLCanvasElement>;
+  /** Exports to a Blob (SVG/PNG/JPG/WebP). */
+  toBlob(options?: BlobOptions): Promise<Blob>;
+  /** Convenience PNG export (returns an <img>). */
+  toPng(options?: { backgroundColor?: string; quality?: number }): Promise<HTMLImageElement>;
+  /** Convenience JPG export (returns an <img>). */
+  toJpg(options?: { backgroundColor?: string; quality?: number }): Promise<HTMLImageElement>;
+  /** Convenience WebP export (returns an <img>). */
+  toWebp(options?: { backgroundColor?: string; quality?: number }): Promise<HTMLImageElement>;
+  /** Triggers a file download. */
+  download(options?: DownloadOptions): Promise<void>;
+}
+
+/**
+ * Capture an element and return reusable export helpers.
+ */
+export declare function snapdom(el: Element, options?: CaptureOptions): Promise<CaptureResult>;
+
+export declare namespace snapdom {
+  function toImg(el: Element, options?: CaptureOptions): Promise<HTMLImageElement>;
+  function toCanvas(el: Element, options?: CaptureOptions): Promise<HTMLCanvasElement>;
+  function toBlob(el: Element, options?: CaptureOptions & BlobOptions): Promise<Blob>;
+  function toPng(el: Element, options?: CaptureOptions): Promise<HTMLImageElement>;
+  function toJpg(el: Element, options?: CaptureOptions): Promise<HTMLImageElement>;
+  function toWebp(el: Element, options?: CaptureOptions): Promise<HTMLImageElement>;
+  function download(el: Element, options?: CaptureOptions & DownloadOptions): Promise<void>;
+}
+
+/**
+ * Preload resources (images/fonts) to avoid first-capture stalls.
+ */
+export interface PreCacheOptions {
+  /** Root element to scan. Default: document.body. */
+  root?: Element | Document;
+  /** Inline non-icon fonts during preload. Default: true. */
+  embedFonts?: boolean;
+  /** Additional local fonts. */
+  localFonts?: LocalFontDescriptor[];
+  /** Proxy for CORS fallbacks. */
+  useProxy?: string;
+}
+
+export declare function preCache(options?: PreCacheOptions): Promise<void>;
+
+export {};