tiny-essentials 1.22.5 → 1.22.7

package/dist/v1/libs/TinyHtml.cjs

@@ -20,6 +20,12 @@ const {
  * @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
@@ -339,6 +345,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 +1037,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 +1060,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 +1096,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 +1129,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 +1149,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);
   }
 
@@ -2042,13 +2148,19 @@ 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));
       } else results.push(nds[index]);
@@ -2061,7 +2173,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) {
@@ -2073,7 +2185,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) {
@@ -2085,7 +2197,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) {
@@ -2097,7 +2209,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) {
@@ -2109,7 +2221,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) {
@@ -2121,7 +2233,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) {
@@ -2133,7 +2245,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) {
@@ -2145,7 +2257,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) {
@@ -2157,7 +2269,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) {
@@ -2169,7 +2281,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/dist/v1/libs/TinyHtml.d.mts

@@ -3,6 +3,10 @@ export default TinyHtml;
  * Represents a TinyHtml instance with any constructor element values.
  */
 export type TinyHtmlAny = TinyHtml<ConstructorElValues>;
+/**
+ * Represents the valid values that can be appended to a TinyNode.
+ */
+export type AppendCheckerValues = TinyNode | TinyNode[] | string | false | null | undefined;
 /**
  * Callback function used for hover events.
  */
@@ -275,7 +279,55 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
         areElsCollPerfTop: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsCollPerfBottom: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsCollPerfLeft: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
-        areElsCollPerfRight: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
+        areElsCollPerfRight: (rect1: TinyCollision.ObjRect, 
+        /**
+         * Represents a value that can be either a DOM Element, or the document object.
+         * Useful for functions that operate generically on measurable targets.
+         *
+         * @typedef {Element|Document} ElementWithDoc
+         */
+        /**
+         * A parameter type used for filtering or matching elements.
+         * It can be:
+         * - A string (CSS selector),
+         * - A raw DOM element,
+         * - An array of raw DOM elements,
+         * - A filtering function that receives an index and element,
+         *   and returns true if it matches.
+         *
+         * @typedef {string|Element|Element[]|((index: number, el: Element) => boolean)} WinnowRequest
+         */
+        /**
+         * Elements accepted as constructor values for TinyHtml.
+         * These include common DOM elements and root containers.
+         *
+         * @typedef {Window|Element|Document|Text} ConstructorElValues
+         */
+        /**
+         * Options passed to `addEventListener` or `removeEventListener`.
+         * Can be a boolean or an object of type `AddEventListenerOptions`.
+         *
+         * @typedef {boolean|AddEventListenerOptions} EventRegistryOptions
+         */
+        /**
+         * Structure describing a registered event callback and its options.
+         *
+         * @typedef {Object} EventRegistryItem
+         * @property {EventListenerOrEventListenerObject|null} handler - The function to be executed when the event is triggered.
+         * @property {EventRegistryOptions} [options] - Optional configuration passed to the listener.
+         */
+        /**
+         * Maps event names (e.g., `"click"`, `"keydown"`) to a list of registered handlers and options.
+         *
+         * @typedef {Record<string, EventRegistryItem[]>} EventRegistryList
+         */
+        /**
+         * WeakMap storing all event listeners per element.
+         * Each element has a registry mapping event names to their handler lists.
+         *
+         * @type {WeakMap<ConstructorElValues|EventTarget, EventRegistryList>}
+         */
+        rect2: TinyCollision.ObjRect) => boolean;
         areElsColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsPerfColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         getElsColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => string | null;
@@ -300,6 +352,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
@@ -933,52 +1021,52 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {Node[]}
      */
     static clone(el: TinyNode | TinyNode[], deep?: boolean): Node[];
-    static readonly _appendChecker(where: string, ...nodes: (TinyNode | TinyNode[] | string)[]): (Node | string)[];
+    static readonly _appendChecker(where: string, ...nodes: AppendCheckerValues[]): (Node | string)[];
     /**
      * Appends child elements or strings to the end of the target element(s).
      *
      * @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<T extends TinyElement>(el: T, ...children: (TinyNode | TinyNode[] | string)[]): T;
+    static append<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
      * @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<T extends TinyElement>(el: T, ...children: (TinyNode | TinyNode[] | string)[]): T;
+    static prepend<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
      * @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<T extends TinyElement>(el: T, ...children: (TinyNode | TinyNode[] | string)[]): T;
+    static before<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
      * @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<T extends TinyElement>(el: T, ...children: (TinyNode | TinyNode[] | string)[]): T;
+    static after<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
      * @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<T extends TinyElement>(el: T, ...newNodes: (TinyNode | TinyNode[] | string)[]): T;
+    static replaceWith<T extends TinyElement>(el: T, ...newNodes: AppendCheckerValues[]): T;
     /**
      * Appends the given element(s) to each target element in sequence.
      *
@@ -2908,38 +2996,38 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
     /**
      * 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: (TinyNode | TinyNode[] | string)[]): this;
+    append(...children: AppendCheckerValues[]): this;
     /**
      * 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: (TinyNode | TinyNode[] | string)[]): this;
+    prepend(...children: AppendCheckerValues[]): this;
     /**
      * 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: (TinyNode | TinyNode[] | string)[]): this;
+    before(...children: AppendCheckerValues[]): this;
     /**
      * 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: (TinyNode | TinyNode[] | string)[]): this;
+    after(...children: AppendCheckerValues[]): this;
     /**
      * 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: (TinyNode | TinyNode[] | string)[]): this;
+    replaceWith(...newNodes: AppendCheckerValues[]): this;
     /**
      * Appends the given element(s) to each target element in sequence.
      *