tiny-essentials 1.22.6 → 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
@@ -2142,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]);
@@ -2161,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) {
@@ -2173,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) {
@@ -2185,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) {
@@ -2197,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) {
@@ -2209,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) {
@@ -2221,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) {
@@ -2233,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) {
@@ -2245,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) {
@@ -2257,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) {
@@ -2269,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;
@@ -969,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.
      *
@@ -2944,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.
      *

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
@@ -1868,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));
             }
@@ -1888,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) {
@@ -1899,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) {
@@ -1910,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) {
@@ -1921,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) {
@@ -1932,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) {
@@ -1943,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) {
@@ -1954,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) {
@@ -1965,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) {
@@ -1976,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) {
@@ -1987,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.6",
+  "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",