tiny-essentials 1.17.0 → 1.18.0

package/dist/v1/TinySmartScroller.js

@@ -470,6 +470,19 @@ const {
   areElsCollRight: TinyHtml_areElsCollRight,
 } = collision_namespaceObject;
 
+/**
+ * Callback invoked on each animation frame with the current scroll position,
+ * normalized animation time (`0` to `1`), and a completion flag.
+ *
+ * @typedef {(progress: { x: number, y: number, isComplete: boolean, time: number }) => void} OnScrollAnimation
+ */
+
+/**
+ * A list of supported easing function names for smooth animations.
+ *
+ * @typedef {'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic'} Easings
+ */
+
 /**
  * Represents a raw Node element or an instance of TinyHtml.
  * This type is used to abstract interactions with both plain elements
@@ -540,6 +553,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:
@@ -559,12 +587,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`.
@@ -576,7 +598,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.
  */
 
@@ -1135,9 +1157,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) {
@@ -1154,9 +1176,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) {
@@ -1170,6 +1192,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.
@@ -2878,7 +2926,7 @@ class TinyHtml {
    */
   static setWinScrollTop(value) {
     if (typeof value !== 'number') throw new TypeError('The value must be a number.');
-    window.scrollTo({ top: value });
+    TinyHtml.setScrollTop(window, value);
   }
 
   /**
@@ -2887,7 +2935,7 @@ class TinyHtml {
    */
   static setWinScrollLeft(value) {
     if (typeof value !== 'number') throw new TypeError('The value must be a number.');
-    window.scrollTo({ left: value });
+    TinyHtml.setScrollLeft(window, value);
   }
 
   /**
@@ -3204,6 +3252,30 @@ class TinyHtml {
 
   //////////////////////////////////////////////////
 
+  /**
+   * Applies an animation to one or multiple TinyElement instances.
+   *
+   * @param {TinyElement|TinyElement[]} el - A single TinyElement or an array of TinyElements to animate.
+   * @param {Keyframe[] | PropertyIndexedKeyframes | null} keyframes - The keyframes used to define the animation.
+   * @param {number | KeyframeAnimationOptions} [ops] - Timing or configuration options for the animation.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static animate(el, keyframes, ops) {
+    TinyHtml._preElems(el, 'animate').forEach((elem) => elem.animate(keyframes, ops));
+    return el;
+  }
+
+  /**
+   * Applies an animation to one or multiple TinyElement instances.
+   *
+   * @param {Keyframe[] | PropertyIndexedKeyframes | null} keyframes - The keyframes used to define the animation.
+   * @param {number | KeyframeAnimationOptions} [ops] - Timing or configuration options for the animation.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  animate(keyframes, ops) {
+    return TinyHtml.animate(this, keyframes, ops);
+  }
+
   /**
    * Gets the offset of the element relative to the document.
    * @param {TinyElement} el - Target element.
@@ -3359,26 +3431,147 @@ class TinyHtml {
   }
 
   /**
-   * Sets the vertical scroll position.
-   * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
-   * @param {number} value - Scroll top value.
-   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   * Collection of easing functions used for scroll and animation calculations.
+   * Each function receives a normalized time value (`t` from 0 to 1) and returns the eased progress.
+   *
+   * @type {Record<string, (t: number) => number>}
    */
-  static setScrollTop(el, value) {
-    if (typeof value !== 'number') throw new TypeError('ScrollTop value must be a number.');
-    TinyHtml._preElemsAndWindow(el, 'setScrollTop').forEach((elem) => {
-      if (TinyHtml.isWindow(elem)) {
-        elem.scrollTo(elem.pageXOffset, value);
+  static easings = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => --t * t * t + 1,
+    easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1),
+  };
+
+  /**
+   * Smoothly scrolls one or more elements (or the window) to the specified X and Y coordinates
+   * using a custom duration and easing function.
+   *
+   * If `duration` or a valid `easing` is not provided, the scroll will be performed immediately.
+   *
+   * @param {TinyElementAndWindow | TinyElementAndWindow[]} el - A single element, array of elements, or the window to scroll.
+   * @param {Object} [settings={}] - Configuration object for the scroll animation.
+   * @param {number} [settings.targetX] - The horizontal scroll target in pixels.
+   * @param {number} [settings.targetY] - The vertical scroll target in pixels.
+   * @param {number} [settings.duration] - The duration of the animation in milliseconds.
+   * @param {Easings} [settings.easing] - The easing function name to use for the scroll animation.
+   * @param {OnScrollAnimation} [settings.onAnimation] - Optional callback invoked on each animation
+   *   frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   * @throws {TypeError} If `el` is not a valid element, array, or window.
+   * @throws {TypeError} If `targetX` or `targetY` is defined but not a number.
+   * @throws {TypeError} If `duration` is defined but not a number.
+   * @throws {TypeError} If `easing` is defined but not a valid easing function name.
+   * @throws {TypeError} If `onAnimation` is defined but not a function.
+   */
+  static scrollToXY(el, { targetX, targetY, duration, easing, onAnimation } = {}) {
+    if (targetX !== undefined && typeof targetX !== 'number')
+      throw new TypeError('`targetX` must be a number if provided.');
+    if (targetY !== undefined && typeof targetY !== 'number')
+      throw new TypeError('`targetY` must be a number if provided.');
+    if (duration !== undefined && typeof duration !== 'number')
+      throw new TypeError('`duration` must be a number if provided.');
+    if (easing !== undefined && typeof easing !== 'string')
+      throw new TypeError('`easing` must be a string if provided.');
+    if (easing !== undefined && typeof TinyHtml.easings[easing] !== 'function')
+      throw new TypeError(`Unknown easing function: "${easing}".`);
+    if (onAnimation !== undefined && typeof onAnimation !== 'function')
+      throw new TypeError('`onAnimation` must be a function if provided.');
+
+    /**
+     * Performs an instant scroll to the given coordinates.
+     *
+     * @param {ElementAndWindow} elem - The element or window to scroll.
+     * @param {number} newX - The final horizontal scroll position.
+     * @param {number} newY - The final vertical scroll position.
+     * @param {number} time - Normalized progress value.
+     */
+    const executeScroll = (elem, newX, newY, time) => {
+      if (elem instanceof Window) {
+        window.scrollTo(newX, newY);
       } else if (elem.nodeType === 9) {
         // @ts-ignore
-        elem.defaultView.scrollTo(elem.defaultView.pageXOffset, value);
+        elem.defaultView.scrollTo(newX, newY);
       } else {
-        elem.scrollTop = value;
+        const startX = elem instanceof Window ? window.scrollX : elem.scrollLeft;
+        const startY = elem instanceof Window ? window.scrollY : elem.scrollTop;
+        if (startX !== newX) elem.scrollLeft = newX;
+        if (startY !== newY) elem.scrollTop = newY;
       }
+      if (typeof onAnimation === 'function')
+        onAnimation({ x: newX, y: newY, isComplete: time >= 1, time });
+    };
+
+    TinyHtml._preElemsAndWindow(el, 'scrollToXY').forEach((elem) => {
+      const startX = elem instanceof Window ? window.scrollX : elem.scrollLeft;
+      const startY = elem instanceof Window ? window.scrollY : elem.scrollTop;
+      const targX = targetX ?? startX;
+      const targY = targetY ?? startY;
+
+      const changeX = targX - startX;
+      const changeY = targY - startY;
+
+      const ease = (typeof easing === 'string' && TinyHtml.easings[easing]) || null;
+      if (typeof duration !== 'number' || typeof ease !== 'function')
+        return executeScroll(elem, targX, targY, 1);
+      const startTime = performance.now();
+      const dur = duration ?? 0;
+
+      /**
+       * Animates the scroll position based on easing and time.
+       *
+       * @param {number} currentTime - Timestamp provided by requestAnimationFrame.
+       */
+      function animateScroll(currentTime) {
+        if (typeof ease !== 'function') return;
+        const time = Math.min(1, (currentTime - startTime) / dur);
+        const easedTime = ease(time);
+
+        const newX = startX + changeX * easedTime;
+        const newY = startY + changeY * easedTime;
+        executeScroll(elem, newX, newY, time);
+
+        if (time < 1) requestAnimationFrame(animateScroll);
+      }
+
+      requestAnimationFrame(animateScroll);
     });
     return el;
   }
 
+  /**
+   * Smoothly scrolls one or more elements (or the window) to the specified X and Y coordinates
+   * using a custom duration and easing function.
+   *
+   * If `duration` or a valid `easing` is not provided, the scroll will be performed immediately.
+   *
+   * @param {Object} [settings={}] - Configuration object for the scroll animation.
+   * @param {number} [settings.targetX] - The horizontal scroll target in pixels.
+   * @param {number} [settings.targetY] - The vertical scroll target in pixels.
+   * @param {number} [settings.duration] - The duration of the animation in milliseconds.
+   * @param {Easings} [settings.easing] - The easing function name to use for the scroll animation.
+   * @param {OnScrollAnimation} [settings.onAnimation] - Optional callback invoked on each animation
+   *   frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   */
+  scrollToXY({ targetX, targetY, duration, easing, onAnimation } = {}) {
+    return TinyHtml.scrollToXY(this, { targetX, targetY, duration, easing, onAnimation });
+  }
+
+  /**
+   * Sets the vertical scroll position.
+   * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
+   * @param {number} value - Scroll top value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   */
+  static setScrollTop(el, value) {
+    if (typeof value !== 'number') throw new TypeError('ScrollTop value must be a number.');
+    return TinyHtml.scrollToXY(el, { targetY: value });
+  }
+
   /**
    * Sets the vertical scroll position.
    * @param {number} value - Scroll top value.
@@ -3396,17 +3589,7 @@ class TinyHtml {
    */
   static setScrollLeft(el, value) {
     if (typeof value !== 'number') throw new TypeError('ScrollLeft value must be a number.');
-    TinyHtml._preElemsAndWindow(el, 'setScrollLeft').forEach((elem) => {
-      if (TinyHtml.isWindow(elem)) {
-        elem.scrollTo(value, elem.pageYOffset);
-      } else if (elem.nodeType === 9) {
-        // @ts-ignore
-        elem.defaultView.scrollTo(value, elem.defaultView.pageYOffset);
-      } else {
-        elem.scrollLeft = value;
-      }
-    });
-    return el;
+    return TinyHtml.scrollToXY(el, { targetX: value });
   }
 
   /**
@@ -4294,12 +4477,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[]}
    */
@@ -4321,7 +4612,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[]}
    */
@@ -4334,17 +4625,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(
@@ -4361,7 +4652,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[]}
    */
@@ -4374,7 +4665,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[]}
    */
@@ -4396,7 +4687,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[]}
    */
@@ -4439,7 +4730,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[]}
    */
@@ -4466,7 +4757,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[]}
    */