html2canvas-pro 2.0.3 → 2.1.0

package/src/dom/dom-normalizer.ts

@@ -0,0 +1,133 @@
+/**
+ * DOM Normalizer
+ * Handles DOM side effects that need to happen before rendering
+ * Extracted from ElementContainer to follow SRP
+ */
+
+import { CSSParsedDeclaration } from '../css';
+import { isHTMLElementNode } from './node-type-guards';
+
+/**
+ * Stored original styles for restoration
+ */
+export interface OriginalStyles {
+    animationDuration?: string;
+    transform?: string;
+    rotate?: string;
+}
+
+/**
+ * Normalize element styles for accurate rendering
+ * This includes disabling animations and neutralizing transforms.
+ */
+export class DOMNormalizer {
+    /**
+     * Normalize a single element and return original styles.
+     *
+     * ## Why we replace transforms with an identity value instead of "none"
+     *
+     * `getBoundingClientRect()` returns visual (post-transform) coordinates, so we
+     * must neutralize any active transform before measuring element bounds.
+     *
+     * The naive approach of setting `transform: none` (or `rotate: none`) has a
+     * critical side-effect: per **CSS Transforms Level 2**, an element whose
+     * `transform` is non-none automatically becomes the **containing block** for
+     * all of its `position: absolute` *and* `position: fixed` descendants.
+     * Setting it to `none` destroys that role, causing children to resolve their
+     * percentage dimensions and offsets against an unintended ancestor — which
+     * produces completely wrong bounds.
+     *
+     * Solution: instead of removing the transform, we replace it with a visually
+     * inert identity value:
+     *
+     * - `transform: scale(0.5)` → `transform: translate(0, 0)`
+     *   - `translate(0, 0)` is an identity transform (no visual change, no layout shift).
+     *   - `getBoundingClientRect()` returns the same layout-space coordinates as
+     *     if there were no transform at all.
+     *   - Because the value is still non-none, the element **remains a containing
+     *     block** for both `position: absolute` and `position: fixed` descendants.
+     *
+     * - `rotate: 45deg` → `rotate: 0deg`
+     *   - `0deg` is the identity rotation; `0deg ≠ none`, so the same containing-
+     *     block guarantee holds.
+     *
+     * @param element - Element to normalize
+     * @param styles - Parsed CSS styles
+     * @returns Original styles map for restoration
+     */
+    static normalizeElement(element: Element, styles: CSSParsedDeclaration): OriginalStyles {
+        const originalStyles: OriginalStyles = {};
+
+        if (!isHTMLElementNode(element)) {
+            return originalStyles;
+        }
+
+        // Disable animations to capture static state
+        if (styles.animationDuration.some((duration) => duration > 0)) {
+            originalStyles.animationDuration = element.style.animationDuration;
+            element.style.animationDuration = '0s';
+        }
+
+        // Replace the actual transform with an identity translate so that:
+        //   1. getBoundingClientRect() returns layout-space (unscaled/unrotated) coords.
+        //   2. The element still satisfies "transform != none" and therefore keeps
+        //      its role as a containing block for position:absolute / position:fixed
+        //      descendants (CSS Transforms Level 2 §2.3).
+        if (styles.transform !== null) {
+            originalStyles.transform = element.style.transform;
+            element.style.transform = 'translate(0, 0)';
+        }
+
+        // Same rationale for the standalone `rotate` property.
+        // `rotate: 0deg` is an identity rotation with no visual effect.
+        //
+        // However, individual transform properties (`rotate`, `translate`, `scale`)
+        // are part of CSS Transforms Level 2 and their containing-block guarantee
+        // is not uniformly implemented across all browsers. To be safe, if `rotate`
+        // is the only transform-like property active on this element, we also set
+        // `transform: translate(0, 0)` so that the containing-block role is reliably
+        // preserved via the well-supported `transform` property.
+        if (styles.rotate !== null) {
+            originalStyles.rotate = element.style.rotate;
+            element.style.rotate = '0deg';
+
+            // Individual transform properties (`rotate`, `translate`, `scale`) are
+            // CSS Transforms Level 2 and their containing-block guarantee is not
+            // uniformly implemented in all browsers. If `transform` was not already
+            // set to translate(0,0) in the block above (i.e. this element has
+            // `rotate` but no `transform`), we set it now so the containing-block
+            // role is reliably established via the widely-supported `transform`
+            // property – independently of browser support for individual props.
+            if (originalStyles.transform === undefined) {
+                originalStyles.transform = element.style.transform;
+                element.style.transform = 'translate(0, 0)';
+            }
+        }
+
+        return originalStyles;
+    }
+
+    /**
+     * Restore element styles after rendering.
+     *
+     * @param element - Element to restore
+     * @param originalStyles - Original styles to restore
+     */
+    static restoreElement(element: Element, originalStyles: OriginalStyles): void {
+        if (!isHTMLElementNode(element)) {
+            return;
+        }
+
+        if (originalStyles.animationDuration !== undefined) {
+            element.style.animationDuration = originalStyles.animationDuration;
+        }
+
+        if (originalStyles.transform !== undefined) {
+            element.style.transform = originalStyles.transform;
+        }
+
+        if (originalStyles.rotate !== undefined) {
+            element.style.rotate = originalStyles.rotate;
+        }
+    }
+}

