tiny-essentials 1.21.2 → 1.21.4

package/dist/v1/libs/TinyHtml.mjs

@@ -550,6 +550,17 @@ class TinyHtml {
         return TinyHtml.getByTagNameNS(localName, namespaceURI, TinyHtml._preElem(this, 'getByTagNameNS'));
     }
     //////////////////////////////////////////////////////////////////
+    /**
+     * Iterates over all elements, executing the provided callback on each.
+     * @param {(element: TinyHtml, index: number, items: TinyHtml[]) => void} callback - Function invoked for each element.
+     * @returns {TinyHtml} The current instance for chaining.
+     */
+    forEach(callback) {
+        const elems = this.getAll().map((el, index) => this.extract(index));
+        for (const index in elems)
+            callback(elems[index], Number(index), elems);
+        return this;
+    }
     /**
      * Returns the current target held by this instance.
      *
@@ -1153,8 +1164,28 @@ class TinyHtml {
         return TinyHtml.isSameDom(this, elem);
     }
     //////////////////////////////////////////////////////////////////
-    /** @type {ElementDataStore} */
-    _data = {};
+    /**
+     * Internal data storage for element information.
+     * @type {ElementDataStore}
+     */
+    #data = {};
+    /**
+     * Returns a shallow copy of the internal data.
+     * @type {ElementDataStore}
+     */
+    get _data() {
+        return { ...this.#data };
+    }
+    /**
+     * Replaces the internal data with a new object.
+     * @param {ElementDataStore} value - Must be a non-null object.
+     * @throws {Error} If the value is not a valid object.
+     */
+    set _data(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error('value must be a non-null object.');
+        this.#data = value;
+    }
     /**
      * Internal data selectors for accessing public or private data stores.
      *
@@ -1174,7 +1205,7 @@ class TinyHtml {
         private: (where, el) => {
             if (!(el instanceof TinyHtml))
                 throw new Error(`Element must be a TinyHtml instance to execute ${where}().`);
-            return el._data;
+            return el.#data;
         },
     };
     /**
@@ -2495,6 +2526,27 @@ class TinyHtml {
     blur() {
         return TinyHtml.blur(this);
     }
+    /**
+     * Select the text content of an input or textarea element.
+     *
+     * @param {TinyHtml|HTMLInputElement|HTMLTextAreaElement} el - The element or a selector string.
+     * @returns {TinyHtml|HTMLInputElement|HTMLTextAreaElement}
+     */
+    static select(el) {
+        const elem = TinyHtml._preHtmlElem(el, 'select');
+        if (elem instanceof HTMLInputElement || elem instanceof HTMLTextAreaElement)
+            elem.select();
+        else
+            throw new Error('Element must be an <input> or <textarea> to use select().');
+        return el;
+    }
+    /**
+     * Select the text content of an input or textarea element.
+     * @returns {TinyHtml|HTMLInputElement|HTMLTextAreaElement}
+     */
+    select() {
+        return TinyHtml.select(this);
+    }
     /**
      * Interprets a value as a boolean `true` if it matches a common truthy representation.
      *
@@ -4025,135 +4077,155 @@ class TinyHtml {
      * Registers an event listener on the specified element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target to listen on.
-     * @param {string} event - The event type (e.g. 'click', 'keydown').
+     * @param {string|string[]} events - The event type (e.g. 'click', 'keydown').
      * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static on(el, event, handler, options) {
-        if (typeof event !== 'string')
-            throw new TypeError('The event name must be a string.');
-        TinyHtml._preEventTargetElems(el, 'on').forEach((elem) => {
-            elem.addEventListener(event, handler, options);
-            if (!__eventRegistry.has(elem))
-                __eventRegistry.set(elem, {});
-            const events = __eventRegistry.get(elem);
-            if (!events)
-                return;
-            if (!Array.isArray(events[event]))
-                events[event] = [];
-            events[event].push({ handler, options });
-        });
+    static on(el, events, handler, options) {
+        if (typeof events !== 'string' &&
+            (!Array.isArray(events) || !events.every((event) => typeof event === 'string')))
+            throw new TypeError('The events must be a string or array of strings.');
+        for (const event of Array.isArray(events) ? Array.from(new Set(events)) : [events]) {
+            if (typeof event !== 'string')
+                throw new TypeError('The event name must be a string.');
+            TinyHtml._preEventTargetElems(el, 'on').forEach((elem) => {
+                elem.addEventListener(event, handler, options);
+                if (!__eventRegistry.has(elem))
+                    __eventRegistry.set(elem, {});
+                const events = __eventRegistry.get(elem);
+                if (!events)
+                    return;
+                if (!Array.isArray(events[event]))
+                    events[event] = [];
+                events[event].push({ handler, options });
+            });
+        }
         return el;
     }
     /**
      * Registers an event listener on the specified element.
      *
-     * @param {string} event - The event type (e.g. 'click', 'keydown').
+     * @param {string|string[]} events - The event type (e.g. 'click', 'keydown').
      * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    on(event, handler, options) {
-        return TinyHtml.on(this, event, handler, options);
+    on(events, handler, options) {
+        return TinyHtml.on(this, events, handler, options);
     }
     /**
      * Registers an event listener that runs only once, then is removed.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target to listen on.
-     * @param {string} event - The event type (e.g. 'click', 'keydown').
+     * @param {string|string[]} events - The event type (e.g. 'click', 'keydown').
      * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options={}] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static once(el, event, handler, options = {}) {
-        if (typeof event !== 'string')
-            throw new TypeError('The event name must be a string.');
-        TinyHtml._preEventTargetElems(el, 'once').forEach((elem) => {
-            /** @type {EventListenerOrEventListenerObject} */
-            const wrapped = (e) => {
-                TinyHtml.off(elem, event, wrapped);
-                if (typeof handler === 'function')
-                    handler(e);
-            };
-            TinyHtml.on(elem, event, wrapped, typeof options === 'boolean' ? options : { ...options, once: true });
-        });
+    static once(el, events, handler, options = {}) {
+        if (typeof events !== 'string' &&
+            (!Array.isArray(events) || !events.every((event) => typeof event === 'string')))
+            throw new TypeError('The events must be a string or array of strings.');
+        for (const event of Array.isArray(events) ? Array.from(new Set(events)) : [events]) {
+            if (typeof event !== 'string')
+                throw new TypeError('The event name must be a string.');
+            TinyHtml._preEventTargetElems(el, 'once').forEach((elem) => {
+                /** @type {EventListenerOrEventListenerObject} */
+                const wrapped = (e) => {
+                    TinyHtml.off(elem, event, wrapped);
+                    if (typeof handler === 'function')
+                        handler(e);
+                };
+                TinyHtml.on(elem, event, wrapped, typeof options === 'boolean' ? options : { ...options, once: true });
+            });
+        }
         return el;
     }
     /**
      * Registers an event listener that runs only once, then is removed.
      *
-     * @param {string} event - The event type (e.g. 'click', 'keydown').
+     * @param {string|string[]} events - The event type (e.g. 'click', 'keydown').
      * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options={}] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    once(event, handler, options = {}) {
-        return TinyHtml.once(this, event, handler, options);
+    once(events, handler, options = {}) {
+        return TinyHtml.once(this, events, handler, options);
     }
     /**
      * Removes a specific event listener from an element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
-     * @param {string} event - The event type.
+     * @param {string|string[]} events - The event type.
      * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
      * @param {boolean|EventListenerOptions} [options] - Optional listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static off(el, event, handler, options) {
-        if (typeof event !== 'string')
-            throw new TypeError('The event name must be a string.');
-        TinyHtml._preEventTargetElems(el, 'off').forEach((elem) => {
-            elem.removeEventListener(event, handler, options);
-            const events = __eventRegistry.get(elem);
-            if (events && events[event]) {
-                events[event] = events[event].filter((entry) => entry.handler !== handler);
-                if (events[event].length === 0)
-                    delete events[event];
-            }
-        });
+    static off(el, events, handler, options) {
+        if (typeof events !== 'string' &&
+            (!Array.isArray(events) || !events.every((event) => typeof event === 'string')))
+            throw new TypeError('The events must be a string or array of strings.');
+        for (const event of Array.isArray(events) ? Array.from(new Set(events)) : [events]) {
+            if (typeof event !== 'string')
+                throw new TypeError('The event name must be a string.');
+            TinyHtml._preEventTargetElems(el, 'off').forEach((elem) => {
+                elem.removeEventListener(event, handler, options);
+                const events = __eventRegistry.get(elem);
+                if (events && events[event]) {
+                    events[event] = events[event].filter((entry) => entry.handler !== handler);
+                    if (events[event].length === 0)
+                        delete events[event];
+                }
+            });
+        }
         return el;
     }
     /**
      * Removes a specific event listener from an element.
      *
-     * @param {string} event - The event type.
+     * @param {string|string[]} events - The event type.
      * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
      * @param {boolean|EventListenerOptions} [options] - Optional listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    off(event, handler, options) {
-        return TinyHtml.off(this, event, handler, options);
+    off(events, handler, options) {
+        return TinyHtml.off(this, events, handler, options);
     }
     /**
      * Removes all event listeners of a specific type from the element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
-     * @param {string} event - The event type to remove (e.g. 'click').
+     * @param {string|string[]} events - The event type to remove (e.g. 'click').
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static offAll(el, event) {
-        if (typeof event !== 'string')
-            throw new TypeError('The event name must be a string.');
-        TinyHtml._preEventTargetElems(el, 'offAll').forEach((elem) => {
-            const events = __eventRegistry.get(elem);
-            if (events && events[event]) {
-                for (const entry of events[event]) {
-                    elem.removeEventListener(event, entry.handler, entry.options);
+    static offAll(el, events) {
+        if (typeof events !== 'string' &&
+            (!Array.isArray(events) || !events.every((event) => typeof event === 'string')))
+            throw new TypeError('The events must be a string or array of strings.');
+        for (const event of Array.isArray(events) ? Array.from(new Set(events)) : [events]) {
+            if (typeof event !== 'string')
+                throw new TypeError('The event name must be a string.');
+            TinyHtml._preEventTargetElems(el, 'offAll').forEach((elem) => {
+                const events = __eventRegistry.get(elem);
+                if (events && events[event]) {
+                    for (const entry of events[event]) {
+                        elem.removeEventListener(event, entry.handler, entry.options);
+                    }
+                    delete events[event];
                 }
-                delete events[event];
-            }
-        });
+            });
+        }
         return el;
     }
     /**
      * Removes all event listeners of a specific type from the element.
      *
-     * @param {string} event - The event type to remove (e.g. 'click').
+     * @param {string|string[]} events - The event type to remove (e.g. 'click').
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    offAll(event) {
-        return TinyHtml.offAll(this, event);
+    offAll(events) {
+        return TinyHtml.offAll(this, events);
     }
     /**
      * Removes all event listeners of all types from the element.
@@ -4195,34 +4267,39 @@ class TinyHtml {
      * Triggers all handlers associated with a specific event on the given element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - Target element where the event should be triggered.
-     * @param {string} event - Name of the event to trigger.
+     * @param {string|string[]} events - Name of the event to trigger.
      * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static trigger(el, event, payload = {}) {
-        if (typeof event !== 'string')
-            throw new TypeError('The event name must be a string.');
-        TinyHtml._preEventTargetElems(el, 'trigger').forEach((elem) => {
-            const evt = payload instanceof Event || payload instanceof CustomEvent
-                ? payload
-                : new CustomEvent(event, {
-                    bubbles: true,
-                    cancelable: true,
-                    detail: payload,
-                });
-            elem.dispatchEvent(evt);
-        });
+    static trigger(el, events, payload = {}) {
+        if (typeof events !== 'string' &&
+            (!Array.isArray(events) || !events.every((event) => typeof event === 'string')))
+            throw new TypeError('The events must be a string or array of strings.');
+        for (const event of Array.isArray(events) ? Array.from(new Set(events)) : [events]) {
+            if (typeof event !== 'string')
+                throw new TypeError('The event name must be a string.');
+            TinyHtml._preEventTargetElems(el, 'trigger').forEach((elem) => {
+                const evt = payload instanceof Event || payload instanceof CustomEvent
+                    ? payload
+                    : new CustomEvent(event, {
+                        bubbles: true,
+                        cancelable: true,
+                        detail: payload,
+                    });
+                elem.dispatchEvent(evt);
+            });
+        }
         return el;
     }
     /**
      * Triggers all handlers associated with a specific event on the given element.
      *
-     * @param {string} event - Name of the event to trigger.
+     * @param {string|string[]} events - Name of the event to trigger.
      * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    trigger(event, payload = {}) {
-        return TinyHtml.trigger(this, event, payload);
+    trigger(events, payload = {}) {
+        return TinyHtml.trigger(this, events, payload);
     }
     ///////////////////////////////////////////////////////////////
     /**

package/docs/v1/libs/TinyHtml.md

@@ -587,6 +587,17 @@ Checks whether the element exists at the given index.
 
 ---
 
+### `forEach(callback)`
+
+Iterates over all elements in the current instance, executing the provided callback on each one.
+
+* **Parameters**:
+
+  * `callback`: `(element: TinyHtml, index: number, items: TinyHtml[]) => void`
+    Function invoked for each element. Receives the current `TinyHtml`, its index, and the full list.
+
+---
+
 ### `get(index)`
 Returns the raw DOM element associated with this instance.
 
@@ -2238,6 +2249,20 @@ tinyElem.blur();
 
 ---
 
+### 🖊️ `TinyHtml.select(el)` / `el.select()`
+
+Selects all the text inside the given element.
+
+```js
+TinyHtml.select(element);
+// or
+tinyElem.select();
+```
+
+⚠️ Throws an error if the target element is not an `<input>` or `<textarea>`.
+
+---
+
 ## 🌐 Window Scroll & Viewport Helpers
 
 These methods let you control and query scroll positions and viewport size with simple, readable functions.

package/package.json

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