tiny-essentials 1.22.8 → 1.22.10

package/dist/v1/libs/TinyHtml.cjs

@@ -23,7 +23,13 @@ const {
 /**
  * Represents the valid values that can be appended to a TinyNode.
  *
- * @typedef {TinyNode | TinyNode[] | string | false | null | undefined} AppendCheckerValues
+ * @typedef {TinyNode | TinyNode[] | string | false | null | undefined} AppendCheckerTemplate
+ */
+
+/**
+ * Represents the the collection of values that can be appended to a TinyNode.
+ *
+ * @typedef {AppendCheckerTemplate|AppendCheckerTemplate[]} AppendCheckerValues
  */
 
 /**
@@ -1621,12 +1627,12 @@ class TinyHtml {
   }
 
   /**
-   * Return if the element has the target(s).
+   * Returns elements from the current list that contain the given target(s).
    * @param {string|TinyElement|TinyElement[]} target - Selector or DOM element(s).
-   * @returns {boolean} Elements that contain the target.
+   * @returns {Element[]} Elements that contain the target.
    */
   has(target) {
-    return TinyHtml.has(this, target).length > 0;
+    return TinyHtml.has(this, target);
   }
 
   /**
@@ -2148,22 +2154,25 @@ class TinyHtml {
   /**
    * Normalize and validate nodes before DOM insertion.
    * Converts TinyNode-like structures or strings into DOM-compatible nodes.
-   * @type {(where: string, ...nodes: AppendCheckerValues[]) => (Node | string)[]}
+   * @type {(where: string, ...nodes: (AppendCheckerValues|Record<string, AppendCheckerValues>)[]) => (Node | string)[]}
    * @readonly
    */
   static _appendChecker(where, ...nodes) {
+    /** @type {(string | Node)[]} */
     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._preNodeElems(nds[index], where)[0]);
-      } else results.push(nds[index]);
+    for (const item of nodes) {
+      if (typeof item === 'undefined' || item === null || item === false) continue;
+      if (typeof item !== 'string' && typeof item !== 'number') {
+        if (item instanceof Node || item instanceof TinyHtml)
+          results.push(TinyHtml._preNodeElems(item, where)[0]);
+        else if (Array.isArray(item)) results.push(...TinyHtml._appendChecker(where, ...item));
+        else {
+          for (const name in item) {
+            const elems = item[name];
+            results.push(...TinyHtml._appendChecker(where, elems));
+          }
+        }
+      } else results.push(item);
     }
     return results;
   }
