tiny-essentials 1.17.1 → 1.18.1

package/dist/v1/libs/TinyHtml.mjs

@@ -72,6 +72,19 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  *
  * @typedef {Element|Window|Document} ElementAndWinAndDoc
  */
+/**
+ * Represents a raw DOM element with document or an instance of TinyHtml.
+ * This type is used to abstract interactions with both plain elements
+ * and wrapped elements via the TinyHtml class.
+ *
+ * @typedef {ElementWithDoc|TinyHtml} TinyElementWithDoc
+ */
+/**
+ * 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:
@@ -89,11 +102,6 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  *
  * @typedef {Window|Element|Document|Text} ConstructorElValues
  */
-/**
- * The handler function used in event listeners.
- *
- * @typedef {(e: Event) => any} EventRegistryHandle
- */
 /**
  * Options passed to `addEventListener` or `removeEventListener`.
  * Can be a boolean or an object of type `AddEventListenerOptions`.
@@ -104,7 +112,7 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  * Structure describing a registered event callback and its options.
  *
  * @typedef {Object} EventRegistryItem
- * @property {EventRegistryHandle} handler - The function to be executed when the event is triggered.
+ * @property {EventListenerOrEventListenerObject|null} handler - The function to be executed when the event is triggered.
  * @property {EventRegistryOptions} [options] - Optional configuration passed to the listener.
  */
 /**
@@ -595,9 +603,9 @@ class TinyHtml {
      * Ensures the input is returned as an array.
      * Useful to normalize operations across multiple or single element/window/document elements.
      *
-     * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+     * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/document/window element or array of html elements.
      * @param {string} where - The method or context name where validation is being called.
-     * @returns {ElementAndWindow[]} - Always returns an array of element/window elements.
+     * @returns {ElementAndWindow[]} - Always returns an array of element/document/window elements.
      * @readonly
      */
     static _preElemsAndWinAndDoc(elems, where) {
@@ -608,9 +616,9 @@ class TinyHtml {
      * Ensures the input is returned as an single element/window/document element.
      * Useful to normalize operations across multiple or single element/window/document elements.
      *
-     * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+     * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/document/window element or array of html elements.
      * @param {string} where - The method or context name where validation is being called.
-     * @returns {ElementAndWindow} - Always returns an single element/window element.
+     * @returns {ElementAndWindow} - Always returns an single element/document/window element.
      * @readonly
      */
     static _preElemAndWinAndDoc(elems, where) {
@@ -619,6 +627,30 @@ class TinyHtml {
             return result.documentElement;
         return result;
     }
+    /**
+     * Ensures the input is returned as an array.
+     * Useful to normalize operations across multiple or single element with document elements.
+     *
+     * @param {TinyElementWithDoc|TinyElementWithDoc[]} elems - A single element with document element or array of html elements.
+     * @param {string} where - The method or context name where validation is being called.
+     * @returns {ElementWithDoc[]} - Always returns an array of element with document elements.
+     * @readonly
+     */
+    static _preElemsWithDoc(elems, where) {
+        return TinyHtml._preElemsTemplate(elems, where, [Element, Document], ['Element', 'Document']);
+    }
+    /**
+     * Ensures the input is returned as an single element with document element.
+     * Useful to normalize operations across multiple or single element with document elements.
+     *
+     * @param {TinyElementWithDoc|TinyElementWithDoc[]} elems - A single element/window element or array of html elements.
+     * @param {string} where - The method or context name where validation is being called.
+     * @returns {ElementWithDoc} - Always returns an single element/window element.
+     * @readonly
+     */
+    static _preElemWithDoc(elems, where) {
+        return TinyHtml._preElemTemplate(elems, where, [Element, Document], ['Element', 'Document']);
+    }
     /**
      * Normalizes and converts one or more DOM elements (or TinyHtml instances)
      * into an array of `TinyHtml` instances.
@@ -3581,12 +3613,117 @@ class TinyHtml {
         return TinyHtml.valBool(this);
     }
     ////////////////////////////////////////////
+    /**
+     * Registers a listener for the "paste" event to extract files and text from the clipboard (e.g., when the user presses Ctrl+V).
+     *
+     * This method allows reacting to pasted content by providing separate callbacks for files and plain text.
+     * Useful for building file upload areas, rich-text editors, or input enhancements.
+     *
+     * @param {TinyElementWithDoc|TinyElementWithDoc[]} el - The target element(s) where the "paste" event will be listened.
+     * @param {Object} [settings={}] - Optional callbacks to handle clipboard content.
+     * @param {(data: DataTransferItem, file: File) => void} [settings.onFilePaste] - Called for each file pasted from the clipboard (e.g., images).
+     * @param {(data: DataTransferItem, text: string) => void} [settings.onTextPaste] - Called when plain text is pasted from the clipboard.
+     * @returns {EventListenerOrEventListenerObject} The internal "paste" event handler used.
+     */
+    static listenForPaste(el, { onFilePaste, onTextPaste } = {}) {
+        if (typeof onFilePaste !== 'undefined' && typeof onFilePaste !== 'function')
+            throw new TypeError('onFilePaste must be a function.');
+        if (typeof onTextPaste !== 'undefined' && typeof onTextPaste !== 'function')
+            throw new TypeError('onTextPaste must be a function.');
+        /** @type {EventListenerOrEventListenerObject} */
+        const pasteEvent = (event) => {
+            if (!(event instanceof ClipboardEvent))
+                return;
+            const items = event.clipboardData?.items || [];
+            for (const item of items) {
+                if (item.kind === 'file') {
+                    if (typeof onFilePaste === 'function') {
+                        const file = item.getAsFile();
+                        if (file)
+                            onFilePaste(item, file);
+                    }
+                }
+                else if (item.kind === 'string') {
+                    if (typeof onTextPaste === 'function')
+                        item.getAsString((text) => onTextPaste(item, text));
+                }
+            }
+        };
+        TinyHtml._preElemsWithDoc(el, 'listenForPaste').forEach((elem) => TinyHtml.on(elem, 'paste', pasteEvent));
+        return pasteEvent;
+    }
+    /**
+     * Registers a listener for the "paste" event to extract files and text from the clipboard (e.g., when the user presses Ctrl+V).
+     *
+     * This method allows reacting to pasted content by providing separate callbacks for files and plain text.
+     * Useful for building file upload areas, rich-text editors, or input enhancements.
+     *
+     * @param {Object} [settings={}] - Optional callbacks to handle clipboard content.
+     * @param {(data: DataTransferItem, file: File) => void} [settings.onFilePaste] - Called for each file pasted from the clipboard (e.g., images).
+     * @param {(data: DataTransferItem, text: string) => void} [settings.onTextPaste] - Called when plain text is pasted from the clipboard.
+     * @returns {EventListenerOrEventListenerObject} The internal "paste" event handler used.
+     */
+    listenForPaste({ onFilePaste, onTextPaste } = {}) {
+        return TinyHtml.listenForPaste(this, { onFilePaste, onTextPaste });
+    }
+    /**
+     * Checks if the element has a listener for a specific event.
+     *
+     * @param {TinyEventTarget} el - The element to check.
+     * @param {string} event - The event name to check.
+     * @returns {boolean}
+     */
+    static hasEventListener(el, event) {
+        const elem = TinyHtml._preEventTargetElem(el, 'hasEventListener');
+        if (!__eventRegistry.has(elem))
+            return false;
+        const events = __eventRegistry.get(elem);
+        return !!(events && Array.isArray(events[event]) && events[event].length > 0);
+    }
+    /**
+     * Checks if the element has a listener for a specific event.
+     *
+     * @param {string} event - The event name to check.
+     * @returns {boolean}
+     */
+    hasEventListener(event) {
+        return TinyHtml.hasEventListener(this, event);
+    }
+    /**
+     * Checks if the element has the exact handler registered for a specific event.
+     *
+     * @param {TinyEventTarget} el - The element to check.
+     * @param {string} event - The event name to check.
+     * @param {EventListenerOrEventListenerObject} handler - The handler function to check.
+     * @returns {boolean}
+     */
+    static hasExactEventListener(el, event, handler) {
+        const elem = TinyHtml._preEventTargetElem(el, 'hasExactEventListener');
+        if (typeof handler !== 'function')
+            throw new TypeError('The "handler" must be a function.');
+        if (!__eventRegistry.has(elem))
+            return false;
+        const events = __eventRegistry.get(elem);
+        if (!events || !Array.isArray(events[event]))
+            return false;
+        return events[event].some((item) => item.handler === handler);
+    }
+    /**
+     * Checks if the element has the exact handler registered for a specific event.
+     *
+     * @param {string} event - The event name to check.
+     * @param {EventListenerOrEventListenerObject} handler - The handler function to check.
+     * @returns {boolean}
+     */
+    hasExactEventListener(event, handler) {
+        return TinyHtml.hasExactEventListener(this, event, handler);
+    }
     /**
      * 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 {EventRegistryHandle} handler - The callback function to run on event.
+     * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3610,7 +3747,7 @@ class TinyHtml {
      * Registers an event listener on the specified element.
      *
      * @param {string} event - The event type (e.g. 'click', 'keydown').
-     * @param {EventRegistryHandle} handler - The callback function to run on event.
+     * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3622,7 +3759,7 @@ class TinyHtml {
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target to listen on.
      * @param {string} event - The event type (e.g. 'click', 'keydown').
-     * @param {EventRegistryHandle} handler - The callback function to run on event.
+     * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options={}] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3630,10 +3767,11 @@ class TinyHtml {
         if (typeof event !== 'string')
             throw new TypeError('The event name must be a string.');
         TinyHtml._preEventTargetElems(el, 'once').forEach((elem) => {
-            /** @type {EventRegistryHandle} e */
+            /** @type {EventListenerOrEventListenerObject} */
             const wrapped = (e) => {
                 TinyHtml.off(elem, event, wrapped);
-                handler(e);
+                if (typeof handler === 'function')
+                    handler(e);
             };
             TinyHtml.on(elem, event, wrapped, typeof options === 'boolean' ? options : { ...options, once: true });
         });
@@ -3643,7 +3781,7 @@ class TinyHtml {
      * Registers an event listener that runs only once, then is removed.
      *
      * @param {string} event - The event type (e.g. 'click', 'keydown').
-     * @param {EventRegistryHandle} handler - The callback function to run on event.
+     * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
      * @param {EventRegistryOptions} [options={}] - Optional event listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3655,7 +3793,7 @@ class TinyHtml {
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
      * @param {string} event - The event type.
-     * @param {EventRegistryHandle} handler - The function originally bound to the event.
+     * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
      * @param {boolean|EventListenerOptions} [options] - Optional listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3677,7 +3815,7 @@ class TinyHtml {
      * Removes a specific event listener from an element.
      *
      * @param {string} event - The event type.
-     * @param {EventRegistryHandle} handler - The function originally bound to the event.
+     * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
      * @param {boolean|EventListenerOptions} [options] - Optional listener options.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3718,7 +3856,7 @@ class TinyHtml {
      * Removes all event listeners of all types from the element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
-     * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
+     * @param {((handler: EventListenerOrEventListenerObject|null, event: string) => boolean)|null} [filterFn=null] -
      *        Optional filter function to selectively remove specific handlers.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */
@@ -3743,7 +3881,7 @@ class TinyHtml {
     /**
      * Removes all event listeners of all types from the element.
      *
-     * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
+     * @param {((handler: EventListenerOrEventListenerObject|null, event: string) => boolean)|null} [filterFn=null] -
      *        Optional filter function to selectively remove specific handlers.
      * @returns {TinyEventTarget|TinyEventTarget[]}
      */