html2canvas-pro 2.0.3 → 2.1.0

package/src/render/canvas/background-renderer.ts

@@ -0,0 +1,271 @@
+/**
+ * Background Renderer
+ *
+ * Handles rendering of element backgrounds including:
+ * - Background colors
+ * - Background images (URL)
+ * - Linear gradients
+ * - Radial gradients
+ * - Background patterns and repeats
+ */
+
+import { Context } from '../../core/context';
+import { ElementContainer } from '../../dom/element-container';
+import { Path } from '../path';
+import {
+    CSSImageType,
+    CSSLinearGradientImage,
+    CSSRadialGradientImage,
+    CSSURLImage,
+    isLinearGradient,
+    isRadialGradient
+} from '../../css/types/image';
+import { calculateBackgroundRendering } from '../background';
+import { calculateGradientDirection, calculateRadius, processColorStops } from '../../css/types/functions/gradient';
+import { FIFTY_PERCENT, getAbsoluteValue } from '../../css/types/length-percentage';
+import { asString } from '../../css/types/color-utilities';
+import { IMAGE_RENDERING } from '../../css/property-descriptors/image-rendering';
+import { createCanvasPath } from './canvas-path';
+
+/**
+ * Dependencies required for BackgroundRenderer
+ */
+export interface BackgroundRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    context: Context;
+    canvas: HTMLCanvasElement;
+    options: {
+        width: number;
+        height: number;
+        scale: number;
+    };
+}
+
+/**
+ * Background Renderer
+ *
+ * Specialized renderer for element backgrounds.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export class BackgroundRenderer {
+    private readonly ctx: CanvasRenderingContext2D;
+    private readonly context: Context;
+    private readonly canvas: HTMLCanvasElement;
+
+    constructor(deps: BackgroundRendererDependencies) {
+        this.ctx = deps.ctx;
+        this.context = deps.context;
+        this.canvas = deps.canvas;
+        // Options stored in deps but not needed as instance property
+    }
+
+    /**
+     * Render background images for a container
+     * Supports URL images, linear gradients, and radial gradients
+     *
+     * @param container - Element container with background styles
+     */
+    async renderBackgroundImage(container: ElementContainer): Promise<void> {
+        let index = container.styles.backgroundImage.length - 1;
+        for (const backgroundImage of container.styles.backgroundImage.slice(0).reverse()) {
+            if (backgroundImage.type === CSSImageType.URL) {
+                await this.renderBackgroundURLImage(container, backgroundImage as CSSURLImage, index);
+            } else if (isLinearGradient(backgroundImage)) {
+                this.renderLinearGradient(container, backgroundImage, index);
+            } else if (isRadialGradient(backgroundImage)) {
+                this.renderRadialGradient(container, backgroundImage, index);
+            }
+            index--;
+        }
+    }
+
+    /**
+     * Render a URL-based background image
+     */
+    private async renderBackgroundURLImage(
+        container: ElementContainer,
+        backgroundImage: CSSURLImage,
+        index: number
+    ): Promise<void> {
+        let image;
+        const url = backgroundImage.url;
+        try {
+            image = await this.context.cache.match(url);
+        } catch (e) {
+            this.context.logger.error(`Error loading background-image ${url}`);
+        }
+
+        if (image) {
+            const imageWidth = isNaN(image.width) || image.width === 0 ? 1 : image.width;
+            const imageHeight = isNaN(image.height) || image.height === 0 ? 1 : image.height;
+            const [path, x, y, width, height] = calculateBackgroundRendering(container, index, [
+                imageWidth,
+                imageHeight,
+                imageWidth / imageHeight
+            ]);
+            const pattern = this.ctx.createPattern(
+                this.resizeImage(image as HTMLImageElement, width, height, container.styles.imageRendering),
+                'repeat'
+            ) as CanvasPattern;
+            this.renderRepeat(path, pattern, x, y);
+        }
+    }
+
+    /**
+     * Render a linear gradient background
+     */
+    private renderLinearGradient(
+        container: ElementContainer,
+        backgroundImage: CSSLinearGradientImage,
+        index: number
+    ): void {
+        const [path, x, y, width, height] = calculateBackgroundRendering(container, index, [null, null, null]);
+        const [lineLength, x0, x1, y0, y1] = calculateGradientDirection(backgroundImage.angle, width, height);
+
+        const ownerDocument = this.canvas.ownerDocument ?? document;
+        const canvas = ownerDocument.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
+        const gradient = ctx.createLinearGradient(x0, y0, x1, y1);
+
+        processColorStops(backgroundImage.stops, lineLength || 1).forEach((colorStop) =>
+            gradient.addColorStop(colorStop.stop, asString(colorStop.color))
+        );
+
+        ctx.fillStyle = gradient;
+        ctx.fillRect(0, 0, width, height);
+        if (width > 0 && height > 0) {
+            const pattern = this.ctx.createPattern(canvas, 'repeat') as CanvasPattern;
+            this.renderRepeat(path, pattern, x, y);
+        }
+    }
+
+    /**
+     * Render a radial gradient background
+     */
+    private renderRadialGradient(
+        container: ElementContainer,
+        backgroundImage: CSSRadialGradientImage,
+        index: number
+    ): void {
+        const [path, left, top, width, height] = calculateBackgroundRendering(container, index, [null, null, null]);
+        const position = backgroundImage.position.length === 0 ? [FIFTY_PERCENT] : backgroundImage.position;
+        const x = getAbsoluteValue(position[0], width);
+        const y = getAbsoluteValue(position[position.length - 1], height);
+
+        let [rx, ry] = calculateRadius(backgroundImage, x, y, width, height);
+        // Handle edge case where radial gradient size is 0
+        // Use a minimum value of 0.01 to ensure gradient is still rendered
+        if (rx === 0 || ry === 0) {
+            rx = Math.max(rx, 0.01);
+            ry = Math.max(ry, 0.01);
+        }
+        if (rx > 0 && ry > 0) {
+            const radialGradient = this.ctx.createRadialGradient(left + x, top + y, 0, left + x, top + y, rx);
+
+            processColorStops(backgroundImage.stops, rx * 2).forEach((colorStop) =>
+                radialGradient.addColorStop(colorStop.stop, asString(colorStop.color))
+            );
+
+            this.path(path);
+            this.ctx.fillStyle = radialGradient;
+            if (rx !== ry) {
+                // transforms for elliptical radial gradient
+                const midX = container.bounds.left + 0.5 * container.bounds.width;
+                const midY = container.bounds.top + 0.5 * container.bounds.height;
+                const f = ry / rx;
+                const invF = 1 / f;
+
+                this.ctx.save();
+                this.ctx.translate(midX, midY);
+                this.ctx.transform(1, 0, 0, f, 0, 0);
+                this.ctx.translate(-midX, -midY);
+
+                this.ctx.fillRect(left, invF * (top - midY) + midY, width, height * invF);
+                this.ctx.restore();
+            } else {
+                this.ctx.fill();
+            }
+        }
+    }
+
+    /**
+     * Render a repeating pattern with offset
+     *
+     * @param path - Path to fill
+     * @param pattern - Canvas pattern or gradient
+     * @param offsetX - X offset for pattern
+     * @param offsetY - Y offset for pattern
+     */
+    private renderRepeat(
+        path: Path[],
+        pattern: CanvasPattern | CanvasGradient,
+        offsetX: number,
+        offsetY: number
+    ): void {
+        this.path(path);
+        this.ctx.fillStyle = pattern;
+        this.ctx.translate(offsetX, offsetY);
+        this.ctx.fill();
+        this.ctx.translate(-offsetX, -offsetY);
+    }
+
+    /**
+     * Resize an image to target dimensions
+     *
+     * @param image - Source image
+     * @param width - Target width
+     * @param height - Target height
+     * @param imageRendering - CSS image-rendering property value
+     * @returns Resized canvas or original image
+     */
+    private resizeImage(
+        image: HTMLImageElement,
+        width: number,
+        height: number,
+        imageRendering: IMAGE_RENDERING
+    ): HTMLCanvasElement | HTMLImageElement {
+        // https://github.com/niklasvh/html2canvas/pull/2911
+        // if (image.width === width && image.height === height) {
+        //     return image;
+        // }
+
+        const ownerDocument = this.canvas.ownerDocument ?? document;
+        const canvas = ownerDocument.createElement('canvas');
+        canvas.width = Math.max(1, width);
+        canvas.height = Math.max(1, height);
+        const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
+
+        // Apply image smoothing based on CSS image-rendering property
+        if (imageRendering === IMAGE_RENDERING.PIXELATED || imageRendering === IMAGE_RENDERING.CRISP_EDGES) {
+            this.context.logger.debug(`Disabling image smoothing for background image due to CSS image-rendering`);
+            ctx.imageSmoothingEnabled = false;
+        } else if (imageRendering === IMAGE_RENDERING.SMOOTH) {
+            this.context.logger.debug(
+                `Enabling image smoothing for background image due to CSS image-rendering: smooth`
+            );
+            ctx.imageSmoothingEnabled = true;
+        } else {
+            // AUTO: inherit from main renderer context
+            ctx.imageSmoothingEnabled = this.ctx.imageSmoothingEnabled;
+        }
+
+        // Inherit quality setting
+        if (this.ctx.imageSmoothingQuality) {
+            ctx.imageSmoothingQuality = this.ctx.imageSmoothingQuality;
+        }
+
+        ctx.drawImage(image, 0, 0, image.width, image.height, 0, 0, width, height);
+        return canvas;
+    }
+
+    /**
+     * Create a canvas path from path array
+     *
+     * @param paths - Array of path points
+     */
+    private path(paths: Path[]): void {
+        createCanvasPath(this.ctx, paths);
+    }
+}

