tiny-essentials 1.21.3 → 1.21.5

package/dist/v1/libs/TinyHtml.cjs

@@ -2806,6 +2806,27 @@ class TinyHtml {
     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.
    *
@@ -3852,6 +3873,182 @@ class TinyHtml {
     return TinyHtml.id(this);
   }
 
+  /**
+   * Returns the BigInt content of the element.
+   * @param {TinyElement} el - Target element.
+   * @returns {bigint|null} The BigInt content or null if none.
+   */
+  static toBigInt(el) {
+    const elem = TinyHtml._preElem(el, 'toBigInt');
+    const txt = elem.textContent?.trim();
+    let value = null;
+    try {
+      value = BigInt(txt ?? '');
+    } catch {
+      value = null;
+    }
+    return value;
+  }
+
+  /**
+   * Returns the BigInt content of the element.
+   * @returns {bigint|null}
+   */
+  toBigInt() {
+    return TinyHtml.toBigInt(this);
+  }
+
+  /**
+   * Set BigInt content of elements.
+   * @param {TinyElement|TinyElement[]} el
+   * @param {bigint} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static setBigInt(el, value) {
+    if (typeof value !== 'bigint') throw new Error('Value is not a valid BigInt.');
+    TinyHtml._preElems(el, 'setBigInt').forEach((el) => (el.textContent = value.toString()));
+    return el;
+  }
+
+  /**
+   * Set BigInt content of the element.
+   * @param {bigint} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  setBigInt(value) {
+    return TinyHtml.setBigInt(this, value);
+  }
+
+  /**
+   * Returns the Date content of the element.
+   * @param {TinyElement} el - Target element.
+   * @returns {Date|null} The Date content or null if invalid.
+   */
+  static toDate(el) {
+    const elem = TinyHtml._preElem(el, 'toDate');
+    const txt = elem.textContent?.trim();
+    if (!txt) return null;
+    const d = new Date(txt);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+
+  /**
+   * Returns the Date content of the element.
+   * @returns {Date|null}
+   */
+  toDate() {
+    return TinyHtml.toDate(this);
+  }
+
+  /**
+   * Set Date content of elements.
+   * @param {TinyElement|TinyElement[]} el
+   * @param {Date} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static setDate(el, value) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime()))
+      throw new Error('Value is not a valid Date.');
+    TinyHtml._preElems(el, 'setDate').forEach((el) => (el.textContent = value.toISOString()));
+    return el;
+  }
+
+  /**
+   * Set Date content of the element.
+   * @param {Date} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  setDate(value) {
+    return TinyHtml.setDate(this, value);
+  }
+
+  /**
+   * Returns the JSON content of the element.
+   * @param {TinyElement} el - Target element.
+   * @returns {any|null} The parsed JSON content or null if invalid.
+   */
+  static toJson(el) {
+    const elem = TinyHtml._preElem(el, 'toJson');
+    const txt = elem.textContent?.trim();
+    if (!txt) return null;
+    try {
+      return JSON.parse(txt);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Returns the JSON content of the element.
+   * @returns {any|null}
+   */
+  toJson() {
+    return TinyHtml.toJson(this);
+  }
+
+  /**
+   * Set JSON content of elements.
+   * @param {TinyElement|TinyElement[]} el
+   * @param {any} value
+   * @param {number|string} [space] - Indentation level or string for formatting.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static setJson(el, value, space) {
+    TinyHtml._preElems(el, 'setJson').forEach(
+      (el) => (el.textContent = JSON.stringify(value, null, space)),
+    );
+    return el;
+  }
+
+  /**
+   * Set JSON content of the element.
+   * @param {any} value
+   * @param {number|string} [space] - Indentation level or string for formatting.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  setJson(value, space) {
+    return TinyHtml.setJson(this, value, space);
+  }
+
+  /**
+   * Returns the number content of the element.
+   * @param {TinyElement} el - Target element.
+   * @returns {number|null} The text content or null if none.
+   */
+  static toNumber(el) {
+    const elem = TinyHtml._preElem(el, 'toNumber');
+    return typeof elem.textContent === 'string' ? parseFloat(elem.textContent.trim()) : null;
+  }
+
+  /**
+   * Returns the number content of the element.
+   * @returns {number|null} The text content or null if none.
+   */
+  toNumber() {
+    return TinyHtml.toNumber(this);
+  }
+
+  /**
+   * Set number content of elements.
+   * @param {TinyElement|TinyElement[]} el
+   * @param {number} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static setNumber(el, value) {
+    if (typeof value !== 'number') throw new Error('Value is not a valid number.');
+    TinyHtml._preElems(el, 'setNumber').forEach((el) => (el.textContent = value.toString()));
+    return el;
+  }
+
+  /**
+   * Set number content of the element.
+   * @param {number} value
+   * @returns {TinyElement|TinyElement[]}
+   */
+  setNumber(value) {
+    return TinyHtml.setNumber(this, value);
+  }
+
   /**
    * Returns the text content of the element.
    * @param {TinyElement} el - Target element.
@@ -4501,141 +4698,169 @@ 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);
   }
 
   /**
@@ -4681,36 +4906,43 @@ 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);
   }
 
   ///////////////////////////////////////////////////////////////