package/src/dom/element-container.ts

@@ -0,0 +1,75 @@
+import { CSSParsedDeclaration } from '../css/index';
+import { TextContainer } from './text-container';
+import { Bounds, parseBounds } from '../css/layout/bounds';
+import { isHTMLElementNode } from './node-type-guards';
+import { Context } from '../core/context';
+import { DebuggerType, isDebugging } from '../core/debugger';
+import { DOMNormalizer, OriginalStyles } from './dom-normalizer';
+
+export interface ElementContainerOptions {
+    normalizeDom?: boolean;
+}
+
+export class ElementContainer {
+    readonly styles: CSSParsedDeclaration;
+    readonly textNodes: TextContainer[] = [];
+    readonly elements: ElementContainer[] = [];
+    bounds: Bounds;
+
+    createsStackingContext = false;
+    createsRealStackingContext = false;
+    isListOwner = false;
+    debugRender = false;
+
+    private originalStyles?: OriginalStyles;
+    private originalElement?: Element;
+
+    constructor(
+        protected readonly context: Context,
+        element: Element,
+        options: ElementContainerOptions = {}
+    ) {
+        if (isDebugging(element, DebuggerType.PARSE)) {
+            debugger;
+        }
+
+        this.styles = new CSSParsedDeclaration(context, context.config.window.getComputedStyle(element, null));
+
+        const shouldNormalize = options.normalizeDom !== false;
+        if (shouldNormalize && isHTMLElementNode(element)) {
+            this.originalStyles = DOMNormalizer.normalizeElement(element, this.styles);
+            this.originalElement = element;
+        }
+
+        this.bounds = parseBounds(this.context, element);
+
+        if (isDebugging(element, DebuggerType.RENDER)) {
+            this.debugRender = true;
+        }
+    }
+
+    /**
+     * Restore original element styles (if normalized)
+     * Call this after rendering is complete to clean up DOM state
+     */
+    restore(): void {
+        if (this.originalStyles && this.originalElement) {
+            DOMNormalizer.restoreElement(this.originalElement, this.originalStyles);
+            // Clear references to prevent memory leaks
+            this.originalStyles = undefined;
+            this.originalElement = undefined;
+        }
+    }
+
+    /**
+     * Recursively restore all elements in the tree
+     * Call this on the root container after rendering is complete
+     */
+    restoreTree(): void {
+        this.restore();
+        // Recursively restore all child elements
+        for (const child of this.elements) {
+            child.restoreTree();
+        }
+    }
+}

package/src/dom/elements/li-element-container.ts

@@ -0,0 +1,10 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+export class LIElementContainer extends ElementContainer {
+    readonly value: number;
+
+    constructor(context: Context, element: HTMLLIElement) {
+        super(context, element);
+        this.value = element.value;
+    }
+}

package/src/dom/elements/ol-element-container.ts

@@ -0,0 +1,12 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+export class OLElementContainer extends ElementContainer {
+    readonly start: number;
+    readonly reversed: boolean;
+
+    constructor(context: Context, element: HTMLOListElement) {
+        super(context, element);
+        this.start = element.start;
+        this.reversed = typeof element.reversed === 'boolean' && element.reversed === true;
+    }
+}

package/src/dom/elements/select-element-container.ts

@@ -0,0 +1,10 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+export class SelectElementContainer extends ElementContainer {
+    readonly value: string;
+    constructor(context: Context, element: HTMLSelectElement) {
+        super(context, element);
+        const option = element.options[element.selectedIndex || 0];
+        this.value = option ? option.text || '' : '';
+    }
+}

package/src/dom/elements/textarea-element-container.ts

