tiny-essentials 1.17.1 → 1.18.1

package/dist/v1/libs/TinyHtml.cjs

@@ -94,6 +94,21 @@ const {
  * @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:
@@ -113,12 +128,6 @@ const {
  * @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`.
@@ -130,7 +139,7 @@ const {
  * 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.
  */
 
@@ -689,9 +698,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) {
@@ -708,9 +717,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) {
@@ -724,6 +733,32 @@ class TinyHtml {
     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.
@@ -3983,12 +4018,120 @@ class TinyHtml {
 
   ////////////////////////////////////////////
 
+  /**
+   * 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[]}
    */
@@ -4010,7 +4153,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[]}
    */
@@ -4023,17 +4166,17 @@ 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[]}
    */
   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 {EventRegistryHandle} e */
+      /** @type {EventListenerOrEventListenerObject} */
       const wrapped = (e) => {
         TinyHtml.off(elem, event, wrapped);
-        handler(e);
+        if (typeof handler === 'function') handler(e);
       };
 
       TinyHtml.on(
@@ -4050,7 +4193,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[]}
    */
@@ -4063,7 +4206,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[]}
    */
@@ -4085,7 +4228,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[]}
    */
@@ -4128,7 +4271,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[]}
    */
@@ -4155,7 +4298,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[]}
    */

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

@@ -65,6 +65,17 @@ export type TinyElementAndWinAndDoc = ElementAndWinAndDoc | TinyHtml;
  * Useful for functions that operate generically on scrollable or measurable targets.
  */
 export type ElementAndWinAndDoc = Element | Window | Document;
+/**
+ * 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.
+ */
+export type TinyElementWithDoc = ElementWithDoc | TinyHtml;
+/**
+ * Represents a value that can be either a DOM Element, or the document object.
+ * Useful for functions that operate generically on measurable targets.
+ */
+export type ElementWithDoc = Element | Document;
 /**
  * A parameter type used for filtering or matching elements.
  * It can be:
@@ -80,10 +91,6 @@ export type WinnowRequest = string | Element | Element[] | ((index: number, el:
  * These include common DOM elements and root containers.
  */
 export type ConstructorElValues = Window | Element | Document | Text;
-/**
- * The handler function used in event listeners.
- */
-export type EventRegistryHandle = (e: Event) => any;
 /**
  * Options passed to `addEventListener` or `removeEventListener`.
  * Can be a boolean or an object of type `AddEventListenerOptions`.
@@ -96,7 +103,7 @@ export type EventRegistryItem = {
     /**
      * - The function to be executed when the event is triggered.
      */
-    handler: EventRegistryHandle;
+    handler: EventListenerOrEventListenerObject | null;
     /**
      * - Optional configuration passed to the listener.
      */
@@ -215,8 +222,41 @@ declare class TinyHtml {
         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;
-        getElsPerfColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => "top" | "bottom" | "left" | "right" | null;
+        getElsColliding: (
+        /**
+         * @typedef {'string' | 'date' | 'number'} GetValueTypes
+         * Types of value extractors supported by TinyHtml._valTypes.
+         */
+        /**
+         * @typedef {SetValueBase|SetValueBase[]} SetValueList - A single value or an array of values to be assigned to the input element.
+         */
+        /**
+         * A list of HTML form elements that can have a `.value` property used by TinyHtml.
+         * Includes common input types used in forms.
+         *
+         * @typedef {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement|HTMLOptionElement} InputElement
+         */
+        /**
+         * TinyHtml is a utility class that provides static and instance-level methods
+         * for precise dimension and position computations on HTML elements.
+         * It mimics some jQuery functionalities while using native browser APIs.
+         *
+         * 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.
+         *
+         * @class
+         */
+        rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => string | null;
+        getElsPerfColliding: (rect1: TinyCollision.ObjRect /**
+         * TinyHtml is a utility class that provides static and instance-level methods
+         * for precise dimension and position computations on HTML elements.
+         * It mimics some jQuery functionalities while using native browser APIs.
+         *
+         * 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.
+         *
+         * @class
+         */, rect2: TinyCollision.ObjRect) => "top" | "bottom" | "left" | "right" | null;
         getElsCollOverlap: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => {
             overlapLeft: number;
             overlapRight: number;
@@ -467,9 +507,9 @@ declare 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 readonly _preElemsAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow[];
@@ -477,12 +517,32 @@ declare 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 readonly _preElemAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow;
+    /**
+     * 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 readonly _preElemsWithDoc(elems: TinyElementWithDoc | TinyElementWithDoc[], where: string): ElementWithDoc[];
+    /**
+     * 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 readonly _preElemWithDoc(elems: TinyElementWithDoc | TinyElementWithDoc[], where: string): ElementWithDoc;
     /**
      * Normalizes and converts one or more DOM elements (or TinyHtml instances)
      * into an array of `TinyHtml` instances.
@@ -1479,36 +1539,69 @@ declare class TinyHtml {
      * @throws {Error} If the element is not a checkbox/radio input.
      */
     static valBool(el: TinyInputElement): boolean;
+    /**
+     * 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: TinyElementWithDoc | TinyElementWithDoc[], { onFilePaste, onTextPaste }?: {
+        onFilePaste?: ((data: DataTransferItem, file: File) => void) | undefined;
+        onTextPaste?: ((data: DataTransferItem, text: string) => void) | undefined;
+    }): EventListenerOrEventListenerObject;
+    /**
+     * 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: TinyEventTarget, event: string): boolean;
+    /**
+     * 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: TinyEventTarget, event: string, handler: EventListenerOrEventListenerObject): boolean;
     /**
      * 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[]}
      */
-    static on(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
+    static on(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventListenerOrEventListenerObject | null, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * 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 {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[]}
      */
-    static once(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
+    static once(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventListenerOrEventListenerObject, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes a specific event listener from an element.
      *
      * @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[]}
      */
-    static off(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
+    static off(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes all event listeners of a specific type from the element.
      *
@@ -1521,11 +1614,11 @@ declare 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[]}
      */
-    static offAllTypes(el: TinyEventTarget | TinyEventTarget[], filterFn?: ((handler: EventListenerOrEventListenerObject, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
+    static offAllTypes(el: TinyEventTarget | TinyEventTarget[], filterFn?: ((handler: EventListenerOrEventListenerObject | null, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
     /**
      * Triggers all handlers associated with a specific event on the given element.
      *
@@ -2398,33 +2491,63 @@ declare class TinyHtml {
      * @throws {Error} If the element is not a checkbox/radio input.
      */
     valBool(): boolean;
+    /**
+     * 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 }?: {
+        onFilePaste?: ((data: DataTransferItem, file: File) => void) | undefined;
+        onTextPaste?: ((data: DataTransferItem, text: string) => void) | undefined;
+    }): EventListenerOrEventListenerObject;
+    /**
+     * Checks if the element has a listener for a specific event.
+     *
+     * @param {string} event - The event name to check.
+     * @returns {boolean}
+     */
+    hasEventListener(event: string): boolean;
+    /**
+     * 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: string, handler: EventListenerOrEventListenerObject): boolean;
     /**
      * 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[]}
      */
-    on(event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
+    on(event: string, handler: EventListenerOrEventListenerObject | null, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * 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[]}
      */
-    once(event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
+    once(event: string, handler: EventListenerOrEventListenerObject, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * 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[]}
      */
-    off(event: string, handler: EventRegistryHandle, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
+    off(event: string, handler: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes all event listeners of a specific type from the element.
      *
@@ -2435,11 +2558,11 @@ declare 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[]}
      */
-    offAllTypes(filterFn?: ((handler: EventListenerOrEventListenerObject, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
+    offAllTypes(filterFn?: ((handler: EventListenerOrEventListenerObject | null, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
     /**
      * Triggers all handlers associated with a specific event on the given element.
      *