@unicom-cloud/utils 0.1.23 → 0.1.25

package/snapdom/types/snapdom.d.ts

@@ -1,101 +1,362 @@
-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 {
+/**
+ * snapDOM – ultra-fast DOM-to-image capture
+ * TypeScript definitions (v1.9.14)
+ *
+ * Notes:
+ * - Style compression is internal (no public option).
+ * - Icon fonts are always embedded; `embedFonts` controls non-icon fonts only.
+ * - This file preserves backward compatibility with earlier 1.9.x defs.
+ */
+
+/* =========================
+ * Basic MIME / type aliases
+ * ========================= */
+
+export type RasterMime = 'png' | 'jpg' | 'jpeg' | 'webp';
+export type BlobType = 'svg' | RasterMime;
+
+export type IconFontMatcher = string | RegExp;
+export type CachePolicy = 'disabled' | 'full' | 'auto' | 'soft';
+
+/* =========================
+ * Font & proxy declarations
+ * ========================= */
+
+export interface LocalFont {
+  family: string;
+  src: string; // URL or data: URL
+  weight?: string | number;
+  style?: string;
+}
+
+export interface ExcludeFonts {
+  /** Case-insensitive family names to skip (non-icon only). */
+  families?: string[];
+  /** Host substrings to skip (e.g., "fonts.gstatic.com"). */
+  domains?: string[];
+  /** Unicode-range subset tags to skip (e.g., "cyrillic-ext"). */
+  subsets?: string[];
+}
+
+/* =========================
+ * Capture options
+ * ========================= */
+
+export interface SnapdomOptions {
+  /** Fast path: skip small idle delays where safe. */
+  fast?: boolean;
+  /** Output scale multiplier. Takes precedence over width/height. */
+  scale?: number;
+  /** Device pixel ratio to use for rasterization (defaults to `devicePixelRatio`). */
+  dpr?: number;
+  /** Target width of the export (keeps aspect if only one dimension is provided). */
+  width?: number;
+  /** Target height of the export (keeps aspect if only one dimension is provided). */
+  height?: number;
+
+  /** Background fallback color (used esp. for JPEG). Default "#fff". */
+  backgroundColor?: string;
+  /** Quality for JPEG/WebP (0..1). Default 1. */
+  quality?: number;
+
+  /** Cross-origin proxy prefix (used as a fallback when CORS blocks). */
+  useProxy?: string;
+
+  /** Default Blob type for toBlob() when unspecified. */
+  type?: BlobType;
+
+  /** CSS selector list to filter nodes. */
+  exclude?: string[];
+  /** How to apply `exclude` ("hide" keeps layout via visibility:hidden; "remove" drops nodes). Default "hide". */
+  excludeMode?: 'hide' | 'remove';
+
+  /**
+   * Custom predicate: return true to keep node, false to exclude.
+   * Runs in document order; pairs with `filterMode`.
+   */
+  filter?: (el: Element) => boolean;
+  /** How to apply `filter` ("hide" or "remove"). Default "hide". */
+  filterMode?: 'hide' | 'remove';
+
+  /** outerTransforms the root: remove translate/rotate, keep scale/skew. */
+  outerTransforms?: boolean;
+  /**
+   * Do not expand root bbox for shadows/blur/outline; also strip shadows/outline
+   * from the cloned root to get a tight capture box.
+   */
+  outerShadows?: boolean;
+
+  /** Inline non-icon fonts actually used within the subtree. */
+  embedFonts?: boolean;
+  /** Provide fonts explicitly to avoid remote discovery. */
+  localFonts?: LocalFont[];
+  /** Additional matchers for icon font families (strings or regex). */
+  iconFonts?: IconFontMatcher | IconFontMatcher[];
+  /** Skip specific non-icon fonts (by family/domain/subset). */
+  excludeFonts?: ExcludeFonts;
+
+  /**
+   * Fallback image when <img> fails to load.
+   * Can be a fixed URL or a callback that receives measured dimensions.
+   */
+  fallbackURL?:
+    | string
+    | ((dims: { width?: number; height?: number }) => string);
+
+  /** Cache policy for resources and style maps. Default "soft". */
+  cache?: CachePolicy;
+
+  /** Show placeholders when resources are missing. Default true. */
+  placeholders?: boolean;
+
+  /** Arbitrary plugin configuration at call-site (see PluginUse). */
+  plugins?: PluginUse[];
+}
+
+/* =========================
+ * Capture context (hook state)
+ * ========================= */
+
+export interface CaptureContext extends SnapdomOptions {
+  /** Input element being captured. */
+  element: Element;
+
+  /** Cloned root (detached), available after `beforeClone`/`afterClone`. */
+  clone?: HTMLElement | SVGElement | null;
+
+  /** Internal style/class caches (opaque to user). */
+  classCSS?: string;
+  styleCache?: unknown;
+  fontsCSS?: string;
+  baseCSS?: string;
+
+  /** Serialized artifacts, available after render. */
+  svgString?: string;
+  dataURL?: string;
+
+  /** Current export info during beforeExport/afterExport. */
+  export?: {
+    /** Export key (e.g., "png", "jpeg", "svg", or any custom key). */
+    type: string;
+    /** Options passed to the exporter. */
+    options?: any;
+    /** Canonical SVG data URL of this capture. */
     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>;
-  }
+  };
+}
+
+/* =========================
+ * Exporter signatures
+ * ========================= */
+
+export type Exporter = (ctx: CaptureContext, opts?: any) => Promise<any>;
 