@@ -2173,7 +2182,7 @@ class TinyHtml {
    *
    * @template {TinyElement} T
    * @param {T} el - The target element(s) to receive children.
-   * @param {...AppendCheckerValues} children - The child elements or text to append.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
    * @returns {T}
    */
   static append(el, ...children) {
@@ -2185,7 +2194,7 @@ class TinyHtml {
   /**
    * Appends child elements or strings to the end of the target element(s).
    *
-   * @param {...AppendCheckerValues} children - The child elements or text to append.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
    * @returns {this}
    */
   append(...children) {
@@ -2197,7 +2206,7 @@ class TinyHtml {
    *
    * @template {TinyElement} T
    * @param {T} el - The target element(s) to receive children.
-   * @param {...AppendCheckerValues} children - The child elements or text to prepend.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
    * @returns {T}
    */
   static prepend(el, ...children) {
@@ -2209,7 +2218,7 @@ class TinyHtml {
   /**
    * Prepends child elements or strings to the beginning of the target element(s).
    *
-   * @param {...AppendCheckerValues} children - The child elements or text to prepend.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
    * @returns {this}
    */
   prepend(...children) {
@@ -2221,7 +2230,7 @@ class TinyHtml {
    *
    * @template {TinyElement} T
    * @param {T} el - The target element(s) before which new content is inserted.
-   * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
    * @returns {T}
    */
   static before(el, ...children) {
@@ -2233,7 +2242,7 @@ class TinyHtml {
   /**
    * Inserts elements or strings immediately before the target element(s) in the DOM.
    *
-   * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
    * @returns {this}
    */
   before(...children) {
@@ -2245,7 +2254,7 @@ class TinyHtml {
    *
    * @template {TinyElement} T
    * @param {T} el - The target element(s) after which new content is inserted.
-   * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
    * @returns {T}
    */
   static after(el, ...children) {
@@ -2257,7 +2266,7 @@ class TinyHtml {
   /**
    * Inserts elements or strings immediately after the target element(s) in the DOM.
    *
-   * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
    * @returns {this}
    */
   after(...children) {
@@ -2269,7 +2278,7 @@ class TinyHtml {
    *
    * @template {TinyElement} T
    * @param {T} el - The element(s) to be replaced.
-   * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
    * @returns {T}
    */
   static replaceWith(el, ...newNodes) {
@@ -2281,7 +2290,7 @@ class TinyHtml {
   /**
    * Replaces the target element(s) in the DOM with new elements or text.
    *
-   * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+   * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
    * @returns {this}
    */
   replaceWith(...newNodes) {

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

@@ -6,7 +6,11 @@ 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;
+export type AppendCheckerTemplate = TinyNode | TinyNode[] | string | false | null | undefined;
+/**
+ * Represents the the collection of values that can be appended to a TinyNode.
+ */
+export type AppendCheckerValues = AppendCheckerTemplate | AppendCheckerTemplate[];
 /**
  * Callback function used for hover events.
  */
@@ -279,55 +283,7 @@ 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, 
-        /**
-         * 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;
+        areElsCollPerfRight: (rect1: TinyCollision.ObjRect, 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;
@@ -1021,52 +977,52 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {Node[]}
      */
     static clone(el: TinyNode | TinyNode[], deep?: boolean): Node[];
-    static readonly _appendChecker(where: string, ...nodes: AppendCheckerValues[]): (Node | string)[];
+    static readonly _appendChecker(where: string, ...nodes: (AppendCheckerValues | Record<string, 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 {...AppendCheckerValues} children - The child elements or text to append.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
      * @returns {T}
      */
-    static append<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
+    static append<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, 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 {...AppendCheckerValues} children - The child elements or text to prepend.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
      * @returns {T}
      */
-    static prepend<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
+    static prepend<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, 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 {...AppendCheckerValues} children - Elements or text to insert before the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
      * @returns {T}
      */
-    static before<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
+    static before<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, 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 {...AppendCheckerValues} children - Elements or text to insert after the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
      * @returns {T}
      */
-    static after<T extends TinyElement>(el: T, ...children: AppendCheckerValues[]): T;
+    static after<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, 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 {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
      * @returns {T}
      */
-    static replaceWith<T extends TinyElement>(el: T, ...newNodes: AppendCheckerValues[]): T;
+    static replaceWith<T extends TinyElement>(el: T, ...newNodes: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): T;
     /**
      * Appends the given element(s) to each target element in sequence.
      *
@@ -2865,11 +2821,11 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      */
     is(selector: WinnowRequest): boolean;
     /**
-     * Return if the element has the target(s).
+     * Returns elements from the current list that contain the given target(s).
      * @param {string|TinyElement|TinyElement[]} target - Selector or DOM element(s).
-     * @returns {boolean} Elements that contain the target.
+     * @returns {Element[]} Elements that contain the target.
      */
-    has(target: string | TinyElement | TinyElement[]): boolean;
+    has(target: string | TinyElement | TinyElement[]): Element[];
     /**
      * Finds the closest ancestor (including self) that matches the selector.
      *
@@ -2996,38 +2952,38 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
     /**
      * Appends child elements or strings to the end of the target element(s).
      *
-     * @param {...AppendCheckerValues} children - The child elements or text to append.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
      * @returns {this}
      */
-    append(...children: AppendCheckerValues[]): this;
+    append(...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): this;
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
-     * @param {...AppendCheckerValues} children - The child elements or text to prepend.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
      * @returns {this}
      */
-    prepend(...children: AppendCheckerValues[]): this;
+    prepend(...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): this;
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
-     * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
      * @returns {this}
      */
-    before(...children: AppendCheckerValues[]): this;
+    before(...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): this;
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
-     * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
      * @returns {this}
      */
-    after(...children: AppendCheckerValues[]): this;
+    after(...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): this;
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
-     * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
      * @returns {this}
      */
-    replaceWith(...newNodes: AppendCheckerValues[]): this;
+    replaceWith(...newNodes: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): this;
     /**
      * Appends the given element(s) to each target element in sequence.
      *

package/dist/v1/libs/TinyHtml.mjs

@@ -11,7 +11,12 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
 /**
  * Represents the valid values that can be appended to a TinyNode.
  *
- * @typedef {TinyNode | TinyNode[] | string | false | null | undefined} AppendCheckerValues
+ * @typedef {TinyNode | TinyNode[] | string | false | null | undefined} AppendCheckerTemplate
+ */
+/**
+ * Represents the the collection of values that can be appended to a TinyNode.
+ *
+ * @typedef {AppendCheckerTemplate|AppendCheckerTemplate[]} AppendCheckerValues
  */
 /**
  * Callback function used for hover events.
@@ -1400,12 +1405,12 @@ class TinyHtml {
         return TinyHtml._preElems(roots, 'has').filter((root) => targets.some((t) => root && root.contains(t)));
     }
     /**
-     * Return if the element has the target(s).
+     * Returns elements from the current list that contain the given target(s).
      * @param {string|TinyElement|TinyElement[]} target - Selector or DOM element(s).
-     * @returns {boolean} Elements that contain the target.
+     * @returns {Element[]} Elements that contain the target.
      */
     has(target) {
-        return TinyHtml.has(this, target).length > 0;
+        return TinyHtml.has(this, target);
     }
     /**
      * Finds the closest ancestor (including self) that matches the selector.
@@ -1873,22 +1878,29 @@ class TinyHtml {
     /**
      * Normalize and validate nodes before DOM insertion.
      * Converts TinyNode-like structures or strings into DOM-compatible nodes.
-     * @type {(where: string, ...nodes: AppendCheckerValues[]) => (Node | string)[]}
+     * @type {(where: string, ...nodes: (AppendCheckerValues|Record<string, AppendCheckerValues>)[]) => (Node | string)[]}
      * @readonly
      */
     static _appendChecker(where, ...nodes) {
+        /** @type {(string | Node)[]} */
         const results = [];
-        const nds = [...nodes];
-        for (const index in nds) {
-            if (typeof nds[index] === 'undefined' ||
-                nds[index] === null ||
-                nds[index] === false)
+        for (const item of nodes) {
+            if (typeof item === 'undefined' || item === null || item === false)
                 continue;
-            if (typeof nds[index] !== 'string') {
-                results.push(TinyHtml._preNodeElems(nds[index], where)[0]);
+            if (typeof item !== 'string' && typeof item !== 'number') {
+                if (item instanceof Node || item instanceof TinyHtml)
+                    results.push(TinyHtml._preNodeElems(item, where)[0]);
+                else if (Array.isArray(item))
+                    results.push(...TinyHtml._appendChecker(where, ...item));
+                else {
+                    for (const name in item) {
+                        const elems = item[name];
+                        results.push(...TinyHtml._appendChecker(where, elems));
+                    }
+                }
             }
             else
-                results.push(nds[index]);
+                results.push(item);
         }
         return results;
     }
@@ -1897,7 +1909,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) to receive children.
-     * @param {...AppendCheckerValues} children - The child elements or text to append.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
      * @returns {T}
      */
     static append(el, ...children) {
@@ -1908,7 +1920,7 @@ class TinyHtml {
     /**
      * Appends child elements or strings to the end of the target element(s).
      *
-     * @param {...AppendCheckerValues} children - The child elements or text to append.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
      * @returns {this}
      */
     append(...children) {
@@ -1919,7 +1931,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) to receive children.
-     * @param {...AppendCheckerValues} children - The child elements or text to prepend.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
      * @returns {T}
      */
     static prepend(el, ...children) {
@@ -1930,7 +1942,7 @@ class TinyHtml {
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
-     * @param {...AppendCheckerValues} children - The child elements or text to prepend.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
      * @returns {this}
      */
     prepend(...children) {
@@ -1941,7 +1953,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) before which new content is inserted.
-     * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
      * @returns {T}
      */
     static before(el, ...children) {
@@ -1952,7 +1964,7 @@ class TinyHtml {
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
-     * @param {...AppendCheckerValues} children - Elements or text to insert before the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
      * @returns {this}
      */
     before(...children) {
@@ -1963,7 +1975,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The target element(s) after which new content is inserted.
-     * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
      * @returns {T}
      */
     static after(el, ...children) {
@@ -1974,7 +1986,7 @@ class TinyHtml {
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
-     * @param {...AppendCheckerValues} children - Elements or text to insert after the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert after the target.
      * @returns {this}
      */
     after(...children) {
@@ -1985,7 +1997,7 @@ class TinyHtml {
      *
      * @template {TinyElement} T
      * @param {T} el - The element(s) to be replaced.
-     * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
      * @returns {T}
      */
     static replaceWith(el, ...newNodes) {
@@ -1996,7 +2008,7 @@ class TinyHtml {
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
-     * @param {...AppendCheckerValues} newNodes - New elements or text to replace the target.
+     * @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} newNodes - New elements or text to replace the target.
      * @returns {this}
      */
     replaceWith(...newNodes) {

package/package.json

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