html2canvas-pro 2.0.3 → 2.1.0

package/src/dom/replaced-elements/input-element-container.ts

@@ -0,0 +1,105 @@
+import { ElementContainer } from '../element-container';
+import { BORDER_STYLE } from '../../css/property-descriptors/border-style';
+import { BACKGROUND_CLIP } from '../../css/property-descriptors/background-clip';
+import { BACKGROUND_ORIGIN } from '../../css/property-descriptors/background-origin';
+import { TokenType } from '../../css/syntax/tokenizer';
+import { LengthPercentageTuple } from '../../css/types/length-percentage';
+import { Bounds } from '../../css/layout/bounds';
+import { Context } from '../../core/context';
+
+const CHECKBOX_BORDER_RADIUS: LengthPercentageTuple = [
+    {
+        type: TokenType.DIMENSION_TOKEN,
+        flags: 0,
+        unit: 'px',
+        number: 3
+    }
+];
+
+const RADIO_BORDER_RADIUS: LengthPercentageTuple = [
+    {
+        type: TokenType.PERCENTAGE_TOKEN,
+        flags: 0,
+        number: 50
+    }
+];
+
+const reformatInputBounds = (bounds: Bounds): Bounds => {
+    if (bounds.width > bounds.height) {
+        return new Bounds(bounds.left + (bounds.width - bounds.height) / 2, bounds.top, bounds.height, bounds.height);
+    } else if (bounds.width < bounds.height) {
+        return new Bounds(bounds.left, bounds.top + (bounds.height - bounds.width) / 2, bounds.width, bounds.width);
+    }
+    return bounds;
+};
+
+const getInputValue = (node: HTMLInputElement): string => {
+    const value = node.type === PASSWORD ? new Array(node.value.length + 1).join('\u2022') : node.value;
+
+    return value.length === 0 ? node.placeholder || '' : value;
+};
+
+const isPlaceholder = (node: HTMLInputElement): boolean => {
+    return node.value.length === 0 && !!node.placeholder;
+};
+
+export const CHECKBOX = 'checkbox';
+export const RADIO = 'radio';
+export const PASSWORD = 'password';
+export const INPUT_COLOR = 0x2a2a2aff;
+// Default placeholder color (similar to browsers: rgba(117, 117, 117, 1) or #757575)
+export const PLACEHOLDER_COLOR = 0x757575ff;
+
+export class InputElementContainer extends ElementContainer {
+    readonly type: string;
+    readonly checked: boolean;
+    readonly value: string;
+    readonly isPlaceholder: boolean;
+
+    constructor(context: Context, input: HTMLInputElement) {
+        super(context, input);
+        this.type = input.type.toLowerCase();
+        this.checked = input.checked;
+        this.value = getInputValue(input);
+        this.isPlaceholder = isPlaceholder(input);
+
+        if (this.type === CHECKBOX || this.type === RADIO) {
+            this.styles.backgroundColor = 0xdededeff;
+            this.styles.borderTopColor =
+                this.styles.borderRightColor =
+                this.styles.borderBottomColor =
+                this.styles.borderLeftColor =
+                    0xa5a5a5ff;
+            this.styles.borderTopWidth =
+                this.styles.borderRightWidth =
+                this.styles.borderBottomWidth =
+                this.styles.borderLeftWidth =
+                    1;
+            this.styles.borderTopStyle =
+                this.styles.borderRightStyle =
+                this.styles.borderBottomStyle =
+                this.styles.borderLeftStyle =
+                    BORDER_STYLE.SOLID;
+            this.styles.backgroundClip = [BACKGROUND_CLIP.BORDER_BOX];
+            this.styles.backgroundOrigin = [BACKGROUND_ORIGIN.BORDER_BOX];
+            this.bounds = reformatInputBounds(this.bounds);
+        }
+
+        switch (this.type) {
+            case CHECKBOX:
+                this.styles.borderTopRightRadius =
+                    this.styles.borderTopLeftRadius =
+                    this.styles.borderBottomRightRadius =
+                    this.styles.borderBottomLeftRadius =
+                        CHECKBOX_BORDER_RADIUS;
+                break;
+            case RADIO:
+                this.styles.borderTopRightRadius =
+                    this.styles.borderTopLeftRadius =
+                    this.styles.borderBottomRightRadius =
+                    this.styles.borderBottomLeftRadius =
+                        RADIO_BORDER_RADIUS;
+                break;
+        }
+    }
+}

