tiny-essentials 1.22.5 → 1.22.7

package/dist/v1/libs/TinyHtml.mjs

@@ -8,6 +8,11 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  * Represents a TinyHtml instance with any constructor element values.
  * @typedef {TinyHtml<ConstructorElValues>} TinyHtmlAny
  */
+/**
+ * Represents the valid values that can be appended to a TinyNode.
+ *
+ * @typedef {TinyNode | TinyNode[] | string | false | null | undefined} AppendCheckerValues
+ */
 /**
  * Callback function used for hover events.
  * @callback HoverEventCallback
@@ -286,6 +291,90 @@ const __elemCollision = {
 class TinyHtml {
     /** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
     static Utils = { ...TinyCollision };
+    /**
+     * Controls whether TinyHtml emits detailed debug output to the console.
+     * When enabled, helper methods print structured diagnostics for easier troubleshooting.
+     * @type {boolean}
+     */
+    static #elemDebug = false;
+    /**
+     * Gets whether debug output is enabled.
+     * @returns {boolean} True if debug output is enabled; otherwise, false.
+     */
+    static get elemDebug() {
+        return TinyHtml.#elemDebug;
+    }
+    /**
+     * Enables or disables debug output.
+     * @param {boolean} value True to enable debug output; false to disable.
+     * @throws {TypeError} Thrown if the provided value is not a boolean.
+     * @returns {void}
+     */
+    static set elemDebug(value) {
+        if (typeof value !== 'boolean')
+            throw new TypeError('Expected a boolean value for elemDebug');
+        TinyHtml.#elemDebug = value;
+    }
+    /**
+     * Logs a standardized debug error for element validation, including a console.table
+     * with the involved elements. Use this when an element argument is invalid, unexpected,
+     * or fails a guard/validation.
+     *
+     * The output includes:
+     *  - A concise error header
+     *  - A stack trace (when supported)
+     *  - A table of elements (index, typeof, constructor, summary, value)
+     *  - The specific problematic element, if provided
+     *
+     * @param {(ConstructorElValues | EventTarget | TinyElement | null)[]} elems
+     *        A list of elements participating in the operation (may include nulls).
+     * @param {ConstructorElValues | EventTarget | TinyElement | null} [elem]
+     *        The specific element that triggered the error, if available.
+     * @returns {void}
+     */
+    static _debugElemError(elems, elem) {
+        if (!TinyHtml.#elemDebug)
+            return;
+        const header = '[TinyHtml Debug] Element validation error';
+        console.groupCollapsed(`${header}${elem ? ' — details below' : ''}`);
+        console.error(header);
+        // Stack trace for call-site visibility
+        if (typeof Error !== 'undefined' && typeof Error.captureStackTrace === 'function') {
+            const err = new Error(header);
+            Error.captureStackTrace(err, TinyHtml._debugElemError);
+            console.error(err.stack);
+        }
+        else {
+            console.trace(header);
+        }
+        // Tabular overview of provided elements
+        if (Array.isArray(elems)) {
+            const rows = elems.map((el, index) => {
+                const typeOf = el === null ? 'null' : typeof el;
+                const ctor = el?.constructor?.name ?? (el === null ? 'null' : 'primitive');
+                const isDomEl = typeof Element !== 'undefined' && el instanceof Element;
+                const summary = isDomEl
+                    ? `${el.tagName?.toLowerCase?.() ?? 'element'}#${el.id || ''}.${String(el.className || '')
+                        .trim()
+                        .replace(/\s+/g, '.')}`
+                    : el && typeof el === 'object' && 'nodeType' in el
+                        ? `nodeType:${ /** @type {any} */(el).nodeType}`
+                        : '';
+                return { index, typeOf, constructor: ctor, summary, value: el };
+            });
+            console.table(rows);
+        }
+        else {
+            console.warn('[TinyHtml Debug] "elems" is not an array:', elems);
+        }
+        // Highlight the specific problematic element, if any
+        if (arguments.length > 1) {
+            console.error('[TinyHtml Debug] Problematic element:', elem);
+            if (elem && typeof elem === 'object')
+                console.dir(elem);
+        }
+        console.groupEnd();
+    }
     /**
      * Parse inline styles into an object.
      * @param {string} styleText
@@ -815,8 +904,10 @@ class TinyHtml {
         if (!(this.#el[index] instanceof Element) &&
             !(this.#el[index] instanceof Window) &&
             !(this.#el[index] instanceof Document) &&
-            !(this.#el[index] instanceof Text))
+            !(this.#el[index] instanceof Text)) {
+            TinyHtml._debugElemError([...this.#el], this.#el[index]);
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+        }
         return this.#el[index];
     }
     /**
@@ -830,8 +921,10 @@ class TinyHtml {
         if (!this.#el.every((el) => el instanceof Element ||
             el instanceof Window ||
             el instanceof Document ||
-            el instanceof Text))
+            el instanceof Text)) {
+            TinyHtml._debugElemError([...this.#el]);
             throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+        }
         return [...this.#el];
     }
     //////////////////////////////////////////////////////
@@ -860,8 +953,10 @@ class TinyHtml {
                         break;
                     }
                 }
-                if (!allowed)
+                if (!allowed) {
+                    TinyHtml._debugElemError([...item], result);
                     throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
+                }
                 results.push(result);
                 return result;
             }));
@@ -888,8 +983,10 @@ class TinyHtml {
         const checkElement = (item) => {
             const elem = item[0];
             const result = elem instanceof TinyHtml ? elem._getElements(where) : [elem];
-            if (result.length > 1)
+            if (result.length > 1) {
+                TinyHtml._debugElemError([...item]);
                 throw new Error(`[TinyHtml] Invalid element amount in ${where}() (Received ${result.length}/1).`);
+            }
             let allowed = false;
             for (const TheTinyElement of TheTinyElements) {
                 if (result[0] instanceof TheTinyElement) {
@@ -901,14 +998,18 @@ class TinyHtml {
                 result[0] = null;
                 allowed = true;
             }
-            if (!allowed)
+            if (!allowed) {
+                TinyHtml._debugElemError([...item], result[0]);
                 throw new Error(`[TinyHtml] Invalid element of the list "${elemName.join(',')}" in ${where}().`);
+            }
             return result[0];
         };
         if (!Array.isArray(elems))
             return checkElement([elems]);
-        if (elems.length > 1)
+        if (elems.length > 1) {
+            TinyHtml._debugElemError([...elems]);
             throw new Error(`[TinyHtml] Invalid element amount in ${where}() (Received ${elems.length}/1).`);
+        }
         return checkElement(elems);
     }
     /**
@@ -1772,13 +1873,17 @@ class TinyHtml {
     /**
      * Normalize and validate nodes before DOM insertion.
      * Converts TinyNode-like structures or strings into DOM-compatible nodes.
-     * @type {(where: string, ...nodes: (TinyNode | TinyNode[] | string)[]) => (Node | string)[]}
+     * @type {(where: string, ...nodes: AppendCheckerValues[]) => (Node | string)[]}
      * @readonly
      */
     static _appendChecker(where, ...nodes) {
         const results = [];
         const nds = [...nodes];
         for (const index in nds) {
+            if (typeof nds[index] === 'undefined' ||
+                nds[index] === null ||
+                nds[index] === false)
+                continue;
             if (typeof nds[index] !== 'string') {
                 results.push(TinyHtml._preNodeElem(nds[index], where));
             }
@@ -1792,7 +1897,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) to receive children.
-     * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+     * @param {...AppendCheckerValues} children - The child elements or text to append.
      * @returns {T}
      */
     static append(el, ...children) {
@@ -1803,7 +1908,7 @@ class TinyHtml {
     /**
      * Appends child elements or strings to the end of the target element(s).
      *
-     * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+     * @param {...AppendCheckerValues} children - The child elements or text to append.
      * @returns {this}
      */
     append(...children) {
@@ -1814,7 +1919,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) to receive children.
-     * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+     * @param {...AppendCheckerValues} children - The child elements or text to prepend.
      * @returns {T}
      */
     static prepend(el, ...children) {
@@ -1825,7 +1930,7 @@ class TinyHtml {
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
-     * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+     * @param {...AppendCheckerValues} children - The child elements or text to prepend.
      * @returns {this}
      */
     prepend(...children) {
@@ -1836,7 +1941,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) before which new content is inserted.
-     * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+     * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
      * @returns {T}
      */
     static before(el, ...children) {
@@ -1847,7 +1952,7 @@ class TinyHtml {
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
-     * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+     * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
      * @returns {this}
      */
     before(...children) {
@@ -1858,7 +1963,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) after which new content is inserted.
-     * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+     * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
      * @returns {T}
      */
     static after(el, ...children) {
@@ -1869,7 +1974,7 @@ class TinyHtml {
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
-     * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+     * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
      * @returns {this}
      */
     after(...children) {
@@ -1880,7 +1985,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The element(s) to be replaced.
-     * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+     * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
      * @returns {T}
      */
     static replaceWith(el, ...newNodes) {
@@ -1891,7 +1996,7 @@ class TinyHtml {
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
-     * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+     * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
      * @returns {this}
      */
     replaceWith(...newNodes) {

package/docs/v1/libs/TinyHtml.md

@@ -19,6 +19,7 @@ This design keeps your code concise while maintaining clarity and control over t
 ## 📑 Table of Contents
 
 - [🧩 Type Definitions – Core Building Blocks](#-type-definitions--core-building-blocks)
+- [🔍 Element Debugging System](#-element-debugging-system)
 - [🔨 Element Creation](#-element-creation)
 - [🔎 Static DOM Selectors](#-static-dom-selectors)
 - [🔍 Element Observer](#-element-observer)
@@ -525,6 +526,110 @@ const __elementCurrentAnimation = new WeakMap();
 
 ---
 
+## 🔍 Element Debugging System
+
+TinyHtml includes a built-in **element debugging system** to help developers identify issues with elements during validation, construction, or event handling.
+
+This feature is **disabled by default** and can be toggled on or off.
+
+---
+
+### ⚙️ Enabling Debug Mode
+
+```js
+TinyHtml.elemDebug = true;  // Enable
+TinyHtml.elemDebug = false; // Disable
+```
+
+#### API
+
+* **`TinyHtml.elemDebug` (boolean)**
+  Controls whether TinyHtml emits detailed debug output to the console.
+
+* **Getter**
+
+  ```js
+  TinyHtml.elemDebug; // Returns true or false
+  ```
+
+* **Setter**
+
+  ```js
+  TinyHtml.elemDebug = true;  // Enable debug logs
+  TinyHtml.elemDebug = false; // Disable debug logs
+  ```
+
+  🚨 Throws `TypeError` if the value is not a boolean.
+
+---
+
+### 🛠 Debugging Invalid Elements
+
+When debug mode is enabled, TinyHtml will log structured information whenever an invalid or unexpected element is passed to its internal operations.
+
+This is done through the internal method:
+
+```js
+TinyHtml._debugElemError(elems, elem);
+```
+
+#### Parameters
+
+* **`elems`** → An array of elements (`ConstructorElValues | EventTarget | TinyElement | null`) involved in the operation.
+* **`elem`** *(optional)* → The specific element that triggered the error.
+
+#### Output Includes
+
+* ❌ **Error header** in the console
+* 🧭 **Stack trace** (with `console.trace` or captured stack)
+* 📊 **`console.table`** showing:
+
+  * Index
+  * `typeof`
+  * Constructor name
+  * Summary (DOM tag, ID, class, or nodeType)
+  * The raw value
+* 🎯 **Problematic element** highlighted separately via `console.dir`
+
+---
+
+### 📋 Example Output
+
+When debug mode is enabled and an invalid element is detected, you may see something like this:
+
+```
+[TinyHtml Debug] Element validation error
+Error: [TinyHtml Debug] Element validation error
+    at TinyHtml._debugElemError (...)
+    at ...
+```
+
+Followed by a **console.table**:
+
+| index | typeOf | constructor | summary            | value         |
+| ----- | ------ | ----------- | ------------------ | ------------- |
+| 0     | object | TinyElement | div#main.container | TinyElement{} |
+| 1     | string | primitive   |                    | "invalid"     |
+| 2     | null   | null        |                    | null          |
+
+And a detailed log of the problematic element:
+
+```
+[TinyHtml Debug] Problematic element:
+<div id="main" class="container">...</div>
+```
+
+---
+
+### ✅ Summary
+
+* 🔧 Enable debug with `TinyHtml.elemDebug = true;`
+* 🐞 Detailed errors are shown only when debug mode is on
+* 📊 Uses `console.table`, `console.error`, and `console.dir` for clarity
+* 🚀 Zero runtime overhead when disabled
+
+---
+
 ## 🔨 Element Creation
 
 ### `TinyHtml.createFrom(tagName, attrs?)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.22.5",
+  "version": "1.22.7",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",