@@ -0,0 +1,9 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+export class TextareaElementContainer extends ElementContainer {
+    readonly value: string;
+    constructor(context: Context, element: HTMLTextAreaElement) {
+        super(context, element);
+        this.value = element.value;
+    }
+}

package/src/dom/node-parser.ts

@@ -0,0 +1,177 @@
+import { CSSParsedDeclaration } from '../css';
+import { ElementContainer } from './element-container';
+import { TextContainer } from './text-container';
+import { ImageElementContainer } from './replaced-elements/image-element-container';
+import { CanvasElementContainer } from './replaced-elements/canvas-element-container';
+import { SVGElementContainer } from './replaced-elements/svg-element-container';
+import { LIElementContainer } from './elements/li-element-container';
+import { OLElementContainer } from './elements/ol-element-container';
+import { InputElementContainer } from './replaced-elements/input-element-container';
+import { SelectElementContainer } from './elements/select-element-container';
+import { TextareaElementContainer } from './elements/textarea-element-container';
+import { IFrameElementContainer } from './replaced-elements/iframe-element-container';
+import { Context } from '../core/context';
+import {
+    isBodyElement,
+    isCanvasElement,
+    isCustomElement,
+    isElementNode,
+    isHTMLElement,
+    isHTMLElementNode,
+    isIFrameElement,
+    isImageElement,
+    isInputElement,
+    isLIElement,
+    isOLElement,
+    isScriptElement,
+    isSelectElement,
+    isSlotElement,
+    isStyleElement,
+    isSVGElement,
+    isSVGElementNode,
+    isTextareaElement,
+    isTextNode,
+    isVideoElement
+} from './node-type-guards';
+
+// Re-export all type guards for backward compatibility
+export {
+    isBodyElement,
+    isCanvasElement,
+    isCustomElement,
+    isElementNode,
+    isHTMLElement,
+    isHTMLElementNode,
+    isIFrameElement,
+    isImageElement,
+    isInputElement,
+    isLIElement,
+    isOLElement,
+    isScriptElement,
+    isSelectElement,
+    isSlotElement,
+    isStyleElement,
+    isSVGElement,
+    isSVGElementNode,
+    isTextareaElement,
+    isTextNode,
+    isVideoElement
+};
+import { contains } from '../core/bitwise';
+import { DISPLAY } from '../css/property-descriptors/display';
+
+const LIST_OWNERS = ['OL', 'UL', 'MENU'];
+
+const parseNodeTree = (context: Context, node: Node, parent: ElementContainer, root: ElementContainer) => {
+    for (let childNode = node.firstChild, nextNode; childNode; childNode = nextNode) {
+        nextNode = childNode.nextSibling;
+
+        // Fixes #2238 #1624 - Fix the issue of TextNode content being overlooked in rendering due to being perceived as blank by trim().
+        if (isTextNode(childNode) && childNode.data.length > 0) {
+            parent.textNodes.push(new TextContainer(context, childNode, parent.styles));
+        } else if (isElementNode(childNode)) {
+            if (isSlotElement(childNode) && childNode.assignedNodes) {
+                childNode
+                    .assignedNodes()
+                    .forEach((assignedNode: Node) => parseNodeTree(context, assignedNode, parent, root));
+            } else {
+                const container = createContainer(context, childNode);
+                if (container.styles.isVisible()) {
+                    if (createsRealStackingContext(childNode, container, root)) {
+                        container.createsRealStackingContext = true;
+                    } else if (createsStackingContext(container.styles)) {
+                        container.createsStackingContext = true;
+                    }
+
+                    if (LIST_OWNERS.indexOf(childNode.tagName) !== -1) {
+                        container.isListOwner = true;
+                    }
+
+                    parent.elements.push(container);
+                    if (childNode.shadowRoot) {
+                        parseNodeTree(context, childNode.shadowRoot, container, root);
+                    } else if (
+                        !isTextareaElement(childNode) &&
+                        !isSVGElement(childNode) &&
+                        !isSelectElement(childNode)
+                    ) {
+                        parseNodeTree(context, childNode, container, root);
+                    }
+                }
+            }
+        }
+    }
+};
+
+const createContainer = (context: Context, element: Element): ElementContainer => {
+    if (isImageElement(element)) {
+        return new ImageElementContainer(context, element);
+    }
+
+    if (isCanvasElement(element)) {
+        return new CanvasElementContainer(context, element);
+    }
+
+    if (isSVGElement(element)) {
+        return new SVGElementContainer(context, element);
+    }
+
+    if (isLIElement(element)) {
+        return new LIElementContainer(context, element);
+    }
+
+    if (isOLElement(element)) {
+        return new OLElementContainer(context, element);
+    }
+
+    if (isInputElement(element)) {
+        return new InputElementContainer(context, element);
+    }
+
+    if (isSelectElement(element)) {
+        return new SelectElementContainer(context, element);
+    }
+
+    if (isTextareaElement(element)) {
+        return new TextareaElementContainer(context, element);
+    }
+
+    if (isIFrameElement(element)) {
+        return new IFrameElementContainer(context, element, parseTree);
+    }
+
+    return new ElementContainer(context, element);
+};
+
+export const parseTree = (context: Context, element: HTMLElement): ElementContainer => {
+    const container = createContainer(context, element);
+    container.createsRealStackingContext = true;
+    parseNodeTree(context, element, container, container);
+    return container;
+};
+
+const createsRealStackingContext = (node: Element, container: ElementContainer, root: ElementContainer): boolean => {
+    return (
+        container.styles.isPositionedWithZIndex() ||
+        container.styles.opacity < 1 ||
+        container.styles.isTransformed() ||
+        (isBodyElement(node) && root.styles.isTransparent())
+    );
+};
+
+const createsStackingContext = (styles: CSSParsedDeclaration): boolean => {
+    // Positioned and floating elements create stacking contexts
+    if (styles.isPositioned() || styles.isFloating()) {
+        return true;
+    }
+
+    // Fix for Issue #137: Inline-level containers (inline-flex, inline-block, etc.)
+    // should create stacking contexts to prevent their children from being added
+    // to the parent's stacking context, which causes rendering order issues
+    return (
+        contains(styles.display, DISPLAY.INLINE_FLEX) ||
+        contains(styles.display, DISPLAY.INLINE_BLOCK) ||
+        contains(styles.display, DISPLAY.INLINE_GRID) ||
+        contains(styles.display, DISPLAY.INLINE_TABLE)
+    );
+};