package/src/dom/replaced-elements/svg-element-container.ts

@@ -0,0 +1,23 @@
+import { ElementContainer } from '../element-container';
+import { parseBounds } from '../../css/layout/bounds';
+import { Context } from '../../core/context';
+
+export class SVGElementContainer extends ElementContainer {
+    svg: string;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+
+    constructor(context: Context, img: SVGSVGElement) {
+        super(context, img);
+        const s = new XMLSerializer();
+        const bounds = parseBounds(context, img);
+        img.setAttribute('width', `${bounds.width}px`);
+        img.setAttribute('height', `${bounds.height}px`);
+
+        this.svg = `data:image/svg+xml,${encodeURIComponent(s.serializeToString(img))}`;
+        this.intrinsicWidth = img.width.baseVal.value;
+        this.intrinsicHeight = img.height.baseVal.value;
+
+        this.context.cache.addImage(this.svg);
+    }
+}

package/src/dom/text-container.ts

@@ -0,0 +1,42 @@
+import { CSSParsedDeclaration } from '../css/index';
+import { TEXT_TRANSFORM } from '../css/property-descriptors/text-transform';
+import { parseTextBounds, TextBounds } from '../css/layout/text';
+import { Context } from '../core/context';
+
+export class TextContainer {
+    text: string;
+    textBounds: TextBounds[];
+
+    constructor(context: Context, node: Text, styles: CSSParsedDeclaration) {
+        this.text = transform(node.data, styles.textTransform);
+        // Range offsets below are based on transformed text; keep the node in sync
+        // when casing changes string length, for example "ß".toUpperCase() === "SS".
+        if (this.text.length !== node.data.length) {
+            node.data = this.text;
+        }
+        this.textBounds = parseTextBounds(context, this.text, styles, node);
+    }
+}
+
+const transform = (text: string, transform: TEXT_TRANSFORM) => {
+    switch (transform) {
+        case TEXT_TRANSFORM.LOWERCASE:
+            return text.toLowerCase();
+        case TEXT_TRANSFORM.CAPITALIZE:
+            return text.replace(CAPITALIZE, capitalize);
+        case TEXT_TRANSFORM.UPPERCASE:
+            return text.toUpperCase();
+        default:
+            return text;
+    }
+};
+
+const CAPITALIZE = /(^|\s|:|-|\(|\))([a-z])/g;
+
+const capitalize = (m: string, p1: string, p2: string) => {
+    if (m.length > 0) {
+        return p1 + p2.toUpperCase();
+    }
+
+    return m;
+};

package/src/global.d.ts