+/** Map returned by `defineExports`: keys are exposed on the result (e.g., `pdf` → `result.toPdf()` as well as `result['pdf']()`). */
+export type ExportMap = Record<string, Exporter>;
+
+/* =========================
+ * Plugin system
+ * ========================= */
+
+export interface SnapdomPlugin {
+  /** Unique name for de-dupe/overrides. */
+  name: string;
+
+  /** Hook order follows registration order. All hooks may be async. */
+  beforeSnap?(context: CaptureContext): void | Promise<void>;
+  beforeClone?(context: CaptureContext): void | Promise<void>;
+  afterClone?(context: CaptureContext): void | Promise<void>;
+  beforeRender?(context: CaptureContext): void | Promise<void>;
+  afterRender?(context: CaptureContext): void | Promise<void>;
+
+  /** Runs before EACH export. */
+  beforeExport?(context: CaptureContext): void | Promise<void>;
   /**
-   * Captura un elemento del DOM como imagen SVG + métodos de exportación.
+   * Runs after EACH export; returning a value will be chained to the next plugin
+   * (transform pipeline). If undefined is returned, the prior result is preserved.
    */
-  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>;
-  }
+  afterExport?(context: CaptureContext, result: any): any | Promise<any>;
 
   /**
-   * Precarga imágenes, fondos y fuentes para acelerar capturas posteriores.
+   * Provide custom exporters (e.g., { pdf: async (ctx, opts) => Blob }).
+   * Keys are exposed on the capture result as helpers (toPdf()) and as index access (result['pdf']()).
    */
