tiny-essentials 1.17.0 → 1.18.0

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

@@ -1,4 +1,18 @@
 export default TinyHtml;
+/**
+ * Callback invoked on each animation frame with the current scroll position,
+ * normalized animation time (`0` to `1`), and a completion flag.
+ */
+export type OnScrollAnimation = (progress: {
+    x: number;
+    y: number;
+    isComplete: boolean;
+    time: number;
+}) => void;
+/**
+ * A list of supported easing function names for smooth animations.
+ */
+export type Easings = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic";
 /**
  * Represents a raw Node element or an instance of TinyHtml.
  * This type is used to abstract interactions with both plain elements
@@ -51,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:
@@ -66,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`.
@@ -82,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.
      */
@@ -201,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;
@@ -453,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[];
@@ -463,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.
@@ -1084,6 +1158,15 @@ declare class TinyHtml {
      * @returns {number}
      */
     static outerWidth(el: TinyElementAndWinAndDoc, includeMargin?: boolean): number;
+    /**
+     * 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: TinyElement | TinyElement[], keyframes: Keyframe[] | PropertyIndexedKeyframes | null, ops?: number | KeyframeAnimationOptions): TinyElement | TinyElement[];
     /**
      * Gets the offset of the element relative to the document.
      * @param {TinyElement} el - Target element.
@@ -1120,6 +1203,41 @@ declare class TinyHtml {
      * @returns {number}
      */
     static scrollLeft(el: TinyElementAndWindow): number;
+    /**
+     * 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 easings: Record<string, (t: number) => number>;
+    /**
+     * 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: TinyElementAndWindow | TinyElementAndWindow[], { targetX, targetY, duration, easing, onAnimation }?: {
+        targetX?: number | undefined;
+        targetY?: number | undefined;
+        duration?: number | undefined;
+        easing?: Easings | undefined;
+        onAnimation?: OnScrollAnimation | undefined;
+    }): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Sets the vertical scroll position.
      * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
@@ -1421,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.
      *
@@ -1463,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.
      *
@@ -2093,6 +2244,14 @@ declare class TinyHtml {
      * @returns {number}
      */
     outerWidth(includeMargin?: boolean): number;
+    /**
+     * 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: Keyframe[] | PropertyIndexedKeyframes | null, ops?: number | KeyframeAnimationOptions): TinyElement | TinyElement[];
     /**
      * Gets the offset of the element relative to the document.
      * @returns {{top: number, left: number}}
@@ -2124,6 +2283,28 @@ declare class TinyHtml {
      * @returns {number}
      */
     scrollLeft(): number;
+    /**
+     * 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 }?: {
+        targetX?: number | undefined;
+        targetY?: number | undefined;
+        duration?: number | undefined;
+        easing?: Easings | undefined;
+        onAnimation?: OnScrollAnimation | undefined;
+    }): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Sets the vertical scroll position.
      * @param {number} value - Scroll top value.
@@ -2310,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.
      *
@@ -2347,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.
      *