@@ -0,0 +1,19 @@
+interface CSSStyleDeclaration {
+    textDecorationColor: string;
+    textDecorationLine: string;
+    textDecorationStyle: string;
+    textDecorationThickness: string;
+    textUnderlineOffset: string;
+    overflowWrap: string;
+    rotate: string;
+    webkitLineClamp: string;
+    webkitBoxOrient: string;
+}
+
+interface DocumentType extends Node, ChildNode {
+    readonly internalSubset: string | null;
+}
+
+interface Document {
+    fonts: any;
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { Html2CanvasConfig, ConfigOptions, setDefaultConfig } from './config';
+import { createDefaultValidator, Validator, ValidationResult } from './core/validator';
+import { PerformanceMonitor } from './core/performance-monitor';
+import { renderElement } from './core/render-element';
+import type { Options } from './options';
+
+export type { Options };
+
+/**
+ * Renders an HTML element to a `<canvas>` element.
+ *
+ * The function clones the target element and its subtree into a hidden iframe,
+ * resolves all computed styles, and paints the result onto a canvas —
+ * producing a visual snapshot of the DOM as it appears in the browser.
+ *
+ * @example
+ * ```ts
+ * import html2canvas from 'html2canvas-pro';
+ *
+ * const canvas = await html2canvas(document.body, {
+ *   backgroundColor: '#ffffff',
+ *   scale: 2,
+ *   useCORS: true
+ * });
+ * document.body.appendChild(canvas);
+ * ```
+ *
+ * @param element - The root HTMLElement to render.
+ * @param options - Rendering options.
+ * @param config  - Advanced configuration. In most cases this is auto-created;
+ *                  only pass it if you need to share a cache across multiple calls.
+ * @returns A promise that resolves to the rendered HTMLCanvasElement.
+ *
+ * @throws {Error} If the element is not attached to a document.
+ * @throws {DOMException} If an {@link Options.signal|AbortSignal} was provided and the operation was aborted.
+ */
+const html2canvas = (
+    element: HTMLElement,
+    options: Partial<Options> = {},
+    config?: Html2CanvasConfig
+): Promise<HTMLCanvasElement> => {
+    const finalConfig =
+        config ||
+        Html2CanvasConfig.fromElement(element, {
+            cspNonce: options.cspNonce,
+            cache: options.cache
+        });
+
+    return renderElement(element, options, finalConfig);
+};
+
+/**
+ * Set CSP nonce for inline styles.
+ *
+ * @deprecated Since 2.0.0. Pass `cspNonce` in options instead:
+ *             `html2canvas(element, { cspNonce: '...' })`
+ */
+const setCspNonce = (nonce: string) => {
+    console.warn(
+        '[html2canvas-pro] setCspNonce is deprecated. ' +
+            'Pass cspNonce in options instead: html2canvas(element, { cspNonce: "..." })'
+    );
+
+    if (typeof window !== 'undefined') {
+        setDefaultConfig(new Html2CanvasConfig({ window, cspNonce: nonce }));
+    }
+};
+
+html2canvas.setCspNonce = setCspNonce;
+
+export default html2canvas;
+export {
+    html2canvas,
+    Html2CanvasConfig,
+    ConfigOptions,
+    Validator,
+    ValidationResult,
+    createDefaultValidator,
+    PerformanceMonitor
+};
+
+export { IMAGE_RENDERING } from './css/property-descriptors/image-rendering';

package/src/invariant.ts

@@ -0,0 +1,5 @@
+export const invariant = (assertion: boolean, error: string): void => {
+    if (!assertion) {
+        console.error(error);
+    }
+};

package/src/options.ts

@@ -0,0 +1,55 @@
+import { CloneOptions, WindowOptions } from './dom/document-cloner';
+import { RenderOptions } from './render/canvas/canvas-renderer';
+import { ContextOptions } from './core/context';
+import { Validator } from './core/validator';
+
+/**
+ * Options passed to {@link html2canvas}.
+ *
+ * Combines clone, window, render, and context configuration into a single
+ * options object. All properties are optional.
+ */
+export type Options = CloneOptions &
+    WindowOptions &
+    RenderOptions &
+    ContextOptions & {
+        /** Background color for the resulting canvas. Use `null` for transparent. */
+        backgroundColor: string | null;
+        /** Use foreignObject rendering (SVG-based) instead of the default Canvas 2D pipeline. */
+        foreignObjectRendering: boolean;
+        /** Whether to remove the cloned iframe after rendering. @default true */
+        removeContainer?: boolean;
+        /** CSP nonce for inline style elements. */
+        cspNonce?: string;
+        /** Custom input validator. */
+        validator?: Validator;
+        /** Skip pre-render validation of element and options. */
+        skipValidation?: boolean;
+        /** Enable performance monitoring and log a timing summary. */
+        enablePerformanceMonitoring?: boolean;
+        /**
+         * An AbortSignal that can be used to cancel an in-progress render.
+         * When the signal is aborted, the returned promise rejects with an
+         * `AbortError` DOMException.
+         */
+        signal?: AbortSignal;
+        /**
+         * Enable/disable image smoothing (anti-aliasing) globally.
+         * - `false`: Pixel-perfect rendering for pixel art, sprites, and retro graphics
+         * - `true`: Smooth rendering for photos and high-quality images
+         * - CSS `image-rendering` property on individual elements takes precedence
+         * @default true (browser default)
+         */
+        imageSmoothing?: boolean;
+        /**
+         * Image smoothing quality level when imageSmoothing is enabled.
+         * - `'low'`: Faster, lower quality (good for preview)
+         * - `'medium'`: Balanced (default in most browsers)
+         * - `'high'`: Slower, best quality (good for final export)
+         *
+         * Browser support: Chrome 54+, Firefox 94+, Safari 17+
+         * Falls back gracefully in older browsers.
+         * @default browser default (usually 'low' or 'medium')
+         */
+        imageSmoothingQuality?: 'low' | 'medium' | 'high';
+    };

package/src/render/__tests__/object-fit.test.ts

@@ -0,0 +1,85 @@
+import { deepStrictEqual } from 'assert';
+import { OBJECT_FIT } from '../../css/property-descriptors/object-fit';
+import { calculateObjectFitRendering } from '../object-fit';
+
+describe('calculateObjectFitRendering', () => {
+    const box = { left: 10, top: 20, width: 100, height: 50 };
+
+    it('should preserve fill rendering by default', () => {
+        deepStrictEqual(calculateObjectFitRendering(200, 100, box, OBJECT_FIT.FILL), {
+            sx: 0,
+            sy: 0,
+            sw: 200,
+            sh: 100,
+            dx: 10,
+            dy: 20,
+            dw: 100,
+            dh: 50
+        });
+    });
+
+    it('should calculate contain destination rectangle', () => {
+        deepStrictEqual(calculateObjectFitRendering(100, 100, box, OBJECT_FIT.CONTAIN), {
+            sx: 0,
+            sy: 0,
+            sw: 100,
+            sh: 100,
+            dx: 35,
+            dy: 20,
+            dw: 50,
+            dh: 50
+        });
+    });
+
+    it('should calculate cover source rectangle', () => {
+        deepStrictEqual(calculateObjectFitRendering(100, 100, box, OBJECT_FIT.COVER), {
+            sx: 0,
+            sy: 25,
+            sw: 100,
+            sh: 50,
+            dx: 10,
+            dy: 20,
+            dw: 100,
+            dh: 50
+        });
+    });
+
+    it('should calculate none with centered clipping', () => {
+        deepStrictEqual(calculateObjectFitRendering(200, 100, box, OBJECT_FIT.NONE), {
+            sx: 50,
+            sy: 25,
+            sw: 100,
+            sh: 50,
+            dx: 10,
+            dy: 20,
+            dw: 100,
+            dh: 50
+        });
+    });
+
+    it('should scale down using contain logic when image is larger than box', () => {
+        deepStrictEqual(calculateObjectFitRendering(200, 50, box, OBJECT_FIT.SCALE_DOWN), {
+            sx: 0,
+            sy: 0,
+            sw: 200,
+            sh: 50,
+            dx: 10,
+            dy: 32.5,
+            dw: 100,
+            dh: 25
+        });
+    });
+
+    it('should scale down using none logic when image is smaller than box', () => {
+        deepStrictEqual(calculateObjectFitRendering(60, 30, box, OBJECT_FIT.SCALE_DOWN), {
+            sx: 0,
+            sy: 0,
+            sw: 60,
+            sh: 30,
+            dx: 30,
+            dy: 30,
+            dw: 60,
+            dh: 30
+        });
+    });
+});