tiny-essentials 1.22.11 → 1.22.12

package/dist/v1/libs/TinyHtml.cjs

@@ -335,6 +335,21 @@ const __elemCollision = {
 
 // TITLE: Class Intro
 
+/**
+ * Represents all possible inputs accepted by the TinyHtml constructor.
+ * Can be a single element, an array of elements, array-like DOM collections,
+ * or a CSS selector string.
+ *
+ * @typedef {(
+ *   ConstructorElValues |
+ *   ConstructorElValues[] |
+ *   NodeListOf<Element> |
+ *   HTMLCollectionOf<Element> |
+ *   NodeListOf<HTMLElement> |
+ *   string
+ * )} TinyHtmlConstructor
+ */
+
 /**
  * TinyHtml is a utility class that provides static and instance-level methods
  * for precise dimension and position computations on HTML elements.
@@ -343,7 +358,7 @@ const __elemCollision = {
  * Inspired by the jQuery project's open source implementations of element dimension
  * and offset utilities. This class serves as a lightweight alternative using modern DOM APIs.
  *
- * @template {ConstructorElValues|ConstructorElValues[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} TinyHtmlT
+ * @template {TinyHtmlConstructor} TinyHtmlT
  * @class
  */
 class TinyHtml {
@@ -1824,7 +1839,8 @@ class TinyHtml {
   static setData(el, key, value, isPrivate = false) {
     const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('setData', el);
     if (typeof key !== 'string') throw new TypeError('The key must be a string.');
-    data[key] = value;
+    if (typeof value !== 'undefined') data[key] = value;
+    else TinyHtml.removeData(el, key);
     return el;
   }
 
@@ -1840,6 +1856,57 @@ class TinyHtml {
     return TinyHtml.setData(this, key, value, isPrivate);
   }
 
+  /**
+   * Checks if a specific key exists in the data store of a DOM element.
+   *
+   * @template {TinyElement} T
+   * @param {T} el - The DOM element.
+   * @param {string} key - The key to check.
+   * @param {boolean} [isPrivate=false] - Whether to check the private store.
+   * @returns {boolean}
+   */
+  static hasData(el, key, isPrivate = false) {
+    if (typeof key !== 'string') throw new TypeError('The key must be a string.');
+    const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('hasData', el);
+    return Object.prototype.hasOwnProperty.call(data, key);
+  }
+
+  /**
+   * Checks if a specific key exists in the data store of this element.
+   *
+   * @param {string} key - The key to check.
+   * @param {boolean} [isPrivate=false] - Whether to check the private store.
+   * @returns {boolean}
+   */
+  hasData(key, isPrivate = false) {
+    return TinyHtml.hasData(this, key, isPrivate);
+  }
+
+  /**
+   * Removes a value associated with a specific key from the data store of a DOM element.
+   *
+   * @param {TinyElement} el - The DOM element.
+   * @param {string} key - The key to remove.
+   * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+   * @returns {boolean}
+   */
+  static removeData(el, key, isPrivate = false) {
+    if (typeof key !== 'string') throw new TypeError('The key must be a string.');
+    const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('removeData', el);
+    return delete data[key];
+  }
+
+  /**
+   * Removes a value associated with a specific key from the data store of this element.
+   *
+   * @param {string} key - The key to remove.
+   * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+   * @returns {boolean}
+   */
+  removeData(key, isPrivate = false) {
+    return TinyHtml.removeData(this, key, isPrivate);
+  }
+
   //////////////////////////////////////////////////////
 
   // TITLE: DOM Getter 2
@@ -2488,47 +2555,75 @@ class TinyHtml {
   }
 
   /**
-   * Creates an instance of TinyHtml for a specific Element.
-   * Useful when you want to operate repeatedly on the same element using instance methods.
-   * @param {TinyHtmlT} el - The element to wrap and manipulate.
+   * Validates if all provided items are acceptable constructor values.
+   *
+   * @param {any[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} els - The elements to validate.
+   * @throws {Error} If any element is not a valid target.
    */
-  constructor(el) {
+  static _elCheck(els) {
+    for (const item of els) {
+      if (
+        !(item instanceof Element) &&
+        !(item instanceof Window) &&
+        !(item instanceof Document) &&
+        !(item instanceof Text)
+      )
+        throw new Error(`[TinyHtml] Invalid Target in constructor.`);
+    }
+  }
+
+  /**
+   * A new TinyHtml object containing the combined elements.
+   *
+   * @template {TinyHtmlConstructor} T
+   * @param {T} el - The elements to add.
+   * @returns {TinyHtml<T>} The new length of the internal collection.
+   */
+  add(el) {
+    return new TinyHtml([...this.#el, ...TinyHtml._selector(el)]);
+  }
+
+  /**
+   * Resolves the given constructor input into a normalized array of elements.
+   *
+   * @param {TinyHtmlConstructor} el - A selector string, element, array-like collection, or array of constructor values.
+   * @returns {ConstructorElValues[]} A normalized array of DOM elements/values.
+   * @throws {Error} If a TinyHtml instance is passed (nesting TinyHtml inside TinyHtml is not allowed).
+   * @throws {Error} If the resolved elements are not valid constructor values.
+   */
+  static _selector(el) {
     if (el instanceof TinyHtml)
       throw new Error(
         `[TinyHtml] You are trying to put a TinyHtml inside another TinyHtml in constructor.`,
       );
 
-    /** @param {any[]} els */
-    const elCheck = (els) => {
-      if (
-        !els.every(
-          (el) =>
-            el instanceof Element ||
-            el instanceof Window ||
-            el instanceof Document ||
-            el instanceof Text,
-        )
-      )
-        throw new Error(`[TinyHtml] Invalid Target in constructor.`);
-    };
-
-    if (Array.isArray(el)) {
-      elCheck(el);
-      this.#el = el;
-    } else if (el instanceof NodeList || el instanceof HTMLCollection) {
-      /** @type {ConstructorElValues[]} */
-      // @ts-ignore
-      const els = [...el];
-      elCheck(els);
-      this.#el = els;
+    /** @type {(list: any[]) => any[]} */
+    const fixItemList = (list) => Array.from(new Set(list));
+    const selector = typeof el !== 'string' ? el : document.querySelectorAll(el);
+    if (Array.isArray(selector)) {
+      TinyHtml._elCheck(selector);
+      return fixItemList(selector);
+    } else if (selector instanceof NodeList || selector instanceof HTMLCollection) {
+      const els = [...selector];
+      TinyHtml._elCheck(els);
+      return fixItemList(els);
     } else {
-      const els = [el];
-      elCheck(els);
+      const els = [selector];
+      TinyHtml._elCheck(els);
       // @ts-ignore
-      this.#el = els;
+      return fixItemList(els);
     }
   }
 
+  /**
+   * Creates an instance of TinyHtml for a specific Element.
+   * Useful when you want to operate repeatedly on the same element using instance methods.
+   * @param {TinyHtmlT} el - The element to wrap and manipulate.
+   */
+  constructor(el) {
+    this.#el = TinyHtml._selector(el);
+  }
+
   /**
    * Checks whether the given object is a window.
    * @param {*} obj - The object to test.

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

@@ -207,6 +207,12 @@ export type InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaEl
 export type HtmlParsed = [tagName: string, // The tag name of the element (e.g., 'div', 'img')
 attributes: Record<string, string>, // All element attributes as key-value pairs
 ...children: (string | HtmlParsed)[]];
+/**
+ * Represents all possible inputs accepted by the TinyHtml constructor.
+ * Can be a single element, an array of elements, array-like DOM collections,
+ * or a CSS selector string.
+ */
+export type TinyHtmlConstructor = (ConstructorElValues | ConstructorElValues[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement> | string);
 /**
  * Possible directions from which a collision was detected and locked.
  *
@@ -246,6 +252,20 @@ attributes: Record<string, string>, // All element attributes as key-value pairs
  *   ...children: (string | HtmlParsed)[] // Text or nested elements
  * ]} HtmlParsed
  */
+/**
+ * Represents all possible inputs accepted by the TinyHtml constructor.
+ * Can be a single element, an array of elements, array-like DOM collections,
+ * or a CSS selector string.
+ *
+ * @typedef {(
+ *   ConstructorElValues |
+ *   ConstructorElValues[] |
+ *   NodeListOf<Element> |
+ *   HTMLCollectionOf<Element> |
+ *   NodeListOf<HTMLElement> |
+ *   string
+ * )} TinyHtmlConstructor
+ */
 /**
  * TinyHtml is a utility class that provides static and instance-level methods
  * for precise dimension and position computations on HTML elements.
@@ -254,10 +274,10 @@ attributes: Record<string, string>, // All element attributes as key-value pairs
  * Inspired by the jQuery project's open source implementations of element dimension
  * and offset utilities. This class serves as a lightweight alternative using modern DOM APIs.
  *
- * @template {ConstructorElValues|ConstructorElValues[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} TinyHtmlT
+ * @template {TinyHtmlConstructor} TinyHtmlT
  * @class
  */
-declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValues[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement>> {
+declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
     /** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
     static Utils: {
         getElsRelativeCenterOffset(rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect): {
@@ -871,6 +891,25 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {T}
      */
     static setData<T extends TinyElement>(el: T, key: string, value: any, isPrivate?: boolean): T;
+    /**
+     * Checks if a specific key exists in the data store of a DOM element.
+     *
+     * @template {TinyElement} T
+     * @param {T} el - The DOM element.
+     * @param {string} key - The key to check.
+     * @param {boolean} [isPrivate=false] - Whether to check the private store.
+     * @returns {boolean}
+     */
+    static hasData<T extends TinyElement>(el: T, key: string, isPrivate?: boolean): boolean;
+    /**
+     * Removes a value associated with a specific key from the data store of a DOM element.
+     *
+     * @param {TinyElement} el - The DOM element.
+     * @param {string} key - The key to remove.
+     * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+     * @returns {boolean}
+     */
+    static removeData(el: TinyElement, key: string, isPrivate?: boolean): boolean;
     /**
      * Get the sibling element in a given direction.
      *
@@ -1081,6 +1120,22 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {T}
      */
     static replaceAll<T extends TinyNode | TinyNode[]>(el: T, targets: TinyNode | TinyNode[]): T;
+    /**
+     * Validates if all provided items are acceptable constructor values.
+     *
+     * @param {any[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} els - The elements to validate.
+     * @throws {Error} If any element is not a valid target.
+     */
+    static _elCheck(els: any[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement>): void;
+    /**
+     * Resolves the given constructor input into a normalized array of elements.
+     *
+     * @param {TinyHtmlConstructor} el - A selector string, element, array-like collection, or array of constructor values.
+     * @returns {ConstructorElValues[]} A normalized array of DOM elements/values.
+     * @throws {Error} If a TinyHtml instance is passed (nesting TinyHtml inside TinyHtml is not allowed).
+     * @throws {Error} If the resolved elements are not valid constructor values.
+     */
+    static _selector(el: TinyHtmlConstructor): ConstructorElValues[];
     /**
      * Checks whether the given object is a window.
      * @param {*} obj - The object to test.
@@ -2884,6 +2939,22 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {this}
      */
     setData(key: string, value: any, isPrivate?: boolean): this;
+    /**
+     * Checks if a specific key exists in the data store of this element.
+     *
+     * @param {string} key - The key to check.
+     * @param {boolean} [isPrivate=false] - Whether to check the private store.
+     * @returns {boolean}
+     */
+    hasData(key: string, isPrivate?: boolean): boolean;
+    /**
+     * Removes a value associated with a specific key from the data store of this element.
+     *
+     * @param {string} key - The key to remove.
+     * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+     * @returns {boolean}
+     */
+    removeData(key: string, isPrivate?: boolean): boolean;
     /**
      * Returns the direct parent node of the given element, excluding document fragments.
      *
@@ -3038,6 +3109,14 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {number} The total count of elements.
      */
     get size(): number;
+    /**
+     * A new TinyHtml object containing the combined elements.
+     *
+     * @template {TinyHtmlConstructor} T
+     * @param {T} el - The elements to add.
+     * @returns {TinyHtml<T>} The new length of the internal collection.
+     */
+    add<T extends TinyHtmlConstructor>(el: T): TinyHtml<T>;
     /**
      * Returns the full computed CSS styles for the given element.
      *

package/dist/v1/libs/TinyHtml.mjs

@@ -282,6 +282,20 @@ const __elemCollision = {
  * ]} HtmlParsed
  */
 // TITLE: Class Intro
+/**
+ * Represents all possible inputs accepted by the TinyHtml constructor.
+ * Can be a single element, an array of elements, array-like DOM collections,
+ * or a CSS selector string.
+ *
+ * @typedef {(
+ *   ConstructorElValues |
+ *   ConstructorElValues[] |
+ *   NodeListOf<Element> |
+ *   HTMLCollectionOf<Element> |
+ *   NodeListOf<HTMLElement> |
+ *   string
+ * )} TinyHtmlConstructor
+ */
 /**
  * TinyHtml is a utility class that provides static and instance-level methods
  * for precise dimension and position computations on HTML elements.
@@ -290,7 +304,7 @@ const __elemCollision = {
  * Inspired by the jQuery project's open source implementations of element dimension
  * and offset utilities. This class serves as a lightweight alternative using modern DOM APIs.
  *
- * @template {ConstructorElValues|ConstructorElValues[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} TinyHtmlT
+ * @template {TinyHtmlConstructor} TinyHtmlT
  * @class
  */
 class TinyHtml {
@@ -1582,7 +1596,10 @@ class TinyHtml {
         const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('setData', el);
         if (typeof key !== 'string')
             throw new TypeError('The key must be a string.');
-        data[key] = value;
+        if (typeof value !== 'undefined')
+            data[key] = value;
+        else
+            TinyHtml.removeData(el, key);
         return el;
     }
     /**
@@ -1596,6 +1613,55 @@ class TinyHtml {
     setData(key, value, isPrivate = false) {
         return TinyHtml.setData(this, key, value, isPrivate);
     }
+    /**
+     * Checks if a specific key exists in the data store of a DOM element.
+     *
+     * @template {TinyElement} T
+     * @param {T} el - The DOM element.
+     * @param {string} key - The key to check.
+     * @param {boolean} [isPrivate=false] - Whether to check the private store.
+     * @returns {boolean}
+     */
+    static hasData(el, key, isPrivate = false) {
+        if (typeof key !== 'string')
+            throw new TypeError('The key must be a string.');
+        const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('hasData', el);
+        return Object.prototype.hasOwnProperty.call(data, key);
+    }
+    /**
+     * Checks if a specific key exists in the data store of this element.
+     *
+     * @param {string} key - The key to check.
+     * @param {boolean} [isPrivate=false] - Whether to check the private store.
+     * @returns {boolean}
+     */
+    hasData(key, isPrivate = false) {
+        return TinyHtml.hasData(this, key, isPrivate);
+    }
+    /**
+     * Removes a value associated with a specific key from the data store of a DOM element.
+     *
+     * @param {TinyElement} el - The DOM element.
+     * @param {string} key - The key to remove.
+     * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+     * @returns {boolean}
+     */
+    static removeData(el, key, isPrivate = false) {
+        if (typeof key !== 'string')
+            throw new TypeError('The key must be a string.');
+        const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('removeData', el);
+        return delete data[key];
+    }
+    /**
+     * Removes a value associated with a specific key from the data store of this element.
+     *
+     * @param {string} key - The key to remove.
+     * @param {boolean} [isPrivate=false] - Whether to remove from the private store.
+     * @returns {boolean}
+     */
+    removeData(key, isPrivate = false) {
+        return TinyHtml.removeData(this, key, isPrivate);
+    }
     //////////////////////////////////////////////////////
     // TITLE: DOM Getter 2
     /**
@@ -2188,39 +2254,68 @@ class TinyHtml {
         return this.#el.length;
     }
     /**
-     * Creates an instance of TinyHtml for a specific Element.
-     * Useful when you want to operate repeatedly on the same element using instance methods.
-     * @param {TinyHtmlT} el - The element to wrap and manipulate.
+     * Validates if all provided items are acceptable constructor values.
+     *
+     * @param {any[]|NodeListOf<Element>|HTMLCollectionOf<Element>|NodeListOf<HTMLElement>} els - The elements to validate.
+     * @throws {Error} If any element is not a valid target.
      */
-    constructor(el) {
+    static _elCheck(els) {
+        for (const item of els) {
+            if (!(item instanceof Element) &&
+                !(item instanceof Window) &&
+                !(item instanceof Document) &&
+                !(item instanceof Text))
+                throw new Error(`[TinyHtml] Invalid Target in constructor.`);
+        }
+    }
+    /**
+     * A new TinyHtml object containing the combined elements.
+     *
+     * @template {TinyHtmlConstructor} T
+     * @param {T} el - The elements to add.
+     * @returns {TinyHtml<T>} The new length of the internal collection.
+     */
+    add(el) {
+        return new TinyHtml([...this.#el, ...TinyHtml._selector(el)]);
+    }
+    /**
+     * Resolves the given constructor input into a normalized array of elements.
+     *
+     * @param {TinyHtmlConstructor} el - A selector string, element, array-like collection, or array of constructor values.
+     * @returns {ConstructorElValues[]} A normalized array of DOM elements/values.
+     * @throws {Error} If a TinyHtml instance is passed (nesting TinyHtml inside TinyHtml is not allowed).
+     * @throws {Error} If the resolved elements are not valid constructor values.
+     */
+    static _selector(el) {
         if (el instanceof TinyHtml)
             throw new Error(`[TinyHtml] You are trying to put a TinyHtml inside another TinyHtml in constructor.`);
-        /** @param {any[]} els */
-        const elCheck = (els) => {
-            if (!els.every((el) => el instanceof Element ||
-                el instanceof Window ||
-                el instanceof Document ||
-                el instanceof Text))
-                throw new Error(`[TinyHtml] Invalid Target in constructor.`);
-        };
-        if (Array.isArray(el)) {
-            elCheck(el);
-            this.#el = el;
+        /** @type {(list: any[]) => any[]} */
+        const fixItemList = (list) => Array.from(new Set(list));
+        const selector = typeof el !== 'string' ? el : document.querySelectorAll(el);
+        if (Array.isArray(selector)) {
+            TinyHtml._elCheck(selector);
+            return fixItemList(selector);
         }
-        else if (el instanceof NodeList || el instanceof HTMLCollection) {
-            /** @type {ConstructorElValues[]} */
-            // @ts-ignore
-            const els = [...el];
-            elCheck(els);
-            this.#el = els;
+        else if (selector instanceof NodeList || selector instanceof HTMLCollection) {
+            const els = [...selector];
+            TinyHtml._elCheck(els);
+            return fixItemList(els);
         }
         else {
-            const els = [el];
-            elCheck(els);
+            const els = [selector];
+            TinyHtml._elCheck(els);
             // @ts-ignore
-            this.#el = els;
+            return fixItemList(els);
         }
     }
+    /**
+     * Creates an instance of TinyHtml for a specific Element.
+     * Useful when you want to operate repeatedly on the same element using instance methods.
+     * @param {TinyHtmlT} el - The element to wrap and manipulate.
+     */
+    constructor(el) {
+        this.#el = TinyHtml._selector(el);
+    }
     /**
      * Checks whether the given object is a window.
      * @param {*} obj - The object to test.

package/docs/v1/libs/TinyHtml.md

@@ -1001,6 +1001,31 @@ static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml[]
 
 ## 🧩 Internal Element Access
 
+### `_elCheck(els)`
+
+Validates if all provided items are acceptable constructor values.
+
+* **Parameters**:
+
+  * `els` (`ConstructorElValues[]`) — The elements to validate.
+* **Throws**:
+
+  * `Error` — If any element is not a valid target.
+* **Returns**: `void`
+
+---
+
+### `add(...el)`
+
+Adds elements to the end of the internal collection.
+
+* **Parameters**:
+
+  * `...el` (`ConstructorElValues`) — The elements to add.
+* **Returns**: `TinyHtml` — A new TinyHtml object containing the combined elements.
+
+---
+
 ### `exists(index)`
 Checks whether the element exists at the given index.
 
@@ -1214,6 +1239,14 @@ Gets data from the element.
 
 Sets a value on the element’s data store.
 
+#### `TinyHtml.hasData(el, key, isPrivate?)`
+
+Checks if a specific key exists in the data store of a DOM element.
+
+#### `TinyHtml.removeData(el, key, isPrivate?)`
+
+Removes a value associated with a specific key from the data store of a DOM element.
+
 ---
 
 ### 📌 Instance Methods
@@ -1226,6 +1259,14 @@ Shortcut for getting data from the current instance’s element.
 
 Shortcut for setting data on the current element.
 
+#### `.hasData(key, isPrivate?)`
+
+Checks if a specific key exists in the data store of this element.
+
+#### `.removeData(key, isPrivate?)`
+
+Removes a value associated with a specific key from the data store of this element.
+
 ---
 
 ## 🔄 DOM Traversal Methods

package/package.json

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