tiny-essentials 1.22.5 → 1.22.6

package/dist/v1/libs/TinyHtml.cjs

@@ -339,6 +339,94 @@ class TinyHtml {
 
   static Utils = { ...collision };
 
+  /**
+   * 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
@@ -943,8 +1031,10 @@ class TinyHtml {
       !(this.#el[index] instanceof Window) &&
       !(this.#el[index] instanceof Document) &&
       !(this.#el[index] instanceof Text)
-    )
+    ) {
+      TinyHtml._debugElemError([...this.#el], this.#el[index]);
       throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+    }
     return this.#el[index];
   }
 
@@ -964,8 +1054,10 @@ class TinyHtml {
           el instanceof Document ||
           el instanceof Text,
       )
-    )
+    ) {
+      TinyHtml._debugElemError([...this.#el]);
       throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
+    }
     return [...this.#el];
   }
 
@@ -998,10 +1090,12 @@ 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;
         }),
@@ -1029,10 +1123,12 @@ 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) {
@@ -1047,17 +1143,21 @@ class TinyHtml {
         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);
   }
 

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

@@ -300,6 +300,42 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
             y: number;
         };
     };
+    /**
+     * Controls whether TinyHtml emits detailed debug output to the console.
+     * When enabled, helper methods print structured diagnostics for easier troubleshooting.
+     * @type {boolean}
+     */
+    static "__#8@#elemDebug": boolean;
+    /**
+     * 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: boolean);
+    /**
+     * Gets whether debug output is enabled.
+     * @returns {boolean} True if debug output is enabled; otherwise, false.
+     */
+    static get elemDebug(): boolean;
+    /**
+     * 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: (ConstructorElValues | EventTarget | TinyElement | null)[], elem?: ConstructorElValues | EventTarget | TinyElement | null, ...args: any[]): void;
     /**
      * Parse inline styles into an object.
      * @param {string} styleText

package/dist/v1/libs/TinyHtml.mjs

@@ -286,6 +286,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 +899,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 +916,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 +948,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 +978,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 +993,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);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.22.5",
+  "version": "1.22.6",
   "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",