@happy-dom/node-canvas-adapter 20.10.0

package/README.md

@@ -0,0 +1,48 @@
+![Happy DOM Logo](https://github.com/capricorn86/happy-dom/raw/master/docs/happy-dom-logo.jpg)
+
+Pluggable canvas adapter for [Happy DOM](https://github.com/capricorn86/happy-dom) using [node-canvas](https://github.com/Automattic/node-canvas).
+
+## Installation
+
+```bash
+npm install canvas @happy-dom/node-canvas-adapter
+```
+
+## Documentation
+
+You will find the documentation in the [Happy DOM Wiki](https://github.com/capricorn86/happy-dom/wiki) under [Node Canvas Adapter](https://github.com/capricorn86/happy-dom/wiki/Node-Canvas-Adapter).
+
+## Usage
+
+```typescript
+import { Window } from 'happy-dom';
+import { CanvasAdapter } from '@happy-dom/node-canvas-adapter';
+
+const window = new Window({
+  settings: {
+    canvasAdapter: new CanvasAdapter(),
+    // Optionally, enable image file loading (e.g. for <img> elements)
+    enableImageFileLoading: true
+  }
+});
+
+const canvas = window.document.createElement('canvas');
+const context = canvas.getContext('2d');
+
+canvas.width = 200;
+canvas.height = 200;
+
+// Now you can use canvas context
+context.fillStyle = 'red';
+context.fillRect(0, 0, 100, 100);
+
+// Get data URL
+const dataUrl = canvas.toDataURL();
+
+// Output the data URL
+console.log(dataUrl);
+```
+
+## Happy DOM
+
+[Documentation](https://github.com/capricorn86/happy-dom/wiki/) | [Getting Started](https://github.com/capricorn86/happy-dom/wiki/Getting-started) | [Setup as Test Environment](https://github.com/capricorn86/happy-dom/wiki/Setup-as-Test-Environment) | [GitHub](https://github.com/capricorn86/happy-dom/)

package/lib/CanvasAdapter.d.ts

@@ -0,0 +1,69 @@
+import { type ICanvasAdapter, type ICanvasRenderingContext2D, type ICanvasAdapterCaller, type Blob } from 'happy-dom';
+/**
+ * Canvas adapter that delegates rendering to the `canvas` npm package.
+ *
+ * @example
+ * ```typescript
+ * import { Window } from 'happy-dom';
+ * import { CanvasAdapter } from '@happy-dom/node-canvas-adapter';
+ *
+ * const window = new Window({
+ *   settings: { canvasAdapter: new CanvasAdapter() }
+ * });
+ *
+ * const canvas = window.document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ * ```
+ */
+export default class CanvasAdapter implements ICanvasAdapter {
+    #private;
+    /**
+     * Creates a rendering context for the given canvas element.
+     *
+     * @param canvas.canvas
+     * @param canvas The canvas element.
+     * @param canvas.window Window.
+     * @param contextType The context identifier ('2d', 'webgl', etc.).
+     * @param contextAttributes Optional context creation attributes.
+     * @param canvas.canvasType
+     * @returns The rendering context, or null if the type is unsupported.
+     *
+     * @example
+     * ```typescript
+     * const ctx = adapter.getContext(canvas, '2d');
+     * ```
+     */
+    getContext({ canvas, window }: ICanvasAdapterCaller, contextType: string, contextAttributes?: Record<string, unknown>): ICanvasRenderingContext2D | null;
+    /**
+     * Serialize the canvas content as a data URL.
+     *
+     * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+     * @param caller.canvas Canvas.
+     * @param type MIME type of the output image.
+     * @param quality Encoder quality for lossy formats, in the range 0–1.
+     * @returns A data URL string.
+     *
+     * @example
+     * ```typescript
+     * const url = adapter.toDataURL(canvas, 'image/png');
+     * ```
+     */
+    toDataURL({ canvas }: ICanvasAdapterCaller, type?: string, quality?: unknown): string;
+    /**
+     * Creates a Blob from the canvas content and passes it to the callback.
+     *
+     * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+     * @param caller.canvas Canvas.
+     * @param caller.window Window.
+     * @param canvas The canvas element.
+     * @param callback Receives the resulting Blob, or null on failure.
+     * @param type MIME type of the output image.
+     * @param quality Encoder quality for lossy formats, in the range 0–1.
+     *
+     * @example
+     * ```typescript
+     * adapter.toBlob(canvas, (blob) => console.log(blob?.size));
+     * ```
+     */
+    toBlob({ canvas, window }: ICanvasAdapterCaller, callback: (blob: Blob | null) => void, type?: string, quality?: unknown): void;
+}

package/lib/CanvasAdapter.js

@@ -0,0 +1,216 @@
+import { createCanvas, Image as CanvasImage } from 'canvas';
+import { HTMLCanvasElement, HTMLImageElement, OffscreenCanvas, ImageData, PropertySymbol, HTMLVideoElement, ImageBitmap } from 'happy-dom';
+const EXTENDED_SYMBOL = Symbol('extended');
+/**
+ * Canvas adapter that delegates rendering to the `canvas` npm package.
+ *
+ * @example
+ * ```typescript
+ * import { Window } from 'happy-dom';
+ * import { CanvasAdapter } from '@happy-dom/node-canvas-adapter';
+ *
+ * const window = new Window({
+ *   settings: { canvasAdapter: new CanvasAdapter() }
+ * });
+ *
+ * const canvas = window.document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ * ```
+ */
+export default class CanvasAdapter {
+    #canvases = new WeakMap();
+    /**
+     * Returns or creates a node-canvas instance bound to the given canvas element.
+     *
+     * @param canvas The canvas element.
+     * @returns The bound node-canvas instance.
+     */
+    #getNodeCanvas(canvas) {
+        const existing = this.#canvases.get(canvas);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const nodeCanvas = createCanvas(canvas.width, canvas.height);
+        this.#canvases.set(canvas, nodeCanvas);
+        return nodeCanvas;
+    }
+    /**
+     * Creates a rendering context for the given canvas element.
+     *
+     * @param canvas.canvas
+     * @param canvas The canvas element.
+     * @param canvas.window Window.
+     * @param contextType The context identifier ('2d', 'webgl', etc.).
+     * @param contextAttributes Optional context creation attributes.
+     * @param canvas.canvasType
+     * @returns The rendering context, or null if the type is unsupported.
+     *
+     * @example
+     * ```typescript
+     * const ctx = adapter.getContext(canvas, '2d');
+     * ```
+     */
+    getContext({ canvas, window }, contextType, contextAttributes) {
+        if (contextType !== '2d') {
+            return null;
+        }
+        const context = this.#getNodeCanvas(canvas).getContext('2d', contextAttributes);
+        if (context === null) {
+            return null;
+        }
+        if (context[EXTENDED_SYMBOL]) {
+            return context;
+        }
+        context[EXTENDED_SYMBOL] = true;
+        // drawImage()
+        const originalDrawImage = context.drawImage;
+        context.drawImage = (...args) => {
+            const shape = args[0];
+            const drawImageBuffer = (buffer) => {
+                const canvasImage = new CanvasImage();
+                canvasImage.src = buffer;
+                canvasImage.width = shape.width;
+                canvasImage.height = shape.height;
+                args[0] = canvasImage;
+                originalDrawImage.apply(context, args);
+            };
+            if (shape instanceof HTMLImageElement) {
+                if (shape[PropertySymbol.buffer]) {
+                    drawImageBuffer(shape[PropertySymbol.buffer]);
+                    return;
+                }
+                if (!shape.complete) {
+                    shape.addEventListener('load', () => {
+                        if (shape[PropertySymbol.buffer]) {
+                            drawImageBuffer(shape[PropertySymbol.buffer]);
+                        }
+                    });
+                }
+                return;
+            }
+            if (shape instanceof HTMLVideoElement) {
+                // Not supported yet
+                return;
+            }
+            if (shape instanceof ImageBitmap ||
+                shape instanceof HTMLCanvasElement ||
+                shape instanceof OffscreenCanvas) {
+                const nodeCanvas = this.#getNodeCanvas(shape[PropertySymbol.canvas] || shape);
+                if (nodeCanvas) {
+                    args[0] = nodeCanvas;
+                    originalDrawImage.apply(context, args);
+                }
+                return;
+            }
+        };
+        // createImageData()
+        const originalCreateImageData = context.createImageData;
+        context.createImageData = (...args) => {
+            const imageData = originalCreateImageData.apply(context, args);
+            return new ImageData(imageData.data, imageData.width, imageData.height);
+        };
+        // putImageData()
+        const originalPutImageData = context.putImageData;
+        context.putImageData = (...args) => {
+            const imageData = args[0];
+            if (!(imageData instanceof ImageData)) {
+                throw new window.TypeError(`Failed to execute 'putImageData' on 'CanvasRenderingContext2D': parameter 1 is not of type 'ImageData'`);
+            }
+            const canvasImageData = originalCreateImageData.call(context, imageData.width, imageData.height);
+            canvasImageData.data.set(imageData.data);
+            args[0] = canvasImageData;
+            originalPutImageData.apply(context, args);
+        };
+        // getImageData()
+        const originalGetImageData = context.getImageData;
+        context.getImageData = (...args) => {
+            const imageData = originalGetImageData.apply(context, args);
+            return new ImageData(imageData.data, imageData.width, imageData.height);
+        };
+        // createPattern()
+        const originalCreatePattern = context.createPattern;
+        context.createPattern = (shape, repetition) => {
+            if (shape instanceof HTMLImageElement) {
+                if (!shape[PropertySymbol.buffer]) {
+                    return null;
+                }
+                const canvasImage = new CanvasImage();
+                canvasImage.src = shape[PropertySymbol.buffer];
+                canvasImage.width = shape.width;
+                canvasImage.height = shape.height;
+                return originalCreatePattern.call(context, canvasImage, repetition);
+            }
+            if (shape instanceof HTMLVideoElement) {
+                // Not supported yet
+                return null;
+            }
+            if (shape instanceof ImageBitmap ||
+                shape instanceof HTMLCanvasElement ||
+                shape instanceof OffscreenCanvas) {
+                const nodeCanvas = this.#getNodeCanvas(shape[PropertySymbol.canvas] || shape);
+                if (nodeCanvas) {
+                    return originalCreatePattern.call(context, nodeCanvas, repetition);
+                }
+            }
+            return null;
+        };
+        return context;
+    }
+    /**
+     * Serialize the canvas content as a data URL.
+     *
+     * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+     * @param caller.canvas Canvas.
+     * @param type MIME type of the output image.
+     * @param quality Encoder quality for lossy formats, in the range 0–1.
+     * @returns A data URL string.
+     *
+     * @example
+     * ```typescript
+     * const url = adapter.toDataURL(canvas, 'image/png');
+     * ```
+     */
+    toDataURL({ canvas }, type, quality) {
+        const nodeCanvas = this.#getNodeCanvas(canvas);
+        if (type === 'image/jpeg') {
+            return nodeCanvas.toDataURL('image/jpeg', quality);
+        }
+        return nodeCanvas.toDataURL('image/png');
+    }
+    /**
+     * Creates a Blob from the canvas content and passes it to the callback.
+     *
+     * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+     * @param caller.canvas Canvas.
+     * @param caller.window Window.
+     * @param canvas The canvas element.
+     * @param callback Receives the resulting Blob, or null on failure.
+     * @param type MIME type of the output image.
+     * @param quality Encoder quality for lossy formats, in the range 0–1.
+     *
+     * @example
+     * ```typescript
+     * adapter.toBlob(canvas, (blob) => console.log(blob?.size));
+     * ```
+     */
+    toBlob({ canvas, window }, callback, type, quality) {
+        const nodeCanvas = this.#getNodeCanvas(canvas);
+        if (type === 'image/jpeg') {
+            nodeCanvas.toBuffer((error, buffer) => {
+                if (error !== null) {
+                    callback(null);
+                    return;
+                }
+                callback(new window.Blob([new Uint8Array(buffer)], { type: 'image/jpeg' }));
+            }, 'image/jpeg', { quality: quality });
+            return;
+        }
+        nodeCanvas.toBuffer((error, buffer) => {
+            if (error !== null) {
+                callback(null);
+                return;
+            }
+            callback(new window.Blob([new Uint8Array(buffer)], { type: type ?? 'image/png' }));
+        });
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1 @@
+export { default as CanvasAdapter } from './CanvasAdapter.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { default as CanvasAdapter } from './CanvasAdapter.js';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@happy-dom/node-canvas-adapter",
+  "version": "20.10.0",
+  "license": "MIT",
+  "homepage": "https://github.com/capricorn86/happy-dom/tree/master/packages/@happy-dom/node-canvas-adapter",
+  "repository": "https://github.com/capricorn86/happy-dom",
+  "author": "David Ortner",
+  "description": "Pluggable canvas adapter for happy-dom using node-canvas.",
+  "main": "lib/index.js",
+  "type": "module",
+  "keywords": [
+    "canvas",
+    "happy-dom",
+    "adapter",
+    "node-canvas",
+    "rendering"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc",
+    "watch": "tsc -w --preserveWatchOutput",
+    "test": "vitest run",
+    "test:debug": "vitest run --inspect-brk --no-file-parallelism"
+  },
+  "peerDependencies": {
+    "canvas": "^3.2.3",
+    "happy-dom": ">=20.9.0"
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.0.16",
+    "canvas": "^3.2.1",
+    "happy-dom": "^20.10.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/CanvasAdapter.ts

@@ -0,0 +1,275 @@
+import { createCanvas, Image as CanvasImage } from 'canvas';
+import {
+	HTMLCanvasElement,
+	HTMLImageElement,
+	OffscreenCanvas,
+	ImageData,
+	PropertySymbol,
+	type ICanvasAdapter,
+	type ICanvasRenderingContext2D,
+	type ICanvasAdapterCaller,
+	type ICanvasShape,
+	type Blob,
+	HTMLVideoElement,
+	ImageBitmap
+} from 'happy-dom';
+
+const EXTENDED_SYMBOL = Symbol('extended');
+
+/**
+ * Canvas adapter that delegates rendering to the `canvas` npm package.
+ *
+ * @example
+ * ```typescript
+ * import { Window } from 'happy-dom';
+ * import { CanvasAdapter } from '@happy-dom/node-canvas-adapter';
+ *
+ * const window = new Window({
+ *   settings: { canvasAdapter: new CanvasAdapter() }
+ * });
+ *
+ * const canvas = window.document.createElement('canvas');
+ * const ctx = canvas.getContext('2d');
+ * ```
+ */
+export default class CanvasAdapter implements ICanvasAdapter {
+	readonly #canvases = new WeakMap<ICanvasShape, ReturnType<typeof createCanvas>>();
+
+	/**
+	 * Returns or creates a node-canvas instance bound to the given canvas element.
+	 *
+	 * @param canvas The canvas element.
+	 * @returns The bound node-canvas instance.
+	 */
+	#getNodeCanvas(canvas: ICanvasShape): ReturnType<typeof createCanvas> {
+		const existing = this.#canvases.get(canvas);
+		if (existing !== undefined) {
+			return existing;
+		}
+		const nodeCanvas = createCanvas(canvas.width, canvas.height);
+		this.#canvases.set(canvas, nodeCanvas);
+		return nodeCanvas;
+	}
+
+	/**
+	 * Creates a rendering context for the given canvas element.
+	 *
+	 * @param canvas.canvas
+	 * @param canvas The canvas element.
+	 * @param canvas.window Window.
+	 * @param contextType The context identifier ('2d', 'webgl', etc.).
+	 * @param contextAttributes Optional context creation attributes.
+	 * @param canvas.canvasType
+	 * @returns The rendering context, or null if the type is unsupported.
+	 *
+	 * @example
+	 * ```typescript
+	 * const ctx = adapter.getContext(canvas, '2d');
+	 * ```
+	 */
+	public getContext(
+		{ canvas, window }: ICanvasAdapterCaller,
+		contextType: string,
+		contextAttributes?: Record<string, unknown>
+	): ICanvasRenderingContext2D | null {
+		if (contextType !== '2d') {
+			return null;
+		}
+		const context = this.#getNodeCanvas(canvas).getContext('2d', contextAttributes);
+
+		if (context === null) {
+			return null;
+		}
+
+		if ((<any>context)[EXTENDED_SYMBOL]) {
+			return <ICanvasRenderingContext2D>(<unknown>context);
+		}
+
+		(<any>context)[EXTENDED_SYMBOL] = true;
+
+		// drawImage()
+		const originalDrawImage = context.drawImage;
+		context.drawImage = (...args: any[]) => {
+			const shape = <ICanvasShape>args[0];
+			const drawImageBuffer = (buffer: Buffer): void => {
+				const canvasImage = new CanvasImage();
+				canvasImage.src = buffer;
+				canvasImage.width = shape.width;
+				canvasImage.height = shape.height;
+				args[0] = canvasImage;
+				(<any>originalDrawImage).apply(context, args);
+			};
+			if (shape instanceof HTMLImageElement) {
+				if (shape[PropertySymbol.buffer]) {
+					drawImageBuffer(shape[PropertySymbol.buffer]);
+					return;
+				}
+				if (!shape.complete) {
+					shape.addEventListener('load', () => {
+						if (shape[PropertySymbol.buffer]) {
+							drawImageBuffer(shape[PropertySymbol.buffer]);
+						}
+					});
+				}
+				return;
+			}
+			if (shape instanceof HTMLVideoElement) {
+				// Not supported yet
+				return;
+			}
+			if (
+				shape instanceof ImageBitmap ||
+				shape instanceof HTMLCanvasElement ||
+				shape instanceof OffscreenCanvas
+			) {
+				const nodeCanvas = this.#getNodeCanvas(
+					(<ImageBitmap>shape)[PropertySymbol.canvas] || shape
+				);
+				if (nodeCanvas) {
+					args[0] = nodeCanvas;
+					(<any>originalDrawImage).apply(context, args);
+				}
+				return;
+			}
+		};
+
+		// createImageData()
+		const originalCreateImageData = context.createImageData;
+		context.createImageData = (...args: any[]) => {
+			const imageData = originalCreateImageData.apply(context, <any>args);
+			return new ImageData(imageData.data, imageData.width, imageData.height);
+		};
+
+		// putImageData()
+		const originalPutImageData = context.putImageData;
+		context.putImageData = (...args: any[]) => {
+			const imageData = args[0];
+			if (!(imageData instanceof ImageData)) {
+				throw new window.TypeError(
+					`Failed to execute 'putImageData' on 'CanvasRenderingContext2D': parameter 1 is not of type 'ImageData'`
+				);
+			}
+			const canvasImageData = (<any>originalCreateImageData).call(
+				context,
+				imageData.width,
+				imageData.height
+			);
+			canvasImageData.data.set(imageData.data);
+			args[0] = canvasImageData;
+			(<any>originalPutImageData).apply(context, args);
+		};
+
+		// getImageData()
+		const originalGetImageData = context.getImageData;
+		context.getImageData = (...args: any[]) => {
+			const imageData = originalGetImageData.apply(context, <any>args);
+			return new ImageData(imageData.data, imageData.width, imageData.height);
+		};
+
+		// createPattern()
+		const originalCreatePattern = context.createPattern;
+		context.createPattern = (
+			shape: any,
+			repetition: '' | 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat'
+		): any => {
+			if (shape instanceof HTMLImageElement) {
+				if (!shape[PropertySymbol.buffer]) {
+					return null;
+				}
+
+				const canvasImage = new CanvasImage();
+				canvasImage.src = shape[PropertySymbol.buffer];
+				canvasImage.width = shape.width;
+				canvasImage.height = shape.height;
+				return originalCreatePattern.call(context, canvasImage, repetition);
+			}
+			if (shape instanceof HTMLVideoElement) {
+				// Not supported yet
+				return null;
+			}
+			if (
+				shape instanceof ImageBitmap ||
+				shape instanceof HTMLCanvasElement ||
+				shape instanceof OffscreenCanvas
+			) {
+				const nodeCanvas = this.#getNodeCanvas(
+					(<ImageBitmap>shape)[PropertySymbol.canvas] || shape
+				);
+				if (nodeCanvas) {
+					return originalCreatePattern.call(context, nodeCanvas, repetition);
+				}
+			}
+			return null;
+		};
+
+		return <ICanvasRenderingContext2D>(<unknown>context);
+	}
+
+	/**
+	 * Serialize the canvas content as a data URL.
+	 *
+	 * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+	 * @param caller.canvas Canvas.
+	 * @param type MIME type of the output image.
+	 * @param quality Encoder quality for lossy formats, in the range 0–1.
+	 * @returns A data URL string.
+	 *
+	 * @example
+	 * ```typescript
+	 * const url = adapter.toDataURL(canvas, 'image/png');
+	 * ```
+	 */
+	public toDataURL({ canvas }: ICanvasAdapterCaller, type?: string, quality?: unknown): string {
+		const nodeCanvas = this.#getNodeCanvas(canvas);
+		if (type === 'image/jpeg') {
+			return nodeCanvas.toDataURL('image/jpeg', <number>quality);
+		}
+		return nodeCanvas.toDataURL('image/png');
+	}
+
+	/**
+	 * Creates a Blob from the canvas content and passes it to the callback.
+	 *
+	 * @param caller Information about the caller, including the canvas element and its associated window and browser frame.
+	 * @param caller.canvas Canvas.
+	 * @param caller.window Window.
+	 * @param canvas The canvas element.
+	 * @param callback Receives the resulting Blob, or null on failure.
+	 * @param type MIME type of the output image.
+	 * @param quality Encoder quality for lossy formats, in the range 0–1.
+	 *
+	 * @example
+	 * ```typescript
+	 * adapter.toBlob(canvas, (blob) => console.log(blob?.size));
+	 * ```
+	 */
+	public toBlob(
+		{ canvas, window }: ICanvasAdapterCaller,
+		callback: (blob: Blob | null) => void,
+		type?: string,
+		quality?: unknown
+	): void {
+		const nodeCanvas = this.#getNodeCanvas(canvas);
+		if (type === 'image/jpeg') {
+			nodeCanvas.toBuffer(
+				(error, buffer) => {
+					if (error !== null) {
+						callback(null);
+						return;
+					}
+					callback(new window.Blob([new Uint8Array(buffer)], { type: 'image/jpeg' }));
+				},
+				'image/jpeg',
+				{ quality: <number>quality }
+			);
+			return;
+		}
+		nodeCanvas.toBuffer((error, buffer) => {
+			if (error !== null) {
+				callback(null);
+				return;
+			}
+			callback(new window.Blob([new Uint8Array(buffer)], { type: type ?? 'image/png' }));
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default as CanvasAdapter } from './CanvasAdapter.js';