html2canvas-pro 2.3.2 → 2.3.4

package/dist/html2canvas-pro.js

@@ -1,5 +1,5 @@
 /*!
-* html2canvas-pro 2.3.2 <https://yorickshan.github.io/html2canvas-pro/>
+* html2canvas-pro 2.3.4 <https://yorickshan.github.io/html2canvas-pro/>
 * Copyright (c) 2024-present yorickshan and html2canvas-pro contributors
 * Released under MIT License
 */
@@ -1734,9 +1734,10 @@
 		let arg = [];
 		tokens.forEach((token) => {
 			if (token.type === 4) {
-				if (arg.length === 0) throw new Error(`Error parsing function args, zero tokens for arg`);
-				args.push(arg);
-				arg = [];
+				if (arg.length) {
+					args.push(arg);
+					arg = [];
+				}
 				return;
 			}
 			if (token.type !== 31) arg.push(token);
@@ -3962,6 +3963,7 @@
 				if (isIdentToken(token)) switch (token.value) {
 					case "padding-box": return 1;
 					case "content-box": return 2;
+					case "text": return 3;
 				}
 				return 0;
 			});
@@ -6734,7 +6736,8 @@
 	};
 	const parseCache = /* @__PURE__ */ new Map();
 	const parse = (context, descriptor, style) => {
-		const rawValue = style !== null && typeof style !== "undefined" ? style.toString() : descriptor.initialValue;
+		let rawValue = style !== null && typeof style !== "undefined" ? style.toString() : descriptor.initialValue;
+		if (rawValue.trim() === "") rawValue = descriptor.initialValue;
 		let valueCache = parseCache.get(descriptor);
 		if (valueCache) {
 			const cached = valueCache.get(rawValue);
@@ -10528,6 +10531,7 @@
 			this.effectsRenderer.applyEffects(paint.getEffects(2));
 			const styles = paint.container.styles;
 			const hasBackground = !isTransparent(styles.backgroundColor) || styles.backgroundImage.length;
+			const hasTextClip = hasTextBackgroundClip(styles);
 			const borders = [
 				{
 					style: styles.borderTopStyle,
@@ -10550,17 +10554,21 @@
 					width: styles.borderLeftWidth
 				}
 			];
-			const backgroundPaintingArea = calculateBackgroundCurvedPaintingArea(getBackgroundValueForIndex(styles.backgroundClip, 0), paint.curves);
+			const backgroundClipValue = getBackgroundValueForIndex(styles.backgroundClip, 0);
+			const backgroundPaintingArea = calculateBackgroundCurvedPaintingArea(backgroundClipValue, paint.curves);
 			if (hasBackground || styles.boxShadow.length) {
-				this.ctx.save();
-				this.path(backgroundPaintingArea);
-				this.ctx.clip();
-				if (!isTransparent(styles.backgroundColor)) {
-					this.ctx.fillStyle = asString(styles.backgroundColor);
-					this.ctx.fill();
+				if (hasTextClip && paint.container.textNodes.length > 0) await this.renderTextClippedBackground(paint);
+				else {
+					this.ctx.save();
+					this.path(backgroundPaintingArea);
+					this.ctx.clip();
+					if (!isTransparent(styles.backgroundColor)) {
+						this.ctx.fillStyle = asString(styles.backgroundColor);
+						this.ctx.fill();
+					}
+					await this.backgroundRenderer.renderBackgroundImage(paint.container);
+					this.ctx.restore();
 				}
-				await this.backgroundRenderer.renderBackgroundImage(paint.container);
-				this.ctx.restore();
 				styles.boxShadow.slice(0).reverse().forEach((shadow) => {
 					this.ctx.save();
 					const borderBoxArea = calculateBorderBoxPath(paint.curves);
@@ -10619,6 +10627,82 @@
 			this.effectsRenderer.applyEffects([]);
 			return this.canvas;
 		}
+		/**
+		* Render background clipped to text shape using offscreen canvas with destination-in compositing.
+		* This implements background-clip: text support.
+		*
+		* Algorithm:
+		*   1. Draw background (color + images) onto an offscreen canvas
+		*   2. Use destination-in compositing to clip the background to the text glyph shapes
+		*   3. Composite the result back onto the main canvas
+		*
+		* The offscreen canvas uses CSS-pixel dimensions (not device-pixel) because the
+		* background renderer handles scaling internally via BackgroundRenderer options.
+		*/
+		async renderTextClippedBackground(paint) {
+			const container = paint.container;
+			const styles = container.styles;
+			const bounds = container.bounds;
+			if (bounds.width <= 0 || bounds.height <= 0) return;
+			const offscreen = (this.canvas.ownerDocument ?? document).createElement("canvas");
+			const width = Math.ceil(bounds.width);
+			const height = Math.ceil(bounds.height);
+			offscreen.width = width;
+			offscreen.height = height;
+			const offCtx = offscreen.getContext("2d");
+			if (!offCtx) return;
+			const [fontString] = this.textRenderer.createFontStyle(styles);
+			offCtx.font = fontString;
+			offCtx.textBaseline = "alphabetic";
+			offCtx.textAlign = "left";
+			offCtx.direction = styles.direction === 1 ? "rtl" : "ltr";
+			const baseline = measureBaseline(offCtx, styles.fontSize.number);
+			const bgRenderer = new BackgroundRenderer({
+				ctx: offCtx,
+				context: this.context,
+				canvas: offscreen,
+				options: {
+					width,
+					height,
+					scale: 1
+				}
+			});
+			if (!isTransparent(styles.backgroundColor)) {
+				offCtx.fillStyle = asString(styles.backgroundColor);
+				offCtx.fillRect(0, 0, width, height);
+			}
+			offCtx.save();
+			offCtx.translate(-bounds.left, -bounds.top);
+			await bgRenderer.renderBackgroundImage(container);
+			offCtx.restore();
+			offCtx.globalCompositeOperation = "destination-in";
+			offCtx.fillStyle = "#000";
+			const writingMode = styles.writingMode;
+			const letterSpacing = styles.letterSpacing;
+			for (const textNode of container.textNodes) for (const textBound of textNode.textBounds) {
+				const localLeft = textBound.bounds.left - bounds.left;
+				const localTop = textBound.bounds.top - bounds.top + baseline;
+				if (letterSpacing > 0) this.renderTextMaskWithLetterSpacing(offCtx, textBound, letterSpacing, localLeft, localTop, writingMode);
+				else offCtx.fillText(textBound.text, localLeft, localTop);
+			}
+			this.ctx.drawImage(offscreen, bounds.left, bounds.top);
+		}
+		/**
+		* Render text glyphs one-by-one as a mask, applying letter-spacing between characters.
+		* This ensures the mask matches how the text renderer lays out the characters.
+		*/
+		renderTextMaskWithLetterSpacing(ctx, text, letterSpacing, x, y, writingMode) {
+			const letters = segmentGraphemes(text.text);
+			let offset = x;
+			for (const letter of letters) {
+				if (isVerticalWritingMode(writingMode)) {
+					ctx.fillText(text.text, x, y);
+					return;
+				}
+				ctx.fillText(letter, offset, y);
+				offset += ctx.measureText(letter).width + letterSpacing;
+			}
+		}
 	};
 	const calculateBackgroundCurvedPaintingArea = (clip, curves) => {
 		switch (clip) {
@@ -10627,6 +10711,12 @@
 			default: return calculatePaddingBoxPath(curves);
 		}
 	};
+	/**
+	* Check if any background layer uses background-clip: text
+	*/
+	const hasTextBackgroundClip = (styles) => {
+		return styles.backgroundClip.some((clip) => clip === 3);
+	};
 	//#endregion
 	//#region src/render/canvas/foreignobject-renderer.ts
 	var ForeignObjectRenderer = class {