package/src/render/canvas/border-renderer.ts

@@ -0,0 +1,224 @@
+/**
+ * Border Renderer
+ *
+ * Handles rendering of element borders including:
+ * - Solid borders
+ * - Double borders
+ * - Dashed borders
+ * - Dotted borders
+ */
+
+import { Color } from '../../css/types/color';
+import { asString } from '../../css/types/color-utilities';
+import { BoundCurves } from '../bound-curves';
+import { BORDER_STYLE } from '../../css/property-descriptors/border-style';
+import {
+    parsePathForBorder,
+    parsePathForBorderDoubleInner,
+    parsePathForBorderDoubleOuter,
+    parsePathForBorderStroke
+} from '../border';
+import { isBezierCurve, BezierCurve } from '../bezier-curve';
+import { Vector } from '../vector';
+import { Path } from '../path';
+
+/**
+ * Dependencies required for BorderRenderer
+ */
+export interface BorderRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+}
+
+/**
+ * Path creation callbacks
+ * The main CanvasRenderer retains path() and formatPath() methods,
+ * so we inject them as callbacks to avoid duplication
+ */
+export interface PathCallbacks {
+    path(paths: Path[]): void;
+    formatPath(paths: Path[]): void;
+}
+
+/**
+ * Border Renderer
+ *
+ * Specialized renderer for element borders.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export class BorderRenderer {
+    private readonly ctx: CanvasRenderingContext2D;
+    private pathCallbacks: PathCallbacks;
+
+    constructor(deps: BorderRendererDependencies, pathCallbacks: PathCallbacks) {
+        this.ctx = deps.ctx;
+        this.pathCallbacks = pathCallbacks;
+    }
+
+    /**
+     * Render a solid border
+     *
+     * @param color - Border color
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     */
+    async renderSolidBorder(color: Color, side: number, curvePoints: BoundCurves): Promise<void> {
+        this.pathCallbacks.path(parsePathForBorder(curvePoints, side));
+        this.ctx.fillStyle = asString(color);
+        this.ctx.fill();
+    }
+
+    /**
+     * Render a double border
+     * Falls back to solid border if width is too small
+     *
+     * @param color - Border color
+     * @param width - Border width
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     */
+    async renderDoubleBorder(color: Color, width: number, side: number, curvePoints: BoundCurves): Promise<void> {
+        if (width < 3) {
+            await this.renderSolidBorder(color, side, curvePoints);
+            return;
+        }
+
+        const outerPaths = parsePathForBorderDoubleOuter(curvePoints, side);
+        this.pathCallbacks.path(outerPaths);
+        this.ctx.fillStyle = asString(color);
+        this.ctx.fill();
+        const innerPaths = parsePathForBorderDoubleInner(curvePoints, side);
+        this.pathCallbacks.path(innerPaths);
+        this.ctx.fill();
+    }
+
+    /**
+     * Render a dashed or dotted border
+     *
+     * @param color - Border color
+     * @param width - Border width
+     * @param side - Border side (0=top, 1=right, 2=bottom, 3=left)
+     * @param curvePoints - Border curve points
+     * @param style - Border style (DASHED or DOTTED)
+     */
+    async renderDashedDottedBorder(
+        color: Color,
+        width: number,
+        side: number,
+        curvePoints: BoundCurves,
+        style: BORDER_STYLE
+    ): Promise<void> {
+        this.ctx.save();
+
+        const strokePaths = parsePathForBorderStroke(curvePoints, side);
+        const boxPaths = parsePathForBorder(curvePoints, side);
+
+        if (style === BORDER_STYLE.DASHED) {
+            this.pathCallbacks.path(boxPaths);
+            this.ctx.clip();
+        }
+
+        // Extract start and end coordinates
+        let startX, startY, endX, endY;
+        if (isBezierCurve(boxPaths[0])) {
+            startX = (boxPaths[0] as BezierCurve).start.x;
+            startY = (boxPaths[0] as BezierCurve).start.y;
+        } else {
+            startX = (boxPaths[0] as Vector).x;
+            startY = (boxPaths[0] as Vector).y;
+        }
+        if (isBezierCurve(boxPaths[1])) {
+            endX = (boxPaths[1] as BezierCurve).end.x;
+            endY = (boxPaths[1] as BezierCurve).end.y;
+        } else {
+            endX = (boxPaths[1] as Vector).x;
+            endY = (boxPaths[1] as Vector).y;
+        }
+
+        // Calculate border length
+        let length;
+        if (side === 0 || side === 2) {
+            length = Math.abs(startX - endX);
+        } else {
+            length = Math.abs(startY - endY);
+        }
+
+        this.ctx.beginPath();
+        if (style === BORDER_STYLE.DOTTED) {
+            this.pathCallbacks.formatPath(strokePaths);
+        } else {
+            this.pathCallbacks.formatPath(boxPaths.slice(0, 2));
+        }
+
+        // Calculate dash and space lengths
+        let dashLength = width < 3 ? width * 3 : width * 2;
+        let spaceLength = width < 3 ? width * 2 : width;
+        if (style === BORDER_STYLE.DOTTED) {
+            dashLength = width;
+            spaceLength = width;
+        }
+
+        // Adjust dash pattern for border length
+        let useLineDash = true;
+        if (length <= dashLength * 2) {
+            useLineDash = false;
+        } else if (length <= dashLength * 2 + spaceLength) {
+            const multiplier = length / (2 * dashLength + spaceLength);
+            dashLength *= multiplier;
+            spaceLength *= multiplier;
+        } else {
+            const numberOfDashes = Math.floor((length + spaceLength) / (dashLength + spaceLength));
+            const minSpace = (length - numberOfDashes * dashLength) / (numberOfDashes - 1);
+            const maxSpace = (length - (numberOfDashes + 1) * dashLength) / numberOfDashes;
+            spaceLength =
+                maxSpace <= 0 || Math.abs(spaceLength - minSpace) < Math.abs(spaceLength - maxSpace)
+                    ? minSpace
+                    : maxSpace;
+        }
+
+        // Apply line dash pattern
+        if (useLineDash) {
+            if (style === BORDER_STYLE.DOTTED) {
+                this.ctx.setLineDash([0, dashLength + spaceLength]);
+            } else {
+                this.ctx.setLineDash([dashLength, spaceLength]);
+            }
+        }
+
+        // Set line style and stroke
+        if (style === BORDER_STYLE.DOTTED) {
+            this.ctx.lineCap = 'round';
+            this.ctx.lineWidth = width;
+        } else {
+            this.ctx.lineWidth = width * 2 + 1.1;
+        }
+        this.ctx.strokeStyle = asString(color);
+        this.ctx.stroke();
+        this.ctx.setLineDash([]);
+
+        // Fill dashed round edge gaps
+        if (style === BORDER_STYLE.DASHED) {
+            if (isBezierCurve(boxPaths[0])) {
+                const path1 = boxPaths[3] as BezierCurve;
+                const path2 = boxPaths[0] as BezierCurve;
+                this.ctx.beginPath();
+                this.pathCallbacks.formatPath([
+                    new Vector(path1.end.x, path1.end.y),
+                    new Vector(path2.start.x, path2.start.y)
+                ]);
+                this.ctx.stroke();
+            }
+            if (isBezierCurve(boxPaths[1])) {
+                const path1 = boxPaths[1] as BezierCurve;
+                const path2 = boxPaths[2] as BezierCurve;
+                this.ctx.beginPath();
+                this.pathCallbacks.formatPath([
+                    new Vector(path1.end.x, path1.end.y),
+                    new Vector(path2.start.x, path2.start.y)
+                ]);
+                this.ctx.stroke();
+            }
+        }
+
+        this.ctx.restore();
+    }
+}

package/src/render/canvas/canvas-path.ts

@@ -0,0 +1,31 @@
+import { isBezierCurve } from '../bezier-curve';
+import { Path } from '../path';
+import { Vector } from '../vector';
+
+export const formatCanvasPath = (ctx: CanvasRenderingContext2D, paths: Path[]): void => {
+    paths.forEach((point, index) => {
+        const start: Vector = isBezierCurve(point) ? point.start : point;
+        if (index === 0) {
+            ctx.moveTo(start.x, start.y);
+        } else {
+            ctx.lineTo(start.x, start.y);
+        }
+
+        if (isBezierCurve(point)) {
+            ctx.bezierCurveTo(
+                point.startControl.x,
+                point.startControl.y,
+                point.endControl.x,
+                point.endControl.y,
+                point.end.x,
+                point.end.y
+            );
+        }
+    });
+};
+
+export const createCanvasPath = (ctx: CanvasRenderingContext2D, paths: Path[]): void => {
+    ctx.beginPath();
+    formatCanvasPath(ctx, paths);
+    ctx.closePath();
+};