-  export function preCache(
-    root?: Document | HTMLElement,
-    options?: {
-      embedFonts?: boolean;
-      useProxy?: string;
-      reset?: boolean;
-      localFonts?: Array<{
-        family: string;
-        src: string;
-        weight?: string;
-        style?: string;
-      }>;
-    },
+  defineExports?(context: CaptureContext): ExportMap | Promise<ExportMap>;
+
+  /** Runs ONCE after the FIRST successful export of this capture (good for cleanup). */
+  afterSnap?(context: CaptureContext): void | Promise<void>;
+}
+
+export type PluginFactory = (options?: any) => SnapdomPlugin;
+/** You can pass a plugin instance, a factory, or a tuple with options. */
+export type PluginUse =
+  | SnapdomPlugin
+  | PluginFactory
+  | [PluginFactory, any]
+  | { plugin: PluginFactory; options?: any };
+
+/* =========================
+ * Capture result API
+ * ========================= */
+
+export interface DownloadOptions {
+  filename?: string;
+  /** Override default blob type for this download. */
+  type?: BlobType;
+  /** Quality hint for raster formats. */
+  quality?: number;
+  /** Target width/height for this export. */
+  width?: number;
+  height?: number;
+}
+
+export interface BlobOptions {
+  type?: BlobType;
+  quality?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface CaptureResult {
+  /** Canonical data URL of the SVG snapshot (when available). */
+  url: string;
+
+  /**
+   * @deprecated Use `toSvg()` for an <img> that renders the SVG snapshot.
+   * Historical alias kept for compatibility.
+   */
+  toImg(): Promise<HTMLImageElement>;
+
+  /** Returns an HTMLImageElement that renders the SVG snapshot. */
+  toSvg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
+
+  /** Returns a Canvas with the rasterized snapshot. */
+  toCanvas(options?: Partial<SnapdomOptions>): Promise<HTMLCanvasElement>;
+
+  /** Returns a Blob of the chosen type (svg/png/jpeg/webp). */
+  toBlob(options?: BlobOptions & Partial<SnapdomOptions>): Promise<Blob>;
+
+  /** Convenience raster exports returning an HTMLImageElement. */
+  toPng(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
+  toJpeg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
+  /** Alias for `toJpeg()`. */
+  toJpg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
+  toWebp(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
+
+  /** Trigger a client-side download of the snapshot using current/default settings. */
+  download(options?: DownloadOptions & Partial<SnapdomOptions>): Promise<void>;
+
+  /**
+   * Custom exporters exposed by plugins:
+   * - As helpers: a plugin returning { pdf: (...) => ... } also enables result.toPdf(...)
+   * - As index access: result["pdf"](...)
+   *
+   * Since keys are not known ahead of time, we allow index access.
+   */
+  [key: string]: any;
+}
+
+/* =========================
+ * Main callable & static helpers
+ * ========================= */
+
+/** Overload: main callable returns a reusable exporter object for the element. */
+export declare function snapdom(
+  element: Element,
+  options?: SnapdomOptions,
+): Promise<CaptureResult>;
+
+/**
+ * Global plugin registration (chainable).
+ * - De-duplicates by `name`.
+ * - Execution order = registration order.
+ * - Per-capture plugins run before globals and override by `name`.
+ */
+export declare namespace snapdom {
+  function plugins(...defs: PluginUse[]): typeof snapdom;
+
+  /** Shortcut helpers that run a one-off capture+export. */
+
+  /** @deprecated Returns an SVG <img>; prefer `toSvg`. */
+  function toImg(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  function toSvg(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  function toCanvas(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLCanvasElement>;
+
+  function toBlob(
+    element: Element,
+    options?: SnapdomOptions & BlobOptions,
+  ): Promise<Blob>;
+
+  function toPng(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  function toJpeg(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  /** Alias for `toJpeg`. */
+  function toJpg(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  function toWebp(
+    element: Element,
+    options?: SnapdomOptions,
+  ): Promise<HTMLImageElement>;
+
+  function download(
+    element: Element,
+    options?: SnapdomOptions & DownloadOptions,
   ): Promise<void>;
 }
+
+/* =========================
+ * preCache helper
+ * ========================= */
+
+export interface PreCacheOptions {
+  /** Root to scan (defaults to `document`). */
+  root?: Element | Document;
+  /** Try to embed non-icon fonts used under root (see also localFonts). */
+  embedFonts?: boolean;
+  /** Provide fonts explicitly to avoid remote discovery. */
+  localFonts?: LocalFont[];
+  /** Additional matchers for icon fonts (strings or regex). */
+  iconFonts?: IconFontMatcher | IconFontMatcher[];
+  /** Cross-origin proxy prefix (as in SnapdomOptions.useProxy). */
+  useProxy?: string;
+  /** Cache policy for this preload operation. */
+  cache?: CachePolicy;
+
+  /** Back-compat fields (no-ops if present) */
+  /**
+   * @deprecated Use `cache` instead.
+   */
+  cacheOpt?: CachePolicy;
+}
+
+/**
+ * Preload external resources for a subtree to avoid first-capture stalls.
+ * Uses the same discovery heuristics as the main capture path.
+ */
+export declare function preCache(
+  root?: Element | Document,
+  options?: PreCacheOptions,
+): Promise<void>;
+
+export {};

package/snapdom.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { preCache as e } from "./snapdom/src/api/preCache.js";
 import { snapdom as m } from "./snapdom/src/api/snapdom.js";
 export {

package/tinycolor/index.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { cmykToRgb as e, convertDecimalToHex as t, convertHexToDecimal as a, hslToRgb as n, hsvToRgb as b, numberInputToObject as m, parseIntFromHex as T, rgbToCmyk as i, rgbToHex as g, rgbToHsl as p, rgbToHsv as l, rgbToRgb as s, rgbaToArgbHex as x, rgbaToHex as c } from "./src/conversion.js";
 import { names as f } from "./src/css-color-names.js";
 import { inputToRGB as u, isValidCSSUnit as H, stringInputToObject as y } from "./src/format-input.js";
@@ -6,7 +7,7 @@ import { TinyColor as O, TinyColor as P } from "./src/index.js";
 import { bounds as k, random as A } from "./src/random.js";
 import { isReadable as F, mostReadable as S, readability as B } from "./src/readability.js";
 import { toMsFilter as M } from "./src/to-ms-filter.js";
-import { bound01 as V, boundAlpha as Z, clamp01 as q, convertToPercentage as w, isOnePointZero as z, isPercentage as E, pad2 as J } from "./src/util.js";
+import { bound01 as V, boundAlpha as Z, clamp01 as q, convertToPercentage as w, isOnePointZero as z, isPercentage as E, pad2 as J } from "./src/utils.js";
 export {
   O as TinyColor,
   V as bound01,

package/tinycolor/src/conversion.js

@@ -1,4 +1,5 @@
-import { bound01 as s, pad2 as h } from "./util.js";
+/* 2025-11-03 10:27:31 */
+import { bound01 as s, pad2 as h } from "./utils.js";
 function A(n, r, t) {
   return {
     r: s(n, 255) * 255,

package/tinycolor/src/css-color-names.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 const e = {
   aliceblue: "#f0f8ff",
   antiquewhite: "#faebd7",

package/tinycolor/src/format-input.js

@@ -1,6 +1,7 @@
+/* 2025-11-03 10:27:31 */
 import { rgbToRgb as S, hsvToRgb as v, hslToRgb as E, cmykToRgb as F, convertHexToDecimal as A, parseIntFromHex as s } from "./conversion.js";
 import { names as R } from "./css-color-names.js";
-import { convertToPercentage as g, boundAlpha as T } from "./util.js";
+import { convertToPercentage as g, boundAlpha as T } from "./utils.js";
 function N(t) {
   let a = { r: 0, g: 0, b: 0 }, e = 1, m = null, b = null, p = null, r = !1, i = !1;
   return typeof t == "string" && (t = w(t)), typeof t == "object" && (n(t.r) && n(t.g) && n(t.b) ? (a = S(t.r, t.g, t.b), r = !0, i = String(t.r).slice(-1) === "%" ? "prgb" : "rgb") : n(t.h) && n(t.s) && n(t.v) ? (m = g(t.s), b = g(t.v), a = v(t.h, m, b), r = !0, i = "hsv") : n(t.h) && n(t.s) && n(t.l) ? (m = g(t.s), p = g(t.l), a = E(t.h, m, p), r = !0, i = "hsl") : n(t.c) && n(t.m) && n(t.y) && n(t.k) && (a = F(t.c, t.m, t.y, t.k), r = !0, i = "cmyk"), Object.prototype.hasOwnProperty.call(t, "a") && (e = t.a)), e = T(e), {

package/tinycolor/src/from-ratio.js

@@ -1,5 +1,6 @@
+/* 2025-11-03 10:27:31 */
 import { TinyColor as e } from "./index.js";
-import { convertToPercentage as o } from "./util.js";
+import { convertToPercentage as o } from "./utils.js";
 function c(n, m) {
   const r = {
     r: o(n.r),

package/tinycolor/src/index.js

@@ -1,7 +1,8 @@
+/* 2025-11-03 10:27:31 */
 import { numberInputToObject as d, rgbToHsv as g, rgbToHsl as u, rgbToHex as b, rgbaToHex as m, rgbToCmyk as c } from "./conversion.js";
 import { names as $ } from "./css-color-names.js";
 import { inputToRGB as f } from "./format-input.js";
-import { boundAlpha as M, clamp01 as a, bound01 as l } from "./util.js";
+import { boundAlpha as M, clamp01 as a, bound01 as l } from "./utils.js";
 class n {
   constructor(t = "", s = {}) {
     if (t instanceof n)

package/tinycolor/src/random.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { TinyColor as l } from "./index.js";
 function g(e = {}) {
   if (e.count !== void 0 && e.count !== null) {

package/tinycolor/src/readability.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { TinyColor as a } from "./index.js";
 function i(n, t) {
   const l = new a(n), e = new a(t);

package/tinycolor/src/to-ms-filter.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { rgbaToArgbHex as i } from "./conversion.js";
 import { TinyColor as g } from "./index.js";
 function d(s, o) {

package/tinycolor/src/{util.js → utils.js}

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 function o(t, r) {
   i(t) && (t = "100%");
   const e = n(t);

package/tinycolor.js

@@ -1,3 +1,4 @@
+/* 2025-11-03 10:27:31 */
 import { cmykToRgb as e, convertDecimalToHex as t, convertHexToDecimal as a, hslToRgb as n, hsvToRgb as b, numberInputToObject as m, parseIntFromHex as T, rgbToCmyk as i, rgbToHex as g, rgbToHsl as p, rgbToHsv as l, rgbToRgb as s, rgbaToArgbHex as x, rgbaToHex as c } from "./tinycolor/src/conversion.js";
 import { names as f } from "./tinycolor/src/css-color-names.js";
 import { inputToRGB as u, isValidCSSUnit as H, stringInputToObject as y } from "./tinycolor/src/format-input.js";
@@ -6,7 +7,7 @@ import { TinyColor as O, TinyColor as P } from "./tinycolor/src/index.js";
 import { bounds as k, random as A } from "./tinycolor/src/random.js";
 import { isReadable as F, mostReadable as S, readability as B } from "./tinycolor/src/readability.js";
 import { toMsFilter as M } from "./tinycolor/src/to-ms-filter.js";
-import { bound01 as V, boundAlpha as Z, clamp01 as q, convertToPercentage as w, isOnePointZero as z, isPercentage as E, pad2 as J } from "./tinycolor/src/util.js";
+import { bound01 as V, boundAlpha as Z, clamp01 as q, convertToPercentage as w, isOnePointZero as z, isPercentage as E, pad2 as J } from "./tinycolor/src/utils.js";
 export {
   O as TinyColor,
   V as bound01,