tiny-essentials 1.20.1 → 1.20.3

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,6 +311,72 @@ 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.
      *
@@ -576,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`.
@@ -2197,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.
      *

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,6 +208,165 @@ 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.
      *
@@ -440,7 +608,8 @@ class TinyHtml {
     _getElement(where, index) {
         if (!(this.#el[index] instanceof Element) &&
             !(this.#el[index] instanceof Window) &&
-            !(this.#el[index] instanceof Document))
+            !(this.#el[index] instanceof Document) &&
+            !(this.#el[index] instanceof Text))
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
         return this.#el[index];
     }
@@ -452,7 +621,10 @@ class TinyHtml {
      * @readonly
      */
     _getElements(where) {
-        if (!this.#el.every((el) => el instanceof Element || el instanceof Window || el instanceof Document))
+        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];
     }
@@ -751,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]);
@@ -1623,6 +1795,14 @@ class TinyHtml {
      * @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.

package/dist/v1/libs/TinySmartScroller.cjs

@@ -275,6 +275,11 @@ class TinySmartScroller {
   /** @type {null|EventListenerOrEventListenerObject} */
   #handler = null;
 
+  #isPastAtBottom = false;
+  #isPastAtTop = false;
+  #isPastAtCustomTop = false;
+  #isPastAtCustomBottom = false;
+
   #isAtBottom = false;
   #isAtTop = false;
   #isAtCustomTop = false;
@@ -639,6 +644,12 @@ class TinySmartScroller {
     else if (atCustomTop) atCustomResult = 'top';
     else if (atCustomBottom) atCustomResult = 'bottom';
 
+    this.#isPastAtTop = this.#isAtTop ?? false;
+    this.#isPastAtBottom = this.#isAtBottom ?? false;
+
+    this.#isPastAtCustomTop = this.#isAtCustomTop ?? false;
+    this.#isPastAtCustomBottom = this.#isAtCustomBottom ?? false;
+
     this.#isAtTop = atTop;
     this.#isAtBottom = atBottom;
 
@@ -968,6 +979,79 @@ class TinySmartScroller {
    *
    * @returns {boolean}
    */
+  isAtCustomBottom() {
+    return this.#isAtCustomBottom;
+  }
+
+  /**
+   * Checks if the user is within the defined extra scroll boundary from the top.
+   *
+   * @returns {boolean}
+   */
+  isAtCustomTop() {
+    return this.#isAtCustomTop;
+  }
+
+  /**
+   * Returns true if the user is currently scrolled to the bottom of the element.
+   *
+   * @returns {boolean}
+   */
+  isAtBottom() {
+    return this.#isAtBottom;
+  }
+
+  /**
+   * Returns true if the user is currently scrolled to the top of the element.
+   *
+   * @returns {boolean}
+   */
+  isAtTop() {
+    return this.#isAtTop;
+  }
+
+  /**
+   * Returns true if the user has already passed beyond the bottom boundary at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtBottom() {
+    return this.#isPastAtBottom;
+  }
+
+  /**
+   * Returns true if the user has already passed beyond the top boundary at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtTop() {
+    return this.#isPastAtTop;
+  }
+
+  /**
+   * Returns true if the user has passed beyond the defined extra scroll boundary from the top at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtCustomTop() {
+    return this.#isPastAtCustomTop;
+  }
+
+  /**
+   * Returns true if the user has passed beyond the defined extra scroll boundary from the bottom at some point.
+   *
+   * @returns {boolean}
+   */
+  isPastAtCustomBottom() {
+    return this.#isPastAtCustomBottom;
+  }
+
+  /**
+   * Checks if the user is within the defined extra scroll boundary from the bottom.
+   *
+   * @returns {boolean}
+   * @deprecated - Use isAtCustomBottom instead.
+   */
   isUserAtCustomBottom() {
     return this.#isAtCustomBottom;
   }
@@ -976,6 +1060,7 @@ class TinySmartScroller {
    * Checks if the user is within the defined extra scroll boundary from the top.
    *
    * @returns {boolean}
+   * @deprecated - Use isAtCustomTop instead.
    */
   isUserAtCustomTop() {
     return this.#isAtCustomTop;
@@ -985,6 +1070,7 @@ class TinySmartScroller {
    * Returns true if the user is currently scrolled to the bottom of the element.
    *
    * @returns {boolean}
+   * @deprecated - Use isAtBottom instead.
    */
   isUserAtBottom() {
     return this.#isAtBottom;
@@ -994,6 +1080,7 @@ class TinySmartScroller {
    * Returns true if the user is currently scrolled to the top of the element.
    *
    * @returns {boolean}
+   * @deprecated - Use isAtTop instead.
    */
   isUserAtTop() {
     return this.#isAtTop;

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

@@ -515,23 +515,75 @@ declare class TinySmartScroller {
      *
      * @returns {boolean}
      */
+    isAtCustomBottom(): boolean;
+    /**
+     * Checks if the user is within the defined extra scroll boundary from the top.
+     *
+     * @returns {boolean}
+     */
+    isAtCustomTop(): boolean;
+    /**
+     * Returns true if the user is currently scrolled to the bottom of the element.
+     *
+     * @returns {boolean}
+     */
+    isAtBottom(): boolean;
+    /**
+     * Returns true if the user is currently scrolled to the top of the element.
+     *
+     * @returns {boolean}
+     */
+    isAtTop(): boolean;
+    /**
+     * Returns true if the user has already passed beyond the bottom boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtBottom(): boolean;
+    /**
+     * Returns true if the user has already passed beyond the top boundary at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtTop(): boolean;
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the top at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomTop(): boolean;
+    /**
+     * Returns true if the user has passed beyond the defined extra scroll boundary from the bottom at some point.
+     *
+     * @returns {boolean}
+     */
+    isPastAtCustomBottom(): boolean;
+    /**
+     * Checks if the user is within the defined extra scroll boundary from the bottom.
+     *
+     * @returns {boolean}
+     * @deprecated - Use isAtCustomBottom instead.
+     */
     isUserAtCustomBottom(): boolean;
     /**
      * Checks if the user is within the defined extra scroll boundary from the top.
      *
      * @returns {boolean}
+     * @deprecated - Use isAtCustomTop instead.
      */
     isUserAtCustomTop(): boolean;
     /**
      * Returns true if the user is currently scrolled to the bottom of the element.
      *
      * @returns {boolean}
+     * @deprecated - Use isAtBottom instead.
      */
     isUserAtBottom(): boolean;
     /**
      * Returns true if the user is currently scrolled to the top of the element.
      *
      * @returns {boolean}
+     * @deprecated - Use isAtTop instead.
      */
     isUserAtTop(): boolean;
     /**