tiny-essentials 1.20.0 → 1.20.2

package/dist/v1/libs/TinyHtml.cjs

@@ -225,6 +225,16 @@ 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.
@@ -240,11 +250,221 @@ class TinyHtml {
 
   static Utils = { ...collision };
 
+  /**
+   * 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.
    */
@@ -290,7 +510,8 @@ class TinyHtml {
     }
 
     template.innerHTML = htmlString;
-    if (!(template.content.firstChild instanceof Element)) throw new Error('');
+    if (!(template.content.firstChild instanceof Element))
+      throw new Error('The HTML string must contain a valid HTML element.');
     return new TinyHtml(template.content.firstChild);
   }
 
@@ -322,18 +543,17 @@ 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'));
@@ -356,18 +576,17 @@ 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'));
@@ -377,11 +596,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));
   }
 
   /**
@@ -391,11 +609,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));
   }
 
   /**
@@ -404,7 +621,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(
@@ -419,85 +636,161 @@ 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) {
+  _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[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 instanceof Element) &&
-      !(this.#el instanceof Window) &&
-      !(this.#el instanceof Document)
+      !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;
+    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;
       }
 
@@ -505,7 +798,7 @@ class TinyHtml {
         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]);
     if (elems.length > 1)
@@ -770,11 +1063,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]);
@@ -798,13 +1091,16 @@ 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);
   }
@@ -1648,7 +1944,8 @@ class TinyHtml {
     const elem = TinyHtml._preNodeElem(el, 'insertBefore');
     const targ = TinyHtml._preNodeElem(target, 'insertBefore');
     const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
-    if (!targ.parentNode) throw new Error('');
+    if (!targ.parentNode)
+      throw new Error('The target element has no parent node to insert before.');
     targ.parentNode.insertBefore(elem, childNode || targ);
     return el;
   }
@@ -1676,7 +1973,7 @@ class TinyHtml {
     const elem = TinyHtml._preNodeElem(el, 'insertAfter');
     const targ = TinyHtml._preNodeElem(target, 'insertBefore');
     const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
-    if (!targ.parentNode) throw new Error('');
+    if (!targ.parentNode) throw new Error('The target element has no parent node to insert after.');
     targ.parentNode.insertBefore(elem, childNode || targ.nextSibling);
     return el;
   }
@@ -1728,28 +2025,57 @@ 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;
+    }
   }
 
   /**
@@ -2153,7 +2479,13 @@ class TinyHtml {
     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;
@@ -2163,7 +2495,13 @@ class TinyHtml {
     },
   });
 
-  /** @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]),
   );
@@ -3804,7 +4142,7 @@ class TinyHtml {
   static _getValByType(elem, type, where) {
     if (typeof type !== 'string') 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}().`);
@@ -4345,14 +4683,77 @@ 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
@@ -4362,7 +4763,7 @@ class TinyHtml {
   static attr(el, name) {
     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));
   }
 
   /**
@@ -4386,8 +4787,8 @@ class TinyHtml {
     if (value !== null && typeof value !== 'string')
       throw new TypeError('The "value" must be a string.');
     TinyHtml._preElems(el, 'setAttr').forEach((elem) => {
-      if (value === null) elem.removeAttribute(name);
-      else elem.setAttribute(name, value);
+      if (value === null) elem.removeAttribute(TinyHtml.getAttrName(name));
+      else elem.setAttribute(TinyHtml.getAttrName(name), value);
     });
     return el;
   }
@@ -4410,7 +4811,9 @@ 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;
   }
 
@@ -4432,7 +4835,7 @@ class TinyHtml {
   static hasAttr(el, name) {
     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));
   }
 
   /**
@@ -4454,9 +4857,7 @@ class TinyHtml {
     if (typeof name !== 'string') 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)];
   }
 
   /**
@@ -4478,9 +4879,7 @@ class TinyHtml {
     if (typeof name !== 'string') 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;
   }
@@ -4504,9 +4903,7 @@ class TinyHtml {
     if (typeof name !== 'string') 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;
   }
@@ -4532,9 +4929,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);
       else TinyHtml.removeProp(elem, name);
@@ -4637,14 +5032,14 @@ class TinyHtml {
     }
 
     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('');
-    if (typeof width !== 'number') throw new Error('');
-    if (typeof top !== 'number') throw new Error('');
-    if (typeof bottom !== 'number') throw new Error('');
-    if (typeof left !== 'number') throw new Error('');
-    if (typeof right !== 'number') throw new Error('');
+    if (typeof height !== 'number') throw new Error('extraRect.height must be a number.');
+    if (typeof width !== 'number') throw new Error('extraRect.width must be a number.');
+    if (typeof top !== 'number') throw new Error('extraRect.top must be a number.');
+    if (typeof bottom !== 'number') throw new Error('extraRect.bottom must be a number.');
+    if (typeof left !== 'number') throw new Error('extraRect.left must be a number.');
+    if (typeof right !== 'number') throw new Error('extraRect.right must be a number.');
 
     // @ts-ignore
     result.height += height;