package/src/dom/node-type-guards.ts

@@ -0,0 +1,70 @@
+/**
+ * DOM Node Type Guards
+ *
+ * All DOM node type guards consolidated here to eliminate duplication
+ * and provide a single source of truth for node type checking.
+ */
+
+// --- Generic node type guards ---
+
+export const isElementNode = (node: Node): node is Element => node.nodeType === Node.ELEMENT_NODE;
+export const isTextNode = (node: Node): node is Text => node.nodeType === Node.TEXT_NODE;
+
+export const isSVGElementNode = (element: Element): element is SVGElement =>
+    typeof (element as SVGElement).className === 'object';
+
+export const isHTMLElementNode = (node: Node): node is HTMLElement =>
+    isElementNode(node) && typeof (node as HTMLElement).style !== 'undefined' && !isSVGElementNode(node);
+
+// --- Tag name based type guards ---
+
+export const isInputElement = (node: Element): node is HTMLInputElement => node.tagName === 'INPUT';
+export const isHTMLElement = (node: Element): node is HTMLHtmlElement => node.tagName === 'HTML';
+export const isSVGElement = (node: Element): node is SVGSVGElement => node.tagName === 'svg';
+export const isBodyElement = (node: Element): node is HTMLBodyElement => node.tagName === 'BODY';
+export const isCanvasElement = (node: Element): node is HTMLCanvasElement => node.tagName === 'CANVAS';
+export const isVideoElement = (node: Element): node is HTMLVideoElement => node.tagName === 'VIDEO';
+export const isImageElement = (node: Element): node is HTMLImageElement => node.tagName === 'IMG';
+export const isIFrameElement = (node: Element): node is HTMLIFrameElement => node.tagName === 'IFRAME';
+export const isStyleElement = (node: Element): node is HTMLStyleElement => node.tagName === 'STYLE';
+export const isScriptElement = (node: Element): node is HTMLScriptElement => node.tagName === 'SCRIPT';
+export const isTextareaElement = (node: Element): node is HTMLTextAreaElement => node.tagName === 'TEXTAREA';
+export const isSelectElement = (node: Element): node is HTMLSelectElement => node.tagName === 'SELECT';
+export const isSlotElement = (node: Element): node is HTMLSlotElement => node.tagName === 'SLOT';
+export const isLIElement = (node: Element): node is HTMLLIElement => node.tagName === 'LI';
+export const isOLElement = (node: Element): node is HTMLOListElement => node.tagName === 'OL';
+
+export const isCustomElement = (element: Element): element is HTMLElement =>
+    !isSVGElementNode(element) && element.tagName.indexOf('-') > 0;
+
+const VOID_OR_REPLACED_TAGS = new Set([
+    'IMG',
+    'VIDEO',
+    'AUDIO',
+    'CANVAS',
+    'IFRAME',
+    'INPUT',
+    'TEXTAREA',
+    'SELECT',
+    'BR',
+    'HR',
+    'META',
+    'LINK',
+    'BASE',
+    'COL',
+    'SOURCE',
+    'TRACK',
+    'WBR',
+    'AREA',
+    'PARAM',
+    'EMBED',
+    'OBJECT'
+]);
+
+/**
+ * Check if an element can have ::before / ::after pseudo-elements.
+ * Per the CSS spec, replaced elements and void elements cannot have pseudo-elements.
+ * SVG elements also do not support pseudo-elements.
+ */
+export const canHavePseudoElements = (element: Element): boolean =>
+    !isSVGElementNode(element) && !VOID_OR_REPLACED_TAGS.has(element.tagName);

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

