@gjsify/dom-elements 0.1.0

package/lib/types/resize-observer.d.ts

@@ -0,0 +1,13 @@
+import type { Element } from './element.js';
+/**
+ * ResizeObserver stub.
+ * Many libraries check for ResizeObserver existence; this prevents crashes.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
+ */
+export declare class ResizeObserver {
+    constructor(_callback: (...args: unknown[]) => void);
+    observe(_target: Element): void;
+    unobserve(_target: Element): void;
+    disconnect(): void;
+}

package/lib/types/text.d.ts

@@ -0,0 +1,21 @@
+import { CharacterData } from './character-data.js';
+/**
+ * Text node.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/Text
+ */
+export declare class Text extends CharacterData {
+    constructor(data?: string);
+    get nodeName(): string;
+    /**
+     * Returns the combined text of this node and all adjacent Text siblings.
+     */
+    get wholeText(): string;
+    /**
+     * Splits the text node at the given offset, returning the new Text node
+     * containing the text after the offset.
+     */
+    splitText(offset: number): Text;
+    cloneNode(_deep?: boolean): Text;
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/types/i-html-image-element.d.ts

@@ -0,0 +1,41 @@
+import type { HTMLElement } from '@gjsify/dom-elements';
+/**
+ * HTML Image Element.
+ *
+ * Reference:
+ * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement.
+ */
+export interface IHTMLImageElement extends HTMLElement {
+    alt: string;
+    readonly complete: boolean;
+    crossOrigin: string | null;
+    readonly currentSrc: string;
+    decoding: string;
+    height: number;
+    isMap: boolean;
+    loading: string;
+    readonly naturalHeight: number;
+    readonly naturalWidth: number;
+    referrerPolicy: string;
+    sizes: string;
+    src: string;
+    srcset: string;
+    useMap: string;
+    width: number;
+    readonly x: number;
+    readonly y: number;
+    /**
+     * The decode() method of the HTMLImageElement interface returns a Promise that resolves when the image is decoded and it is safe to append the image to the DOM.
+     *
+     * @returns Promise.
+     */
+    decode(): Promise<void>;
+    /**
+     * Clones a node.
+     *
+     * @override
+     * @param [deep=false] "true" to clone deep.
+     * @returns Cloned node.
+     */
+    cloneNode(deep?: boolean): IHTMLImageElement;
+}

package/lib/types/types/image-data.d.ts

@@ -0,0 +1,11 @@
+import type { PredefinedColorSpace } from './predefined-color-space.js';
+/** The underlying pixel data of an area of a <canvas> element. It is created using the ImageData() constructor or creator methods on the CanvasRenderingContext2D object associated with a canvas: createImageData() and getImageData(). It can also be used to set a part of the canvas by using putImageData(). */
+export interface ImageData {
+    readonly colorSpace: PredefinedColorSpace;
+    /** Returns the one-dimensional array containing the data in RGBA order, as integers in the range 0 to 255. */
+    readonly data: Uint8ClampedArray<ArrayBuffer>;
+    /** Returns the actual dimensions of the data in the ImageData object, in pixels. */
+    readonly height: number;
+    /** Returns the actual dimensions of the data in the ImageData object, in pixels. */
+    readonly width: number;
+}

package/lib/types/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './i-html-image-element.js';
+export * from './image-data.js';
+export * from './predefined-color-space.js';

package/lib/types/types/predefined-color-space.d.ts

@@ -0,0 +1 @@
+export type PredefinedColorSpace = "display-p3" | "srgb";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gjsify/dom-elements",
+  "version": "0.1.0",
+  "description": "DOM element hierarchy (Node, Element, HTMLElement, HTMLImageElement) for GJS",
+  "type": "module",
+  "module": "lib/esm/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/esm/index.js"
+    }
+  },
+  "scripts": {
+    "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs test.node.mjs || exit 0",
+    "check": "tsc --noEmit",
+    "build": "yarn build:gjsify && yarn build:types",
+    "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+    "build:types": "tsc",
+    "build:test": "yarn build:test:gjs",
+    "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+    "test": "yarn build:gjsify && yarn build:test && yarn test:gjs",
+    "test:gjs": "gjs -m test.gjs.mjs"
+  },
+  "keywords": [
+    "gjs",
+    "dom",
+    "element",
+    "node"
+  ],
+  "dependencies": {
+    "@girs/gdkpixbuf-2.0": "^2.0.0-4.0.0-beta.42",
+    "@girs/gjs": "^4.0.0-beta.42",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-beta.42",
+    "@gjsify/dom-events": "^0.1.0"
+  },
+  "devDependencies": {
+    "@gjsify/cli": "^0.1.0",
+    "@gjsify/unit": "^0.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/attr.ts

@@ -0,0 +1,61 @@
+// Adapted from happy-dom (refs/happy-dom/packages/happy-dom/src/nodes/attr/Attr.ts)
+// Copyright (c) David Ortner (capricorn86). MIT license.
+// Modifications: Simplified for gjsify — lightweight data holder, does not extend Node
+
+import * as PS from './property-symbol.js';
+
+import type { Element } from './element.js';
+
+/**
+ * Represents a DOM attribute.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/Attr
+ */
+export class Attr {
+	public [PS.name]: string;
+	public [PS.value]: string;
+	public [PS.ownerElement]: Element | null;
+
+	public readonly localName: string;
+	public readonly namespaceURI: string | null;
+	public readonly prefix: string | null;
+	public readonly specified = true;
+
+	constructor(
+		name: string,
+		value: string,
+		namespaceURI: string | null = null,
+		prefix: string | null = null,
+		ownerElement: Element | null = null,
+	) {
+		this[PS.name] = name;
+		this[PS.value] = value;
+		this[PS.ownerElement] = ownerElement;
+		this.namespaceURI = namespaceURI;
+		this.prefix = prefix;
+
+		// localName is the part after the prefix colon, or the full name if no prefix
+		const colonIndex = name.indexOf(':');
+		this.localName = colonIndex !== -1 ? name.slice(colonIndex + 1) : name;
+	}
+
+	get name(): string {
+		return this[PS.name];
+	}
+
+	get value(): string {
+		return this[PS.value];
+	}
+
+	set value(value: string) {
+		this[PS.value] = value;
+	}
+
+	get ownerElement(): Element | null {
+		return this[PS.ownerElement];
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'Attr';
+	}
+}

package/src/character-data.ts

@@ -0,0 +1,79 @@
+// Adapted from happy-dom (refs/happy-dom/packages/happy-dom/src/nodes/character-data/CharacterData.ts)
+// Copyright (c) David Ortner (capricorn86). MIT license.
+// Modifications: Simplified for gjsify — no ChildNode utilities, no mutation observer hooks
+
+import { Node } from './node.js';
+import { NodeType } from './node-type.js';
+import * as PS from './property-symbol.js';
+
+/**
+ * CharacterData base class for Text and Comment nodes.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/CharacterData
+ */
+export class CharacterData extends Node {
+	private _data: string;
+
+	constructor(data = '') {
+		super();
+		this[PS.nodeType] = NodeType.TEXT_NODE;
+		this._data = data;
+	}
+
+	get data(): string {
+		return this._data;
+	}
+
+	set data(value: string) {
+		this._data = value;
+	}
+
+	get textContent(): string {
+		return this._data;
+	}
+
+	set textContent(value: string) {
+		this._data = value;
+	}
+
+	get nodeValue(): string {
+		return this._data;
+	}
+
+	set nodeValue(value: string) {
+		this._data = value;
+	}
+
+	get length(): number {
+		return this._data.length;
+	}
+
+	appendData(data: string): void {
+		this._data += data;
+	}
+
+	deleteData(offset: number, count: number): void {
+		this._data = this._data.substring(0, offset) + this._data.substring(offset + count);
+	}
+
+	insertData(offset: number, data: string): void {
+		this._data = this._data.substring(0, offset) + data + this._data.substring(offset);
+	}
+
+	replaceData(offset: number, count: number, data: string): void {
+		this._data = this._data.substring(0, offset) + data + this._data.substring(offset + count);
+	}
+
+	substringData(offset: number, count: number): string {
+		return this._data.substring(offset, offset + count);
+	}
+
+	cloneNode(_deep = false): CharacterData {
+		const clone = new (this.constructor as typeof CharacterData)(this._data);
+		return clone;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'CharacterData';
+	}
+}

package/src/comment.ts

@@ -0,0 +1,31 @@
+// Adapted from happy-dom (refs/happy-dom/packages/happy-dom/src/nodes/comment/Comment.ts)
+// Copyright (c) David Ortner (capricorn86). MIT license.
+// Modifications: Simplified for gjsify
+
+import { CharacterData } from './character-data.js';
+import { NodeType } from './node-type.js';
+import * as PS from './property-symbol.js';
+
+/**
+ * Comment node.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/Comment
+ */
+export class Comment extends CharacterData {
+	constructor(data = '') {
+		super(data);
+		this[PS.nodeType] = NodeType.COMMENT_NODE;
+	}
+
+	get nodeName(): string {
+		return '#comment';
+	}
+
+	cloneNode(_deep = false): Comment {
+		return new Comment(this.data);
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'Comment';
+	}
+}

package/src/document-fragment.ts

@@ -0,0 +1,137 @@
+// Adapted from happy-dom (refs/happy-dom/packages/happy-dom/src/nodes/document-fragment/DocumentFragment.ts)
+// Copyright (c) David Ortner (capricorn86). MIT license.
+// Modifications: Simplified for gjsify — no querySelector/querySelectorAll, no HTML parsing
+
+import { Node } from './node.js';
+import { Element } from './element.js';
+import { Text } from './text.js';
+import { NodeType } from './node-type.js';
+import * as PS from './property-symbol.js';
+
+/**
+ * DocumentFragment.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment
+ */
+export class DocumentFragment extends Node {
+	constructor() {
+		super();
+		this[PS.nodeType] = NodeType.DOCUMENT_FRAGMENT_NODE;
+	}
+
+	get nodeName(): string {
+		return '#document-fragment';
+	}
+
+	/** Element children only (excludes text/comment nodes) */
+	get children(): Element[] {
+		return this[PS.elementChildren] as Element[];
+	}
+
+	get childElementCount(): number {
+		return this[PS.elementChildren].length;
+	}
+
+	get firstElementChild(): Element | null {
+		return (this[PS.elementChildren][0] as Element) ?? null;
+	}
+
+	get lastElementChild(): Element | null {
+		const children = this[PS.elementChildren];
+		return (children[children.length - 1] as Element) ?? null;
+	}
+
+	get textContent(): string {
+		let text = '';
+		for (const child of this.childNodes) {
+			if (child.textContent !== null) {
+				text += child.textContent;
+			}
+		}
+		return text;
+	}
+
+	set textContent(value: string) {
+		// Remove all children
+		while (this.firstChild) {
+			this.removeChild(this.firstChild);
+		}
+		// Add text node if value is non-empty
+		if (value) {
+			// Import Text lazily to avoid circular dependency
+this.appendChild(new Text(value));
+		}
+	}
+
+	/**
+	 * Append nodes or strings to this fragment.
+	 */
+	append(...nodes: (Node | string)[]): void {
+		for (const node of nodes) {
+			if (typeof node === 'string') {
+		this.appendChild(new Text(node));
+			} else {
+				this.appendChild(node);
+			}
+		}
+	}
+
+	/**
+	 * Prepend nodes or strings to this fragment.
+	 */
+	prepend(...nodes: (Node | string)[]): void {
+		const firstChild = this.firstChild;
+		for (const node of nodes) {
+			if (typeof node === 'string') {
+		this.insertBefore(new Text(node), firstChild);
+			} else {
+				this.insertBefore(node, firstChild);
+			}
+		}
+	}
+
+	/**
+	 * Replace all children with the given nodes.
+	 */
+	replaceChildren(...nodes: (Node | string)[]): void {
+		while (this.firstChild) {
+			this.removeChild(this.firstChild);
+		}
+		this.append(...nodes);
+	}
+
+	/**
+	 * Find an element by ID in this fragment's children.
+	 */
+	getElementById(id: string): Element | null {
+		for (const child of this.children) {
+			if (child.id === id) return child;
+			const found = this._findById(child, id);
+			if (found) return found;
+		}
+		return null;
+	}
+
+	private _findById(element: Element, id: string): Element | null {
+		for (const child of element.children) {
+			if (child.id === id) return child;
+			const found = this._findById(child, id);
+			if (found) return found;
+		}
+		return null;
+	}
+
+	cloneNode(deep = false): DocumentFragment {
+		const clone = new DocumentFragment();
+		if (deep) {
+			for (const child of this.childNodes) {
+				clone.appendChild(child.cloneNode(true));
+			}
+		}
+		return clone;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'DocumentFragment';
+	}
+}

package/src/document.ts

@@ -0,0 +1,93 @@
+// Document stub for GJS — original implementation
+// Reference: refs/happy-dom/packages/happy-dom/src/nodes/document/Document.ts
+
+import { Node } from './node.js';
+import { Element } from './element.js';
+import { HTMLElement } from './html-element.js';
+import { HTMLImageElement } from './html-image-element.js';
+import { HTMLCanvasElement } from './html-canvas-element.js';
+import { Text } from './text.js';
+import { Comment } from './comment.js';
+import { DocumentFragment } from './document-fragment.js';
+import { Event } from '@gjsify/dom-events';
+
+type ElementFactory = () => HTMLElement;
+
+export class Document extends Node {
+    /** External packages register element factories here (e.g. @gjsify/iframe registers 'iframe') */
+    private static _elementFactories = new Map<string, ElementFactory>();
+
+    /** Stub body element */
+    readonly body: HTMLElement = new HTMLElement();
+
+    /** Stub head element */
+    readonly head: HTMLElement = new HTMLElement();
+
+    /** Stub documentElement */
+    readonly documentElement: HTMLElement = new HTMLElement();
+
+    /**
+     * Register a factory for a custom element tag name.
+     * Called as a side-effect by DOM packages to avoid circular dependencies.
+     *
+     * Example: `Document.registerElementFactory('iframe', () => new HTMLIFrameElement())`
+     */
+    static registerElementFactory(tagName: string, factory: ElementFactory): void {
+        Document._elementFactories.set(tagName.toLowerCase(), factory);
+    }
+
+    createElementNS(_namespace: string | null, tagName: string): HTMLElement {
+        const tag = tagName.toLowerCase();
+        switch (tag) {
+            case 'img': return new HTMLImageElement();
+            case 'canvas': return new HTMLCanvasElement();
+            default: {
+                const factory = Document._elementFactories.get(tag);
+                if (factory) return factory();
+                return new HTMLElement();
+            }
+        }
+    }
+
+    createElement(tagName: string): HTMLElement {
+        return this.createElementNS('http://www.w3.org/1999/xhtml', tagName);
+    }
+
+    createTextNode(data: string): Text {
+        return new Text(data);
+    }
+
+    createComment(data: string): Comment {
+        return new Comment(data);
+    }
+
+    createDocumentFragment(): DocumentFragment {
+        return new DocumentFragment();
+    }
+
+    createEvent(type: string): Event {
+        return new Event(type);
+    }
+
+    /**
+     * Find an element by ID. Searches body's descendants.
+     */
+    getElementById(id: string): Element | null {
+        return this._findById(this.body, id);
+    }
+
+    private _findById(element: Element, id: string): Element | null {
+        if (element.id === id) return element;
+        for (const child of element.children) {
+            const found = this._findById(child, id);
+            if (found) return found;
+        }
+        return null;
+    }
+
+    get [Symbol.toStringTag](): string {
+        return 'Document';
+    }
+}
+
+export const document = new Document();

package/src/dom-token-list.ts

@@ -0,0 +1,140 @@
+// Adapted from happy-dom (refs/happy-dom/packages/happy-dom/src/dom/DOMTokenList.ts)
+// Copyright (c) David Ortner (capricorn86). MIT license.
+// Modifications: Simplified for gjsify — no Proxy, plain array-based implementation
+
+import type { Element } from './element.js';
+
+/**
+ * DOMTokenList — manages a set of space-separated tokens on an attribute.
+ *
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
+ */
+export class DOMTokenList {
+	private _ownerElement: Element;
+	private _attributeName: string;
+
+	constructor(ownerElement: Element, attributeName: string) {
+		this._ownerElement = ownerElement;
+		this._attributeName = attributeName;
+	}
+
+	private _getTokens(): string[] {
+		const value = this._ownerElement.getAttribute(this._attributeName);
+		if (!value) return [];
+		return value.split(/\s+/).filter(t => t.length > 0);
+	}
+
+	private _setTokens(tokens: string[]): void {
+		const value = tokens.join(' ');
+		if (value) {
+			this._ownerElement.setAttribute(this._attributeName, value);
+		} else {
+			this._ownerElement.removeAttribute(this._attributeName);
+		}
+	}
+
+	get length(): number {
+		return this._getTokens().length;
+	}
+
+	get value(): string {
+		return this._ownerElement.getAttribute(this._attributeName) ?? '';
+	}
+
+	set value(val: string) {
+		if (val) {
+			this._ownerElement.setAttribute(this._attributeName, val);
+		} else {
+			this._ownerElement.removeAttribute(this._attributeName);
+		}
+	}
+
+	item(index: number): string | null {
+		const tokens = this._getTokens();
+		return index >= 0 && index < tokens.length ? tokens[index] : null;
+	}
+
+	contains(token: string): boolean {
+		return this._getTokens().includes(token);
+	}
+
+	add(...tokens: string[]): void {
+		const current = this._getTokens();
+		for (const token of tokens) {
+			if (token && !current.includes(token)) {
+				current.push(token);
+			}
+		}
+		this._setTokens(current);
+	}
+
+	remove(...tokens: string[]): void {
+		const current = this._getTokens().filter(t => !tokens.includes(t));
+		this._setTokens(current);
+	}
+
+	toggle(token: string, force?: boolean): boolean {
+		const has = this.contains(token);
+		if (force !== undefined) {
+			if (force) {
+				this.add(token);
+				return true;
+			} else {
+				this.remove(token);
+				return false;
+			}
+		}
+		if (has) {
+			this.remove(token);
+			return false;
+		} else {
+			this.add(token);
+			return true;
+		}
+	}
+
+	replace(token: string, newToken: string): boolean {
+		const tokens = this._getTokens();
+		const idx = tokens.indexOf(token);
+		if (idx === -1) return false;
+		tokens[idx] = newToken;
+		this._setTokens(tokens);
+		return true;
+	}
+
+	supports(_token: string): boolean {
+		// No validation — all tokens are supported
+		return true;
+	}
+
+	forEach(callback: (value: string, index: number, list: DOMTokenList) => void): void {
+		const tokens = this._getTokens();
+		for (let i = 0; i < tokens.length; i++) {
+			callback(tokens[i], i, this);
+		}
+	}
+
+	keys(): IterableIterator<number> {
+		return this._getTokens().keys();
+	}
+
+	values(): IterableIterator<string> {
+		return this._getTokens().values();
+	}
+
+	entries(): IterableIterator<[number, string]> {
+		return this._getTokens().entries();
+	}
+
+	[Symbol.iterator](): IterableIterator<string> {
+		return this._getTokens().values();
+	}
+
+	toString(): string {
+		return this.value;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return 'DOMTokenList';
+	}
+}