tiny-essentials 1.20.1 → 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,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/docs/v1/basics/html.md

@@ -142,11 +142,11 @@ saveJsonFile('yasmin.json', data);
 
 ### 🌐 `fetchTemplate(...)`
 
-Loads data from a remote URL using Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
+Loads data from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
 #### 📥 Parameters
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
+* `url` *(string)*: The full URL to fetch from (must start with `http://`, `https://`, `/`, `./`, or `../`).
 * `options` *(object)* *(optional)*:
 
   * `signal` *(`AbortSignal` | `null`)*: Custom abort signal.
@@ -156,42 +156,88 @@ Loads data from a remote URL using Fetch API, with support for custom HTTP metho
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
 
-#### `fetchJson(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+#### `fetchJson(url, options?)`
 
-Loads and parses a JSON.
+Loads and parses a remote JSON file.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `options` *(object)* *(optional)*:
+* **Parameters**:
 
-#### `fetchBlob(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+  * `url` *(string)*: URL to fetch the JSON from.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
 
-Loads a remote file as a Blob.
+* **Returns**:
+  `Promise<any[] | Record<string | number | symbol, unknown>>` — The parsed JSON data.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `allowedMimeTypes` Optional list of accepted MIME types (e.g., ['image/jpeg']).
-* `options` *(object)* *(optional)*:
+* **Throws**:
 
-##### `signal` (`AbortSignal` | `null`) — *optional*
+  * `Error` if the fetch fails, times out, or returns invalid JSON.
+  * `Error` if the `Content-Type` is not `application/json`.
 
-Custom abort signal. If set:
+---
 
-* The internal timeout mechanism is **disabled**
-* Retry logic is **disabled**
-* Abortion is handled externally
+#### `fetchBlob(url, allowedMimeTypes?, options?)`
 
-#### 📤 Returns
+Loads a remote file as a Blob object.
+
+* **Parameters**:
+
+  * `url` *(string)*: URL of the remote file.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<Blob>`
+
+* **Throws**:
+
+  * `Error` if fetch fails or the MIME type is not allowed.
+  * `Error` if the response is not OK.
+
+---
+
+#### `fetchText(url, allowedMimeTypes?, options?)`
+
+Loads a remote file as **plain text** using the Fetch API.
+
+* **Parameters**:
+
+  * `url` *(string)*: Full URL of the file to fetch.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types (e.g., `['text/plain']`).
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<string>` — The content of the file as a text string.
+
+* **Throws**:
 
-* `Promise<any>`: Resolves with the parsed JSON data.
+  * `Error` if the fetch fails or the response is not OK.
+  * `Error` if the MIME type is not in the allowed list (when provided).
+
+---
+
+#### 📤 Returns (for all helpers)
+
+* `Promise<any>` — Depends on the function:
+
+  * `fetchJson`: Parsed JSON
+  * `fetchBlob`: File as a Blob
+  * `fetchText`: File as plain text
+
+---
 
 #### ⚠️ Throws
 
-* `Error` if the fetch fails or exceeds the timeout
-* `Error` if the response is not `application/json`
-* `Error` if the result is not a plain JSON object
+All functions may throw the following:
+
+* `Error` if the request fails or the response times out.
+* `Error` if `Content-Type` does not match expected type (JSON, Blob, Text, etc).
+* `Error` if response is malformed or rejected by MIME type filter.
+
+---
 
 #### 🧠 Tip
 
-If you pass your own `signal`, this disables both `timeout` and `retries`. Use it when you're managing cancellation manually (e.g. in UI components or async workflows).
+Using a custom `signal` disables both `timeout` and `retries`. This is useful when you want to handle cancellation yourself, like in user interfaces or abortable workflows.
 
 #### 🧪 Example
 
@@ -210,6 +256,16 @@ const data = await fetchJson('https://api.example.com/data', {
 });
 ```
 
+```js
+const text = await fetchText('/example.txt', ['text/plain'], {
+  timeout: 3000,
+});
+```
+
+```js
+const blob = await fetchBlob('/image.jpg', ['image/jpeg']);
+```
+
 ---
 
 ### 📦 `HtmlElBoxSides` Type

package/docs/v1/basics/simpleMath.md

@@ -36,19 +36,37 @@ ruleOfThree(2, 6, 3, true); // → 4
 
 ### 💯 `getSimplePerc(price, percentage)`
 
-**Calculates the percentage of a given base value.**
+**Calculates the actual value that corresponds to a percentage of a base number.**
 
-- **`price`**: The base value (for example, the original price of an item).
-- **`percentage`**: The percentage to calculate from the base value.
+Unlike `getPercentage`, which tells how much something represents in percent,  
+this function tells how much a given percentage *is worth* in actual value.
 
-#### Example:
+- **`price`**: The base number to apply the percentage to.  
+- **`percentage`**: The percentage to calculate from the base.
 
+#### Example:
 ```js
 getSimplePerc(200, 15); // → 30
 ```
 
 ---
 
+### 📊 `getPercentage(part, total)`
+
+**Calculates how much percent a partial value represents of the total value.**
+
+This function is useful when you want to know what fraction of the total a value is, in percentage form.
+
+- **`part`**: The partial value to compare.  
+- **`total`**: The total or maximum value.
+
+#### Example:
+```js
+getPercentage(5, 100); // → 5
+```
+
+---
+
 ### 🎂 `getAge(timeData, now)`
 
 **Calculates the age based on a birthdate.**