@@ -0,0 +1,15 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+
+export class CanvasElementContainer extends ElementContainer {
+    canvas: HTMLCanvasElement;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+
+    constructor(context: Context, canvas: HTMLCanvasElement) {
+        super(context, canvas);
+        this.canvas = canvas;
+        this.intrinsicWidth = canvas.width;
+        this.intrinsicHeight = canvas.height;
+    }
+}

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

@@ -0,0 +1,55 @@
+import { ElementContainer } from '../element-container';
+import { Color, parseColor, COLORS } from '../../css/types/color';
+import { isTransparent } from '../../css/types/color-utilities';
+import { Context } from '../../core/context';
+
+// Parser function type to break circular dependency
+type ParseTreeFunction = (context: Context, node: Node) => ElementContainer;
+
+export class IFrameElementContainer extends ElementContainer {
+    src: string;
+    width: number;
+    height: number;
+    tree?: ElementContainer;
+    backgroundColor: Color;
+    private parseTreeFn?: ParseTreeFunction;
+
+    constructor(context: Context, iframe: HTMLIFrameElement, parseTreeFn?: ParseTreeFunction) {
+        super(context, iframe);
+        this.src = iframe.src;
+        this.width = parseInt(iframe.width, 10) || 0;
+        this.height = parseInt(iframe.height, 10) || 0;
+        this.backgroundColor = this.styles.backgroundColor;
+        this.parseTreeFn = parseTreeFn;
+        try {
+            if (
+                iframe.contentWindow &&
+                iframe.contentWindow.document &&
+                iframe.contentWindow.document.documentElement &&
+                this.parseTreeFn
+            ) {
+                this.tree = this.parseTreeFn(context, iframe.contentWindow.document.documentElement);
+
+                // http://www.w3.org/TR/css3-background/#special-backgrounds
+                const documentBackgroundColor = iframe.contentWindow.document.documentElement
+                    ? parseColor(
+                          context,
+                          getComputedStyle(iframe.contentWindow.document.documentElement).backgroundColor as string
+                      )
+                    : COLORS.TRANSPARENT;
+                const bodyBackgroundColor = iframe.contentWindow.document.body
+                    ? parseColor(
+                          context,
+                          getComputedStyle(iframe.contentWindow.document.body).backgroundColor as string
+                      )
+                    : COLORS.TRANSPARENT;
+
+                this.backgroundColor = isTransparent(documentBackgroundColor)
+                    ? isTransparent(bodyBackgroundColor)
+                        ? this.styles.backgroundColor
+                        : bodyBackgroundColor
+                    : documentBackgroundColor;
+            }
+        } catch (e) {}
+    }
+}

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

@@ -0,0 +1,16 @@
+import { ElementContainer } from '../element-container';
+import { Context } from '../../core/context';
+
+export class ImageElementContainer extends ElementContainer {
+    src: string;
+    intrinsicWidth: number;
+    intrinsicHeight: number;
+
+    constructor(context: Context, img: HTMLImageElement) {
+        super(context, img);
+        this.src = img.currentSrc || img.src;
+        this.intrinsicWidth = img.naturalWidth;
+        this.intrinsicHeight = img.naturalHeight;
+        this.context.cache.addImage(this.src);
+    }
+}

package/src/dom/replaced-elements/index.ts

@@ -0,0 +1,5 @@
+import { CanvasElementContainer } from './canvas-element-container';
+import { ImageElementContainer } from './image-element-container';
+import { SVGElementContainer } from './svg-element-container';
+
+export type ReplacedElementContainer = CanvasElementContainer | ImageElementContainer | SVGElementContainer;