tiny-essentials 1.20.0 → 1.20.2

package/dist/v1/libs/TinyHtml.d.mts

@@ -153,6 +153,12 @@ export type SetValueList = SetValueBase | SetValueBase[];
  * Includes common input types used in forms.
  */
 export type InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement;
+/**
+ * Represents a parsed HTML element in JSON-like array form.
+ */
+export type HtmlParsed = [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)[]];
 /**
  * Possible directions from which a collision was detected and locked.
  *
@@ -183,6 +189,15 @@ export type InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaEl
  *
  * @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.
@@ -236,6 +251,15 @@ declare class TinyHtml {
          *
          * @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.
@@ -248,6 +272,15 @@ declare class TinyHtml {
          */
         rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => string | null;
         getElsPerfColliding: (rect1: TinyCollision.ObjRect /**
+         * 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.
          * It mimics some jQuery functionalities while using native browser APIs.
@@ -256,7 +289,8 @@ declare class TinyHtml {
          * and offset utilities. This class serves as a lightweight alternative using modern DOM APIs.
          *
          * @class
-         */, rect2: TinyCollision.ObjRect) => "top" | "bottom" | "left" | "right" | null;
+         */
+        , rect2: TinyCollision.ObjRect) => "top" | "bottom" | "left" | "right" | null;
         getElsCollOverlap: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => {
             overlapLeft: number;
             overlapRight: number;
@@ -277,15 +311,97 @@ declare class TinyHtml {
             y: number;
         };
     };
+    /**
+     * 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 fetchHtmlFile(url: string | URL | globalThis.Request, ops?: RequestInit): Promise<HtmlParsed[]>;
+    /**
+     * 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 fetchHtmlNodes(url: string, ops?: RequestInit): Promise<(HTMLElement | Text)[]>;
+    /**
+     * 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 fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise<TinyHtml[]>;
+    /**
+     * Converts the content of a <template> to an array of HtmlParsed.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {HtmlParsed[]}
+     */
+    static templateToJson(nodes: HTMLTemplateElement): HtmlParsed[];
+    /**
+     * Converts the content of a <template> to real DOM nodes.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {(Element|Text)[]}
+     */
+    static templateToNodes(nodes: HTMLTemplateElement): (Element | Text)[];
+    /**
+     * Converts the content of a <template> to an array of TinyHtml elements.
+     *
+     * @param {HTMLTemplateElement} nodes
+     * @returns {TinyHtml[]}
+     */
+    static templateToTinyElems(nodes: HTMLTemplateElement): TinyHtml[];
+    /**
+     * 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: string): HtmlParsed[];
+    /**
+     * 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: HtmlParsed[]): (HTMLElement | Text)[];
+    /**
+     * 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: HtmlParsed[]): TinyHtml[];
+    /**
+     * 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: string, attrs?: Record<string, string | null>): TinyHtml;
     /**
      * 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.
      */
-    static createElement(tagName: string, ops: ElementCreationOptions): TinyHtml;
+    static createElement(tagName: string, ops?: ElementCreationOptions): TinyHtml;
     /**
      * Creates a new TinyHtml instance that wraps a DOM TextNode.
      *
@@ -319,9 +435,9 @@ declare 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: string, elem?: Document | Element): TinyHtml[];
+    static queryAll(selector: string, elem?: Document | Element): TinyHtml;
     /**
      * Retrieves an element by its ID and wraps it in a TinyHtml instance.
      *
@@ -334,16 +450,16 @@ declare 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: string, elem?: Document | Element): TinyHtml[];
+    static getByClassName(selector: string, elem?: Document | Element): 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: string): TinyHtml[];
+    static getByName(selector: string): TinyHtml;
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
      * and wraps them in TinyHtml instances.
@@ -351,25 +467,31 @@ declare 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: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml[];
+    static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml;
     /**
-     * @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 readonly _preElemsTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[]): any[];
     /**
-     * @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 readonly _preElemTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[], canNull?: boolean): any;
@@ -554,10 +676,10 @@ declare 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: TinyElement | TinyElement[]): TinyHtml[];
+    static toTinyElm(elems: TinyElement | Text | (TinyElement | Text)[]): TinyHtml[];
     /**
      * Extracts native `Element` instances from one or more elements,
      * which can be either raw DOM elements or wrapped in `TinyHtml`.
@@ -941,9 +1063,21 @@ declare class TinyHtml {
      * @type {Record<string | symbol, string>}
      */
     static "__#6@#cssPropAliases": Record<string | symbol, string>;
-    /** @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: Record<string | symbol, string>;
-    /** @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: Record<string | symbol, string>;
     /**
      * Converts a camelCase string to kebab-case
@@ -1629,13 +1763,52 @@ declare class TinyHtml {
      */
     static trigger(el: TinyEventTarget | TinyEventTarget[], event: string, payload?: Event | CustomEvent | CustomEventInit): TinyEventTarget | TinyEventTarget[];
     /**
-     * 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 readonly _propFix: {
-        for: string;
-        class: string;
-    };
+    static "__#6@#propFix": Record<string | symbol, string>;
+    /**
+     * 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: Record<string | symbol, string>;
+    /**
+     * 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: Record<string | symbol, string>;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string): string;
     /**
      * Get an attribute on an element.
      * @param {TinyElement} el
@@ -1833,9 +2006,9 @@ declare class TinyHtml {
     /**
      * 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: ConstructorElValues);
+    constructor(el: ConstructorElValues | ConstructorElValues[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement>);
     /**
      * Queries the element for the first element matching the CSS selector and wraps it in a TinyHtml instance.
      *
@@ -1847,39 +2020,69 @@ declare class TinyHtml {
      * 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: string): TinyHtml[];
+    querySelectorAll(selector: string): TinyHtml;
     /**
      * 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: string): TinyHtml[];
+    getElementsByClassName(selector: string): TinyHtml;
     /**
      * Retrieves all elements with the specified local tag name within the given namespace URI,
      * and wraps them in TinyHtml instances.
      *
      * @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: string, namespaceURI?: string | null): TinyHtml[];
+    getElementsByTagNameNS(localName: string, namespaceURI?: string | null): 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(): ConstructorElValues;
+    get(index: number): ConstructorElValues;
+    /**
+     * 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: number): TinyHtml;
+    /**
+     * 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: number): boolean;
+    /**
+     * Returns the current targets held by this instance.
+     *
+     * @returns {ConstructorElValues[]} - The instance's targets element.
+     */
+    getAll(): ConstructorElValues[];
     /**
      * 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
      */
-    readonly _getElement(where: string): ConstructorElValues;
+    readonly _getElement(where: string, index: number): ConstructorElValues;
+    /**
+     * 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
+     */
+    readonly _getElements(where: string): ConstructorElValues[];
     /**
      * Returns only the elements **not** matching the given selector or function.
      *
@@ -2094,6 +2297,12 @@ declare class TinyHtml {
      * @returns {TinyNode|TinyNode[]}
      */
     replaceAll(targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
+    /**
+     * Returns the number of elements currently stored in the internal element list.
+     *
+     * @returns {number} The total count of elements.
+     */
+    get size(): number;
     /**
      * Returns the full computed CSS styles for the given element.
      *