tiny-essentials 1.20.0 → 1.20.2

package/dist/v1/libs/TinyHtml.mjs

@@ -186,6 +186,15 @@ const __elemCollision = {
  *
  * @typedef {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement|HTMLOptionElement} InputElement
  */
+/**
+ * Represents a parsed HTML element in JSON-like array form.
+ *
+ * @typedef {[
+ *   tagName: string, // The tag name of the element (e.g., 'div', 'img')
+ *   attributes: Record<string, string>, // All element attributes as key-value pairs
+ *   ...children: (string | HtmlParsed)[] // Text or nested elements
+ * ]} HtmlParsed
+ */
 /**
  * TinyHtml is a utility class that provides static and instance-level methods
  * for precise dimension and position computations on HTML elements.
@@ -199,11 +208,198 @@ const __elemCollision = {
 class TinyHtml {
     /** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
     static Utils = { ...TinyCollision };
+    /**
+     * Fetches an HTML file from the given URL, parses it to JSON.
+     *
+     * @param {string | URL | globalThis.Request} url - The URL of the HTML file.
+     * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+     * @returns {Promise<HtmlParsed[]>} A promise that resolves with the parsed JSON representation of the HTML structure.
+     */
+    static async fetchHtmlFile(url, ops = { method: 'GET' }) {
+        const res = await fetch(url, ops);
+        const contentType = res.headers.get('Content-Type') || '';
+        if (!res.ok)
+            throw new Error(`Failed to fetch: ${res.status} ${res.statusText}`);
+        // Only accept HTML responses
+        if (!contentType.includes('text/html')) {
+            throw new Error(`Invalid content type: ${contentType} (expected text/html)`);
+        }
+        const html = await res.text();
+        return TinyHtml.htmlToJson(html);
+    }
+    /**
+     * Fetches an HTML file from the given URL, parses it to JSON, then converts it to DOM nodes.
+     *
+     * @param {string} url - The URL of the HTML file.
+     * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+     * @returns {Promise<(HTMLElement|Text)[]>} A promise that resolves with the DOM nodes.
+     */
+    static async fetchHtmlNodes(url, ops) {
+        const json = await TinyHtml.fetchHtmlFile(url, ops);
+        return TinyHtml.jsonToNodes(json);
+    }
+    /**
+     * Fetches an HTML file from the given URL, parses it to JSON, then converts it to TinyHtml instances.
+     *
+     * @param {string} url - The URL of the HTML file.
+     * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+     * @returns {Promise<TinyHtml[]>} A promise that resolves with the TinyHtml instances.
+     */
+    static async fetchHtmlTinyElems(url, ops) {
+        const nodes = await TinyHtml.fetchHtmlNodes(url, ops);
+        return TinyHtml.toTinyElm(nodes);
+    }
+    /**
+     * Converts the content of a <template> to an array of HtmlParsed.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {HtmlParsed[]}
+     */
+    static templateToJson(nodes) {
+        return TinyHtml.htmlToJson([...nodes.content.childNodes]
+            .map((node) => node instanceof Element ? node.getHTML() : node instanceof Text ? node.textContent : '')
+            .join(''));
+    }
+    /**
+     * Converts the content of a <template> to real DOM nodes.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {(Element|Text)[]}
+     */
+    static templateToNodes(nodes) {
+        /** @type {(Element|Text)[]} */
+        const result = [];
+        [...nodes.content.cloneNode(true).childNodes].map((node) => {
+            if (!(node instanceof Element) && !(node instanceof Text) && !(node instanceof Comment))
+                throw new Error(`Expected only Element nodes in <template>, but found: ${node.constructor.name}`);
+            if (!(node instanceof Comment))
+                result.push(node);
+        });
+        return result;
+    }
+    /**
+     * Converts the content of a <template> to an array of TinyHtml elements.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {TinyHtml[]}
+     */
+    static templateToTinyElems(nodes) {
+        return TinyHtml.toTinyElm(TinyHtml.templateToNodes(nodes));
+    }
+    /**
+     * Parses a full HTML string into a JSON-like structure.
+     *
+     * @param {string} htmlString - Full HTML markup as a string.
+     * @returns {HtmlParsed[]} An array of parsed HTML elements in structured format.
+     */
+    static htmlToJson(htmlString) {
+        const container = document.createElement('div');
+        container.innerHTML = htmlString.trim();
+        const result = [];
+        /**
+         * @param {Node} el
+         * @returns {*}
+         */
+        const parseElement = (el) => {
+            if (el instanceof Comment)
+                return null;
+            if (el instanceof Text) {
+                const text = el.textContent?.trim();
+                return text ? text : null;
+            }
+            if (!(el instanceof Element))
+                return null;
+            const tag = el.tagName.toLowerCase();
+            /** @type {Record<string, string>} */
+            const props = {};
+            for (const attr of el.attributes) {
+                props[TinyHtml.getPropName(attr.name)] = attr.value;
+            }
+            const children = Array.from(el.childNodes).map(parseElement).filter(Boolean);
+            return children.length > 0 ? [tag, props, ...children] : [tag, props];
+        };
+        for (const child of container.childNodes) {
+            const parsed = parseElement(child);
+            if (parsed)
+                result.push(parsed);
+        }
+        container.innerHTML = '';
+        return result;
+    }
+    /**
+     * Converts a JSON-like HTML structure back to DOM Elements.
+     *
+     * @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
+     * @returns {(HTMLElement|Text)[]} List of DOM nodes.
+     */
+    static jsonToNodes(jsonArray) {
+        /**
+         * @param {HtmlParsed|string} nodeData
+         * @returns {HTMLElement|Text}
+         */
+        const createElement = (nodeData) => {
+            if (typeof nodeData === 'string') {
+                return document.createTextNode(nodeData);
+            }
+            if (!Array.isArray(nodeData))
+                return document.createTextNode('');
+            const [tag, props, ...children] = nodeData;
+            const el = document.createElement(tag);
+            for (const [key, value] of Object.entries(props)) {
+                el.setAttribute(TinyHtml.getAttrName(key), value);
+            }
+            for (const child of children) {
+                const childEl = createElement(child);
+                if (childEl instanceof Comment)
+                    continue;
+                el.appendChild(childEl);
+            }
+            return el;
+        };
+        return jsonArray.map(createElement).filter((node) => !(node instanceof Comment));
+    }
+    /**
+     * Converts a JSON-like HTML structure back to TinyHtml instances.
+     *
+     * @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
+     * @returns {TinyHtml[]} List of TinyHtml instances.
+     */
+    static jsonToTinyElems(jsonArray) {
+        return TinyHtml.toTinyElm(TinyHtml.jsonToNodes(jsonArray));
+    }
+    /**
+     * Creates a new TinyHtml element from a tag name and optional attributes.
+     *
+     * You can alias this method for convenience:
+     * ```js
+     * const createElement = TinyHtml.createFrom;
+     * const myDiv = createElement('div', { class: 'box' });
+     * ```
+     *
+     * @param {string} tagName - The HTML tag name (e.g., 'div', 'span', 'button').
+     * @param {Record<string, string|null>} [attrs] - Optional key-value pairs representing HTML attributes.
+     *                                                If the value is `null`, the attribute will still be set with an empty value.
+     * @returns {TinyHtml} - A new instance of TinyHtml representing the created element.
+     * @throws {TypeError} - If `tagName` is not a string, or `attrs` is not a plain object when defined.
+     */
+    static createFrom(tagName, attrs) {
+        if (typeof tagName !== 'string')
+            throw new TypeError('The "tagName" must be a string.');
+        if (typeof attrs !== 'undefined' && typeof attrs !== 'object')
+            throw new TypeError('The "attrs" must be a object.');
+        const elem = TinyHtml.createElement(tagName);
+        if (typeof attrs === 'object') {
+            for (const attrName in attrs) {
+                elem.setAttr(attrName, attrs[attrName]);
+            }
+        }
+        return elem;
+    }
     /**
      * Creates a new DOM element with the specified tag name and options, then wraps it in a TinyHtml instance.
      *
      * @param {string} tagName - The tag name of the element to create (e.g., 'div', 'span').
-     * @param {ElementCreationOptions} ops - Optional settings for creating the element.
+     * @param {ElementCreationOptions} [ops] - Optional settings for creating the element.
      * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM element.
      * @throws {TypeError} If tagName is not a string or ops is not an object.
      */
@@ -246,7 +442,7 @@ class TinyHtml {
         }
         template.innerHTML = htmlString;
         if (!(template.content.firstChild instanceof Element))
-            throw new Error('');
+            throw new Error('The HTML string must contain a valid HTML element.');
         return new TinyHtml(template.content.firstChild);
     }
     /**
@@ -276,17 +472,16 @@ class TinyHtml {
      *
      * @param {string} selector - A valid CSS selector string.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the matched elements.
      */
     static queryAll(selector, elem = document) {
-        const newEls = elem.querySelectorAll(selector);
-        return TinyHtml.toTinyElm([...newEls]);
+        return new TinyHtml(elem.querySelectorAll(selector));
     }
     /**
      * Queries the element for all elements matching the CSS selector and wraps them in TinyHtml instances.
      *
      * @param {string} selector - A valid CSS selector string.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the matched elements.
      */
     querySelectorAll(selector) {
         return TinyHtml.queryAll(selector, TinyHtml._preElem(this, 'queryAll'));
@@ -308,17 +503,16 @@ class TinyHtml {
      *
      * @param {string} selector - The class name to search for.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     static getByClassName(selector, elem = document) {
-        const newEls = elem.getElementsByClassName(selector);
-        return TinyHtml.toTinyElm([...newEls]);
+        return new TinyHtml(elem.getElementsByClassName(selector));
     }
     /**
      * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
      *
      * @param {string} selector - The class name to search for.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     getElementsByClassName(selector) {
         return TinyHtml.getByClassName(selector, TinyHtml._preElem(this, 'getByClassName'));
@@ -327,11 +521,10 @@ class TinyHtml {
      * Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
      *
      * @param {string} selector - The name attribute to search for.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     static getByName(selector) {
-        const newEls = document.getElementsByName(selector);
-        return TinyHtml.toTinyElm([...newEls]);
+        return new TinyHtml(document.getElementsByName(selector));
     }
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
@@ -340,11 +533,10 @@ class TinyHtml {
      * @param {string} localName - The local name (tag) of the elements to search for.
      * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
      * @param {Document|Element} elem - Target element.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     static getByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml', elem = document) {
-        const newEls = elem.getElementsByTagNameNS(namespaceURI, localName);
-        return TinyHtml.toTinyElm([...newEls]);
+        return new TinyHtml(elem.getElementsByTagNameNS(namespaceURI, localName));
     }
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
@@ -352,7 +544,7 @@ class TinyHtml {
      *
      * @param {string} localName - The local name (tag) of the elements to search for.
      * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
-     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     * @returns {TinyHtml} An array of TinyHtml instances wrapping the found elements.
      */
     getElementsByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml') {
         return TinyHtml.getByTagNameNS(localName, namespaceURI, TinyHtml._preElem(this, 'getByTagNameNS'));
@@ -361,81 +553,150 @@ class TinyHtml {
     /**
      * Returns the current target held by this instance.
      *
+     * @param {number} index - The index of the element to retrieve.
      * @returns {ConstructorElValues} - The instance's target element.
      */
-    get() {
-        return this.#el;
+    get(index) {
+        if (typeof index !== 'number')
+            throw new TypeError('The index must be a number.');
+        if (!this.#el[index])
+            throw new Error(`No element found at index ${index}.`);
+        return this.#el[index];
+    }
+    /**
+     * Extracts a single DOM element from the internal list at the specified index.
+     *
+     * @param {number} index - The index of the element to extract.
+     * @returns {TinyHtml} A new TinyHtml instance wrapping the extracted element.
+     */
+    extract(index) {
+        if (typeof index !== 'number')
+            throw new TypeError('The index must be a number.');
+        if (!this.#el[index])
+            throw new Error(`Cannot extract: no element exists at index ${index}.`);
+        return new TinyHtml(this.#el[index]);
+    }
+    /**
+     * Checks whether the element exists at the given index.
+     *
+     * @param {number} index - The index to check.
+     * @returns {boolean} - True if the element exists; otherwise, false.
+     */
+    exists(index) {
+        if (typeof index !== 'number')
+            throw new TypeError('The index must be a number.');
+        if (!this.#el[index])
+            return false;
+        return true;
+    }
+    /**
+     * Returns the current targets held by this instance.
+     *
+     * @returns {ConstructorElValues[]} - The instance's targets element.
+     */
+    getAll() {
+        return [...this.#el];
     }
     /**
      * Returns the current Element held by this instance.
      *
      * @param {string} where - The method name or context calling this.
+     * @param {number} index - The index of the element to retrieve.
      * @returns {ConstructorElValues} - The instance's element.
      * @readonly
      */
-    _getElement(where) {
-        if (!(this.#el instanceof Element) &&
-            !(this.#el instanceof Window) &&
-            !(this.#el instanceof Document))
+    _getElement(where, index) {
+        if (!(this.#el[index] instanceof Element) &&
+            !(this.#el[index] instanceof Window) &&
+            !(this.#el[index] instanceof Document) &&
+            !(this.#el[index] instanceof Text))
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
-        return this.#el;
+        return this.#el[index];
+    }
+    /**
+     * Returns the current Elements held by this instance.
+     *
+     * @param {string} where - The method name or context calling this.
+     * @returns {ConstructorElValues[]} - The instance's elements.
+     * @readonly
+     */
+    _getElements(where) {
+        if (!this.#el.every((el) => el instanceof Element ||
+            el instanceof Window ||
+            el instanceof Document ||
+            el instanceof Text))
+            throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+        return [...this.#el];
     }
     //////////////////////////////////////////////////////
     /**
-     * @param {TinyElement|EventTarget|null|(TinyElement|EventTarget|null)[]} elems
-     * @param {string} where
-     * @param {any[]} TheTinyElements
-     * @param {string[]} elemName
-     * @returns {any[]}
+     * Prepares and validates multiple elements against allowed types.
+     *
+     * @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input elements to validate.
+     * @param {string} where - The method name or context calling this.
+     * @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
+     * @param {string[]} elemName - The list of expected element names for error reporting.
+     * @returns {any[]} - A flat array of validated elements.
+     * @throws {Error} - If any element is not an instance of one of the allowed types.
      * @readonly
      */
     static _preElemsTemplate(elems, where, TheTinyElements, elemName) {
         /** @param {(TinyElement|EventTarget|null)[]} item */
-        const checkElement = (item) => item.map((elem) => {
-            const result = elem instanceof TinyHtml ? elem._getElement(where) : elem;
-            let allowed = false;
-            for (const TheTinyElement of TheTinyElements) {
-                if (result instanceof TheTinyElement) {
-                    allowed = true;
-                    break;
+        const checkElement = (item) => {
+            /** @type {any[]} */
+            const results = [];
+            item.map((elem) => (elem instanceof TinyHtml ? elem._getElements(where) : [elem]).map((result) => {
+                let allowed = false;
+                for (const TheTinyElement of TheTinyElements) {
+                    if (result instanceof TheTinyElement) {
+                        allowed = true;
+                        break;
+                    }
                 }
-            }
-            if (!allowed)
-                throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
-            return result;
-        });
+                if (!allowed)
+                    throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
+                results.push(result);
+                return result;
+            }));
+            return results;
+        };
         if (!Array.isArray(elems))
             return checkElement([elems]);
         return checkElement(elems);
     }
     /**
-     * @param {TinyElement|EventTarget|null|(TinyElement|EventTarget|null)[]} elems
-     * @param {string} where
-     * @param {any[]} TheTinyElements
-     * @param {string[]} elemName
-     * @param {boolean} [canNull=false]
-     * @returns {any}
+     * Prepares and validates a single element against allowed types.
+     *
+     * @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input element or list to validate.
+     * @param {string} where - The method name or context calling this.
+     * @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
+     * @param {string[]} elemName - The list of expected element names for error reporting.
+     * @param {boolean} [canNull=false] - Whether `null` is allowed as a valid value.
+     * @returns {any} - The validated element or `null` if allowed.
+     * @throws {Error} - If the element is not valid or if multiple elements are provided.
      * @readonly
      */
     static _preElemTemplate(elems, where, TheTinyElements, elemName, canNull = false) {
         /** @param {(TinyElement|EventTarget|null)[]} item */
         const checkElement = (item) => {
             const elem = item[0];
-            let result = elem instanceof TinyHtml ? elem._getElement(where) : elem;
+            const result = elem instanceof TinyHtml ? elem._getElements(where) : [elem];
+            if (result.length > 1)
+                throw new Error(`[TinyHtml] Invalid element amount in ${where}() (Received ${result.length}/1).`);
             let allowed = false;
             for (const TheTinyElement of TheTinyElements) {
-                if (result instanceof TheTinyElement) {
+                if (result[0] instanceof TheTinyElement) {
                     allowed = true;
                     break;
                 }
             }
-            if (canNull && (result === null || typeof result === 'undefined')) {
-                result = null;
+            if (canNull && (result[0] === null || typeof result[0] === 'undefined')) {
+                result[0] = null;
                 allowed = true;
             }
             if (!allowed)
                 throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
-            return result;
+            return result[0];
         };
         if (!Array.isArray(elems))
             return checkElement([elems]);
@@ -662,11 +923,11 @@ class TinyHtml {
      * This ensures consistent access to methods of the `TinyHtml` class regardless
      * of the input form.
      *
-     * @param {TinyElement|TinyElement[]} elems - A single element or an array of elements (DOM or TinyHtml).
+     * @param {TinyElement|Text|(TinyElement|Text)[]} elems - A single element or an array of elements (DOM or TinyHtml).
      * @returns {TinyHtml[]} An array of TinyHtml instances corresponding to the input elements.
      */
     static toTinyElm(elems) {
-        /** @param {TinyElement[]} item */
+        /** @param {(TinyElement|Text)[]} item */
         const checkElement = (item) => item.map((elem) => (!(elem instanceof TinyHtml) ? new TinyHtml(elem) : elem));
         if (!Array.isArray(elems))
             return checkElement([elems]);
@@ -689,8 +950,13 @@ class TinyHtml {
      */
     static fromTinyElm(elems) {
         /** @param {TinyElement[]} item */
-        const checkElement = (item) => item.map((elem) => 
-        /** @type {Element} */ (elem instanceof TinyHtml ? elem._getElement('fromTinyElm') : elem));
+        const checkElement = (item) => {
+            /** @type {Element[]} */
+            const result = [];
+            item.map((elem) => 
+            /** @type {Element[]} */ (elem instanceof TinyHtml ? elem._getElements('fromTinyElm') : [elem]).map((elem) => result.push(elem)));
+            return result;
+        };
         if (!Array.isArray(elems))
             return checkElement([elems]);
         return checkElement(elems);
@@ -1452,7 +1718,7 @@ class TinyHtml {
         const targ = TinyHtml._preNodeElem(target, 'insertBefore');
         const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
         if (!targ.parentNode)
-            throw new Error('');
+            throw new Error('The target element has no parent node to insert before.');
         targ.parentNode.insertBefore(elem, childNode || targ);
         return el;
     }
@@ -1479,7 +1745,7 @@ class TinyHtml {
         const targ = TinyHtml._preNodeElem(target, 'insertBefore');
         const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
         if (!targ.parentNode)
-            throw new Error('');
+            throw new Error('The target element has no parent node to insert after.');
         targ.parentNode.insertBefore(elem, childNode || targ.nextSibling);
         return el;
     }
@@ -1526,23 +1792,48 @@ class TinyHtml {
     //////////////////////////////////////////////////////
     /**
      * The target HTML element for instance-level operations.
-     * @type {ConstructorElValues}
+     * @type {ConstructorElValues[]}
      */
     #el;
+    /**
+     * Returns the number of elements currently stored in the internal element list.
+     *
+     * @returns {number} The total count of elements.
+     */
+    get size() {
+        return this.#el.length;
+    }
     /**
      * Creates an instance of TinyHtml for a specific Element.
      * Useful when you want to operate repeatedly on the same element using instance methods.
-     * @param {ConstructorElValues} el - The element to wrap and manipulate.
+     * @param {ConstructorElValues|ConstructorElValues[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} el - The element to wrap and manipulate.
      */
     constructor(el) {
         if (el instanceof TinyHtml)
             throw new Error(`[TinyHtml] You are trying to put a TinyHtml inside another TinyHtml in constructor.`);
-        if (!(el instanceof Element) &&
-            !(el instanceof Window) &&
-            !(el instanceof Document) &&
-            !(el instanceof Text))
-            throw new Error(`[TinyHtml] Invalid Target in constructor.`);
-        this.#el = el;
+        /** @param {any[]} els */
+        const elCheck = (els) => {
+            if (!els.every((el) => el instanceof Element ||
+                el instanceof Window ||
+                el instanceof Document ||
+                el instanceof Text))
+                throw new Error(`[TinyHtml] Invalid Target in constructor.`);
+        };
+        if (Array.isArray(el)) {
+            elCheck(el);
+            this.#el = el;
+        }
+        else if (el instanceof NodeList || el instanceof HTMLCollection) {
+            const els = [...el];
+            elCheck(els);
+            this.#el = els;
+        }
+        else {
+            const els = [el];
+            elCheck(els);
+            // @ts-ignore
+            this.#el = els;
+        }
     }
     /**
      * Checks whether the given object is a window.
@@ -1932,7 +2223,13 @@ class TinyHtml {
         msTransform: '-ms-transform',
         msTransition: '-ms-transition',
     };
-    /** @type {Record<string | symbol, string>} */
+    /**
+     * Public proxy to manage camelCase ➝ kebab-case CSS property aliasing.
+     *
+     * Modifying this object ensures that the reverse mapping in `cssPropRevAliases` is updated accordingly.
+     *
+     * @type {Record<string | symbol, string>}
+     */
     static cssPropAliases = new Proxy(TinyHtml.#cssPropAliases, {
         set(target, camelCaseKey, kebabValue) {
             target[camelCaseKey] = kebabValue;
@@ -1941,7 +2238,13 @@ class TinyHtml {
             return true;
         },
     });
-    /** @type {Record<string | symbol, string>} */
+    /**
+     * Reverse map of `cssPropAliases`, mapping kebab-case back to camelCase CSS property names.
+     *
+     * This enables consistent bidirectional lookups of style properties.
+     *
+     * @type {Record<string | symbol, string>}
+     */
     static cssPropRevAliases = Object.fromEntries(Object.entries(TinyHtml.#cssPropAliases).map(([camel, kebab]) => [kebab, camel]));
     /**
      * Converts a camelCase string to kebab-case
@@ -3410,7 +3713,7 @@ class TinyHtml {
             throw new TypeError('The "type" must be a string.');
         if (typeof where !== 'string')
             throw new TypeError('The "where" must be a string.');
-        if (!(elem instanceof HTMLInputElement))
+        if (!(elem instanceof HTMLInputElement) && !(elem instanceof HTMLTextAreaElement))
             throw new Error(`Provided element is not an HTMLInputElement in ${where}().`);
         if (typeof TinyHtml._valTypes[type] !== 'function')
             throw new Error(`No handler found for type "${type}" in ${where}().`);
@@ -3923,13 +4226,70 @@ class TinyHtml {
     }
     ///////////////////////////////////////////////////////////////
     /**
-     * Property name normalization similar to jQuery's propFix.
-     * @readonly
+     * Internal property name normalization map (similar to jQuery's `propFix`).
+     * Maps attribute-like names to their JavaScript DOM property equivalents.
+     *
+     * Example: `'for'` ➝ `'htmlFor'`, `'class'` ➝ `'className'`.
+     *
+     * ⚠️ Do not modify this object directly. Use `TinyHtml.propFix` to ensure reverse mapping (`attrFix`) remains in sync.
+     *
+     * @type {Record<string | symbol, string>}
      */
-    static _propFix = {
+    static #propFix = {
         for: 'htmlFor',
         class: 'className',
     };
+    /**
+     * Public proxy for normalized DOM property names.
+     *
+     * Setting a new entry here will also automatically update the reverse map in `TinyHtml.attrFix`.
+     *
+     * @type {Record<string | symbol, string>}
+     */
+    static propFix = new Proxy(TinyHtml.#propFix, {
+        set(target, val1, val2) {
+            target[val1] = val2;
+            // @ts-ignore
+            TinyHtml.attrFix[val2] = val1;
+            return true;
+        },
+    });
+    /**
+     * Reverse map of `propFix`, mapping property names back to their attribute equivalents.
+     *
+     * Used when converting DOM property names into HTML attribute names.
+     *
+     * @type {Record<string | symbol, string>}
+     */
+    static attrFix = Object.fromEntries(Object.entries(TinyHtml.#propFix).map(([val1, val2]) => [val2, val1]));
+    /**
+     * Normalizes an attribute name to its corresponding DOM property name.
+     *
+     * Example: `'class'` ➝ `'className'`, `'for'` ➝ `'htmlFor'`.
+     * If the name is not mapped, it returns the original name.
+     *
+     * @param {string} name - The attribute name to normalize.
+     * @returns {string} - The corresponding property name.
+     */
+    static getPropName(name) {
+        // @ts-ignore
+        const propName = typeof TinyHtml.propFix[name] === 'string' ? TinyHtml.propFix[name] : name;
+        return propName;
+    }
+    /**
+     * Converts a DOM property name back to its corresponding attribute name.
+     *
+     * Example: `'className'` ➝ `'class'`, `'htmlFor'` ➝ `'for'`.
+     * If the name is not mapped, it returns the original name.
+     *
+     * @param {string} name - The property name to convert.
+     * @returns {string} - The corresponding attribute name.
+     */
+    static getAttrName(name) {
+        // @ts-ignore
+        const propName = typeof TinyHtml.attrFix[name] === 'string' ? TinyHtml.attrFix[name] : name;
+        return propName;
+    }
     /**
      * Get an attribute on an element.
      * @param {TinyElement} el
@@ -3940,7 +4300,7 @@ class TinyHtml {
         if (typeof name !== 'string')
             throw new TypeError('The "name" must be a string.');
         const elem = TinyHtml._preElem(el, 'attr');
-        return elem.getAttribute(name);
+        return elem.getAttribute(TinyHtml.getAttrName(name));
     }
     /**
      * Get an attribute on an element.
@@ -3964,9 +4324,9 @@ class TinyHtml {
             throw new TypeError('The "value" must be a string.');
         TinyHtml._preElems(el, 'setAttr').forEach((elem) => {
             if (value === null)
-                elem.removeAttribute(name);
+                elem.removeAttribute(TinyHtml.getAttrName(name));
             else
-                elem.setAttribute(name, value);
+                elem.setAttribute(TinyHtml.getAttrName(name), value);
         });
         return el;
     }
@@ -3988,7 +4348,7 @@ class TinyHtml {
     static removeAttr(el, name) {
         if (typeof name !== 'string')
             throw new TypeError('The "name" must be a string.');
-        TinyHtml._preElems(el, 'removeAttr').forEach((elem) => elem.removeAttribute(name));
+        TinyHtml._preElems(el, 'removeAttr').forEach((elem) => elem.removeAttribute(TinyHtml.getAttrName(name)));
         return el;
     }
     /**
@@ -4009,7 +4369,7 @@ class TinyHtml {
         if (typeof name !== 'string')
             throw new TypeError('The "name" must be a string.');
         const elem = TinyHtml._preElem(el, 'hasAttr');
-        return elem.hasAttribute(name);
+        return elem.hasAttribute(TinyHtml.getAttrName(name));
     }
     /**
      * Check if an attribute exists on an element.
@@ -4030,9 +4390,7 @@ class TinyHtml {
             throw new TypeError('The "name" must be a string.');
         const elem = TinyHtml._preElem(el, 'hasProp');
         // @ts-ignore
-        const propName = TinyHtml._propFix[name] || name;
-        // @ts-ignore
-        return !!elem[propName];
+        return !!elem[TinyHtml.getPropName(name)];
     }
     /**
      * Check if a property exists.
@@ -4053,9 +4411,7 @@ class TinyHtml {
             throw new TypeError('The "name" must be a string.');
         TinyHtml._preElems(el, 'addProp').forEach((elem) => {
             // @ts-ignore
-            name = TinyHtml._propFix[name] || name;
-            // @ts-ignore
-            elem[name] = true;
+            elem[TinyHtml.getPropName(name)] = true;
         });
         return el;
     }
@@ -4078,9 +4434,7 @@ class TinyHtml {
             throw new TypeError('The "name" must be a string.');
         TinyHtml._preElems(el, 'removeProp').forEach((elem) => {
             // @ts-ignore
-            name = TinyHtml._propFix[name] || name;
-            // @ts-ignore
-            elem[name] = false;
+            elem[TinyHtml.getPropName(name)] = false;
         });
         return el;
     }
@@ -4105,9 +4459,7 @@ class TinyHtml {
             throw new TypeError('The "force" must be a boolean.');
         TinyHtml._preElems(el, 'toggleProp').forEach((elem) => {
             // @ts-ignore
-            const propName = TinyHtml._propFix[name] || name;
-            // @ts-ignore
-            const shouldEnable = force === undefined ? !elem[propName] : force;
+            const shouldEnable = force === undefined ? !elem[TinyHtml.getPropName(name)] : force;
             // @ts-ignore
             if (shouldEnable)
                 TinyHtml.addProp(elem, name);
@@ -4200,20 +4552,20 @@ class TinyHtml {
                 result[name] = rect[name];
         }
         if (typeof extraRect !== 'object' || extraRect === null || Array.isArray(extraRect))
-            throw new Error('');
+            throw new Error('extraRect must be a non-null object.');
         const { height = 0, width = 0, top = 0, bottom = 0, left = 0, right = 0 } = extraRect;
         if (typeof height !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.height must be a number.');
         if (typeof width !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.width must be a number.');
         if (typeof top !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.top must be a number.');
         if (typeof bottom !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.bottom must be a number.');
         if (typeof left !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.left must be a number.');
         if (typeof right !== 'number')
-            throw new Error('');
+            throw new Error('extraRect.right must be a number.');
         // @ts-ignore
         result.height += height;
         // @ts-ignore