tiny-essentials 1.16.2 → 1.17.1

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
@@ -40,6 +54,17 @@ export type TinyElementAndWindow = ElementAndWindow | TinyHtml;
  * Useful for functions that operate generically on scrollable or measurable targets.
  */
 export type ElementAndWindow = Element | Window;
+/**
+ * Represents a raw DOM element/window/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 TinyElementAndWinAndDoc = ElementAndWinAndDoc | TinyHtml;
+/**
+ * Represents a value that can be either a DOM Element, or the global Window object, or the document object.
+ * Useful for functions that operate generically on scrollable or measurable targets.
+ */
+export type ElementAndWinAndDoc = Element | Window | Document;
 /**
  * A parameter type used for filtering or matching elements.
  * It can be:
@@ -54,7 +79,7 @@ export type WinnowRequest = string | Element | Element[] | ((index: number, el:
  * Elements accepted as constructor values for TinyHtml.
  * These include common DOM elements and root containers.
  */
-export type ConstructorElValues = Window | Element | Document;
+export type ConstructorElValues = Window | Element | Document | Text;
 /**
  * The handler function used in event listeners.
  */
@@ -186,34 +211,7 @@ declare class TinyHtml {
         areElsCollRight: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsCollPerfTop: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsCollPerfBottom: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
-        areElsCollPerfLeft: (rect1: TinyCollision.ObjRect, 
-        /**
-         * @typedef {string | number | Date | boolean | null} SetValueBase - Primitive types accepted as input values.
-         */
-        /**
-         * @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
-         */
-        rect2: TinyCollision.ObjRect) => boolean;
+        areElsCollPerfLeft: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsCollPerfRight: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
         areElsPerfColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
@@ -239,36 +237,66 @@ declare class TinyHtml {
             y: number;
         };
     };
+    /**
+     * Creates a new DOM element with the specified tag name and options, then wraps it in a TinyHtml instance.
+     *
+     * @param {string} tagName - The tag name of the element to create (e.g., 'div', 'span').
+     * @param {ElementCreationOptions} ops - Optional settings for creating the element.
+     * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM element.
+     * @throws {TypeError} If tagName is not a string or ops is not an object.
+     */
+    static createElement(tagName: string, ops: ElementCreationOptions): TinyHtml;
+    /**
+     * Creates a new TinyHtml instance that wraps a DOM TextNode.
+     *
+     * This method is useful when you want to insert raw text content into the DOM
+     * without it being interpreted as HTML. The returned instance behaves like any
+     * other TinyHtml element and can be appended or manipulated as needed.
+     *
+     * @param {string} value - The plain text content to be wrapped in a TextNode.
+     * @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM TextNode.
+     * @throws {TypeError} If the provided value is not a string.
+     */
+    static createTextNode(value: string): TinyHtml;
+    /**
+     * Creates an HTMLElement or TextNode from an HTML string.
+     * Supports both elements and plain text.
+     *
+     * @param {string} htmlString - The HTML string to convert.
+     * @returns {TinyHtml} - A single HTMLElement or TextNode.
+     */
+    static createElementFromHTML(htmlString: string): TinyHtml;
     /**
      * Queries the document for the first element matching the CSS selector and wraps it in a TinyHtml instance.
      *
      * @param {string} selector - A valid CSS selector string.
-     * @returns {TinyHtml} A TinyHtml instance wrapping the matched element.
-     * @throws {Error} If no element matches the selector.
+     * @param {Document|Element} elem - Target element.
+     * @returns {TinyHtml|null} A TinyHtml instance wrapping the matched element.
      */
-    static query(selector: string): TinyHtml;
+    static query(selector: string, elem?: Document | Element): TinyHtml | null;
     /**
      * Queries the document for all elements matching the CSS selector and wraps them in TinyHtml instances.
      *
      * @param {string} selector - A valid CSS selector string.
+     * @param {Document|Element} elem - Target element.
      * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
      */
-    static queryAll(selector: string): TinyHtml[];
+    static queryAll(selector: string, elem?: Document | Element): TinyHtml[];
     /**
      * Retrieves an element by its ID and wraps it in a TinyHtml instance.
      *
      * @param {string} selector - The ID of the element to retrieve.
-     * @returns {TinyHtml} A TinyHtml instance wrapping the found element.
-     * @throws {Error} If no element is found with the specified ID.
+     * @returns {TinyHtml|null} A TinyHtml instance wrapping the found element.
      */
-    static getById(selector: string): TinyHtml;
+    static getById(selector: string): TinyHtml | null;
     /**
      * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
      *
      * @param {string} selector - The class name to search for.
+     * @param {Document|Element} elem - Target element.
      * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
      */
-    static getByClassName(selector: string): TinyHtml[];
+    static getByClassName(selector: string, elem?: Document | Element): TinyHtml[];
     /**
      * Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
      *
@@ -282,9 +310,10 @@ declare class TinyHtml {
      *
      * @param {string} localName - The local name (tag) of the elements to search for.
      * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
+     * @param {Document|Element} elem - Target element.
      * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
      */
-    static getByTagNameNS(localName: string, namespaceURI?: string | null): TinyHtml[];
+    static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml[];
     /**
      * @param {TinyElement|EventTarget|null|(TinyElement|EventTarget|null)[]} elems
      * @param {string} where
@@ -434,6 +463,26 @@ declare class TinyHtml {
      * @readonly
      */
     static readonly _preElemAndWindow(elems: TinyElementAndWindow | TinyElementAndWindow[], where: string): ElementAndWindow;
+    /**
+     * 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 {string} where - The method or context name where validation is being called.
+     * @returns {ElementAndWindow[]} - Always returns an array of element/window elements.
+     * @readonly
+     */
+    static readonly _preElemsAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow[];
+    /**
+     * 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 {string} where - The method or context name where validation is being called.
+     * @returns {ElementAndWindow} - Always returns an single element/window element.
+     * @readonly
+     */
+    static readonly _preElemAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow;
     /**
      * Normalizes and converts one or more DOM elements (or TinyHtml instances)
      * into an array of `TinyHtml` instances.
@@ -568,9 +617,9 @@ declare class TinyHtml {
      * @param {string} key - The key under which the data will be stored.
      * @param {any} value - The value to store.
      * @param {boolean} [isPrivate=false] - Whether to store the data in the private store.
-     * @returns {void}
+     * @returns {TinyElement}
      */
-    static setData(el: TinyElement, key: string, value: any, isPrivate?: boolean): void;
+    static setData(el: TinyElement, key: string, value: any, isPrivate?: boolean): TinyElement;
     /**
      * Get the sibling element in a given direction.
      *
@@ -691,76 +740,86 @@ declare class TinyHtml {
     /**
      * Appends child elements or strings to the end of the target element(s).
      *
-     * @param {TinyElement | TinyElement[]} el - The target element(s) to receive children.
+     * @param {TinyElement} el - The target element(s) to receive children.
      * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+     * @returns {TinyElement}
      */
-    static append(el: TinyElement | TinyElement[], ...children: (TinyNode | TinyNode[] | string)[]): void;
+    static append(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
-     * @param {TinyElement | TinyElement[]} el - The target element(s) to receive children.
+     * @param {TinyElement} el - The target element(s) to receive children.
      * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+     * @returns {TinyElement}
      */
-    static prepend(el: TinyElement | TinyElement[], ...children: (TinyNode | TinyNode[] | string)[]): void;
+    static prepend(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
-     * @param {TinyElement | TinyElement[]} el - The target element(s) before which new content is inserted.
+     * @param {TinyElement} el - The target element(s) before which new content is inserted.
      * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+     * @returns {TinyElement}
      */
-    static before(el: TinyElement | TinyElement[], ...children: (TinyNode | TinyNode[] | string)[]): void;
+    static before(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
-     * @param {TinyElement | TinyElement[]} el - The target element(s) after which new content is inserted.
+     * @param {TinyElement} el - The target element(s) after which new content is inserted.
      * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+     * @returns {TinyElement}
      */
-    static after(el: TinyElement | TinyElement[], ...children: (TinyNode | TinyNode[] | string)[]): void;
+    static after(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
-     * @param {TinyElement | TinyElement[]} el - The element(s) to be replaced.
+     * @param {TinyElement} el - The element(s) to be replaced.
      * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+     * @returns {TinyElement}
      */
-    static replaceWith(el: TinyElement | TinyElement[], ...newNodes: (TinyNode | TinyNode[] | string)[]): void;
+    static replaceWith(el: TinyElement, ...newNodes: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Appends the given element(s) to each target element in sequence.
      *
      * @param {TinyNode | TinyNode[]} el - The element(s) to append.
      * @param {TinyNode | TinyNode[]} targets - Target element(s) where content will be appended.
+     * @returns {TinyNode|TinyNode[]}
      */
-    static appendTo(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): void;
+    static appendTo(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
     /**
      * Prepends the given element(s) to each target element in sequence.
      *
      * @param {TinyElement | TinyElement[]} el - The element(s) to prepend.
      * @param {TinyElement | TinyElement[]} targets - Target element(s) where content will be prepended.
+     * @returns {TinyElement|TinyElement[]}
      */
-    static prependTo(el: TinyElement | TinyElement[], targets: TinyElement | TinyElement[]): void;
+    static prependTo(el: TinyElement | TinyElement[], targets: TinyElement | TinyElement[]): TinyElement | TinyElement[];
     /**
      * Inserts the element before a child of a given target, or before the target itself.
      *
      * @param {TinyNode | TinyNode[]} el - The element(s) to insert.
      * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
      * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert before, defaults to target.
+     * @returns {TinyNode|TinyNode[]}
      */
-    static insertBefore(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): void;
+    static insertBefore(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
     /**
      * Inserts the element after a child of a given target, or after the target itself.
      *
      * @param {TinyNode | TinyNode[]} el - The element(s) to insert.
      * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
      * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert after, defaults to target.
+     * @returns {TinyNode|TinyNode[]}
      */
-    static insertAfter(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): void;
+    static insertAfter(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
     /**
      * Replaces all target elements with the provided element(s).
      * If multiple targets exist, the inserted elements are cloned accordingly.
      *
      * @param {TinyNode | TinyNode[]} el - The new element(s) to insert.
      * @param {TinyNode | TinyNode[]} targets - The elements to be replaced.
+     * @returns {TinyNode|TinyNode[]}
      */
-    static replaceAll(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): void;
+    static replaceAll(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
     /**
      * Checks whether the given object is a window.
      * @param {*} obj - The object to test.
@@ -847,8 +906,9 @@ declare class TinyHtml {
      * @param {TinyHtmlElement|TinyHtmlElement[]} el - The element to inspect.
      * @param {string|Object} prop - The property name or an object with key-value pairs
      * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    static setStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string | Object, value?: string | null): void;
+    static setStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string | Object, value?: string | null): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Gets the value of a specific inline style property.
      *
@@ -881,8 +941,9 @@ declare class TinyHtml {
      *
      * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element or an array of elements.
      * @param {string|string[]} prop - A property name or an array of property names to remove.
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    static removeStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string | string[]): void;
+    static removeStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string | string[]): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Toggles a CSS property value between two given values.
      *
@@ -892,26 +953,40 @@ declare class TinyHtml {
      * @param {string} prop - The CSS property to toggle.
      * @param {string} val1 - The first value (used as "current" check).
      * @param {string} val2 - The second value (used as the "alternative").
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    static toggleStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string, val1: string, val2: string): void;
+    static toggleStyle(el: TinyHtmlElement | TinyHtmlElement[], prop: string, val1: string, val2: string): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Removes all inline styles (`style` attribute) from the given element(s).
      *
      * @param {TinyElement|TinyElement[]} el - A single element or an array of elements.
+     * @returns {TinyElement|TinyElement[]}
      */
-    static clearStyle(el: TinyElement | TinyElement[]): void;
+    static clearStyle(el: TinyElement | TinyElement[]): TinyElement | TinyElement[];
     /**
      * Focus the element.
      *
      * @param {TinyHtmlElement} el - The element or a selector string.
+     * @returns {TinyHtmlElement}
      */
-    static focus(el: TinyHtmlElement): void;
+    static focus(el: TinyHtmlElement): TinyHtmlElement;
     /**
      * Blur the element.
      *
      * @param {TinyHtmlElement} el - The element or a selector string.
+     * @returns {TinyHtmlElement}
      */
-    static blur(el: TinyHtmlElement): void;
+    static blur(el: TinyHtmlElement): TinyHtmlElement;
+    /**
+     * Interprets a value as a boolean `true` if it matches a common truthy representation.
+     *
+     * This method checks if the input is any of the common forms used to represent `true`,
+     * such as the string `'true'`, `'1'`, `'on'`, the boolean `true`, or the number `1`.
+     *
+     * @param {string|boolean|number} [value] - The value to interpret as boolean.
+     * @returns {boolean} `true` if the value represents a truthy state, otherwise `false`.
+     */
+    static boolCheck(value?: string | boolean | number): boolean;
     /**
      * Sets the vertical scroll position of the window.
      * @param {number} value - Sets the scroll position.
@@ -942,67 +1017,96 @@ declare class TinyHtml {
      * @returns {number} - Viewport width in pixels.
      */
     static winInnerWidth(): number;
+    /**
+     * Checks if the page is currently scrolled to the very top.
+     *
+     * This method compares the current vertical scroll position with the total document height.
+     * It's useful for detecting if the user has reached the top of the page.
+     *
+     * @returns {boolean} `true` if the page is scrolled to the top, otherwise `false`.
+     */
+    static isPageTop(): boolean;
+    /**
+     * Checks if the page is currently scrolled to the very bottom.
+     *
+     * This method uses the `scrollY` and `innerHeight` properties to determine if the
+     * user has reached the end of the document.
+     *
+     * @returns {boolean} `true` if the page is scrolled to the bottom, otherwise `false`.
+     */
+    static isPageBottom(): boolean;
     /**
      * Gets the width or height of an element based on the box model.
-     * @param {TinyElementAndWindow} el - The element or window.
+     * @param {TinyElementAndWinAndDoc} el - The element or window.
      * @param {"width"|"height"} type - Dimension type.
      * @param {"content"|"padding"|"border"|"margin"} [extra='content'] - Box model context.
      * @returns {number} - Computed dimension.
      * @throws {TypeError} If `type` or `extra` is not a string.
      */
-    static getDimension(el: TinyElementAndWindow, type: "width" | "height", extra?: "content" | "padding" | "border" | "margin"): number;
+    static getDimension(el: TinyElementAndWinAndDoc, type: "width" | "height", extra?: "content" | "padding" | "border" | "margin"): number;
     /**
      * Sets the height of the element.
      * @param {TinyHtmlElement} el - Target element.
      * @param {string|number} value - Height value.
      * @throws {TypeError} If `value` is neither a string nor number.
+     * @returns {TinyHtmlElement}
      */
-    static setHeight(el: TinyHtmlElement, value: string | number): void;
+    static setHeight(el: TinyHtmlElement, value: string | number): TinyHtmlElement;
     /**
      * Sets the width of the element.
      * @param {TinyHtmlElement} el - Target element.
      * @param {string|number} value - Width value.
      * @throws {TypeError} If `value` is neither a string nor number.
+     * @returns {TinyHtmlElement}
      */
-    static setWidth(el: TinyHtmlElement, value: string | number): void;
+    static setWidth(el: TinyHtmlElement, value: string | number): TinyHtmlElement;
     /**
      * Returns content box height.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
-    static height(el: TinyElementAndWindow): number;
+    static height(el: TinyElementAndWinAndDoc): number;
     /**
      * Returns content box width.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
-    static width(el: TinyElementAndWindow): number;
+    static width(el: TinyElementAndWinAndDoc): number;
     /**
      * Returns padding box height.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
-    static innerHeight(el: TinyElementAndWindow): number;
+    static innerHeight(el: TinyElementAndWinAndDoc): number;
     /**
      * Returns padding box width.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
-    static innerWidth(el: TinyElementAndWindow): number;
+    static innerWidth(el: TinyElementAndWinAndDoc): number;
     /**
      * Returns outer height of the element, optionally including margin.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @param {boolean} [includeMargin=false] - Whether to include margin.
      * @returns {number}
      */
-    static outerHeight(el: TinyElementAndWindow, includeMargin?: boolean): number;
+    static outerHeight(el: TinyElementAndWinAndDoc, includeMargin?: boolean): number;
     /**
      * Returns outer width of the element, optionally including margin.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @param {boolean} [includeMargin=false] - Whether to include margin.
      * @returns {number}
      */
-    static outerWidth(el: TinyElementAndWindow, includeMargin?: boolean): 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.
@@ -1039,18 +1143,55 @@ 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.
      * @param {number} value - Scroll top value.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
-    static setScrollTop(el: TinyElementAndWindow | TinyElementAndWindow[], value: number): void;
+    static setScrollTop(el: TinyElementAndWindow | TinyElementAndWindow[], value: number): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Sets the horizontal scroll position.
      * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
      * @param {number} value - Scroll left value.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
-    static setScrollLeft(el: TinyElementAndWindow | TinyElementAndWindow[], value: number): void;
+    static setScrollLeft(el: TinyElementAndWindow | TinyElementAndWindow[], value: number): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Returns the total border width and individual sides from `border{Side}Width` CSS properties.
      *
@@ -1079,8 +1220,8 @@ declare class TinyHtml {
      * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) paddings, and each side individually.
      */
     static padding(el: TinyElement): HtmlElBoxSides;
-    static addClass(el: TinyElement | TinyElement[], ...tokens: string[]): void;
-    static removeClass(el: TinyElement | TinyElement[], ...tokens: string[]): void;
+    static addClass(el: TinyElement | TinyElement[], ...tokens: string[]): (TinyElement | TinyElement[]);
+    static removeClass(el: TinyElement | TinyElement[], ...tokens: string[]): (TinyElement | TinyElement[]);
     /**
      * Replaces an existing class name with a new one.
      * @param {TinyElement|TinyElement[]} el - Target element.
@@ -1149,25 +1290,29 @@ declare class TinyHtml {
      * Set text content of elements.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
-    static setText(el: TinyElement | TinyElement[], value: string): void;
+    static setText(el: TinyElement | TinyElement[], value: string): TinyElement | TinyElement[];
     /**
      * Remove all child nodes from each element.
      * @param {TinyElement|TinyElement[]} el
+     * @returns {TinyElement|TinyElement[]}
      */
-    static empty(el: TinyElement | TinyElement[]): void;
+    static empty(el: TinyElement | TinyElement[]): TinyElement | TinyElement[];
     /**
      * Get the innerHTML of the element.
-     * @param {TinyElement|TinyElement[]} el
+     * @param {TinyElement} el
+     * @param {GetHTMLOptions} [ops]
      * @returns {string}
      */
-    static html(el: TinyElement | TinyElement[]): string;
+    static html(el: TinyElement, ops?: GetHTMLOptions): string;
     /**
      * Set the innerHTML of each element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
-    static setHtml(el: TinyElement | TinyElement[], value: string): void;
+    static setHtml(el: TinyElement | TinyElement[], value: string): TinyElement | TinyElement[];
     /** @readonly */
     static readonly _valHooks: {
         option: {
@@ -1221,8 +1366,9 @@ declare class TinyHtml {
      * @param {TinyInputElement|TinyInputElement[]} el - Target element.
      * @param {SetValueList|((el: InputElement, val: SetValueList) => SetValueList)} value - The value to assign or a function that returns it.
      * @throws {Error} If the computed value is not a valid string or boolean.
+     * @returns {TinyInputElement|TinyInputElement[]}
      */
-    static setVal(el: TinyInputElement | TinyInputElement[], value: SetValueList | ((el: InputElement, val: SetValueList) => SetValueList)): void;
+    static setVal(el: TinyInputElement | TinyInputElement[], value: SetValueList | ((el: InputElement, val: SetValueList) => SetValueList)): TinyInputElement | TinyInputElement[];
     /**
      * Maps value types to their corresponding getter functions.
      * Each function extracts a value of a specific type from a compatible HTMLInputElement.
@@ -1340,8 +1486,9 @@ declare class TinyHtml {
      * @param {string} event - The event type (e.g. 'click', 'keydown').
      * @param {EventRegistryHandle} 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): void;
+    static on(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Registers an event listener that runs only once, then is removed.
      *
@@ -1349,8 +1496,9 @@ declare class TinyHtml {
      * @param {string} event - The event type (e.g. 'click', 'keydown').
      * @param {EventRegistryHandle} 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): void;
+    static once(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes a specific event listener from an element.
      *
@@ -1358,31 +1506,35 @@ declare class TinyHtml {
      * @param {string} event - The event type.
      * @param {EventRegistryHandle} 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): void;
+    static off(el: TinyEventTarget | TinyEventTarget[], event: string, handler: EventRegistryHandle, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes all event listeners of a specific type from the element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
      * @param {string} event - The event type to remove (e.g. 'click').
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static offAll(el: TinyEventTarget | TinyEventTarget[], event: string): void;
+    static offAll(el: TinyEventTarget | TinyEventTarget[], event: string): TinyEventTarget | TinyEventTarget[];
     /**
      * 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] -
      *        Optional filter function to selectively remove specific handlers.
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static offAllTypes(el: TinyEventTarget | TinyEventTarget[], filterFn?: ((handler: EventListenerOrEventListenerObject, event: string) => boolean) | null): void;
+    static offAllTypes(el: TinyEventTarget | TinyEventTarget[], filterFn?: ((handler: EventListenerOrEventListenerObject, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
     /**
      * Triggers all handlers associated with a specific event on the given element.
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - Target element where the event should be triggered.
      * @param {string} event - Name of the event to trigger.
      * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    static trigger(el: TinyEventTarget | TinyEventTarget[], event: string, payload?: Event | CustomEvent | CustomEventInit): void;
+    static trigger(el: TinyEventTarget | TinyEventTarget[], event: string, payload?: Event | CustomEvent | CustomEventInit): TinyEventTarget | TinyEventTarget[];
     /**
      * Property name normalization similar to jQuery's propFix.
      * @readonly
@@ -1403,14 +1555,16 @@ declare class TinyHtml {
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
      * @param {string|null} [value=null]
+     * @returns {TinyElement|TinyElement[]}
      */
-    static setAttr(el: TinyElement | TinyElement[], name: string, value?: string | null): void;
+    static setAttr(el: TinyElement | TinyElement[], name: string, value?: string | null): TinyElement | TinyElement[];
     /**
      * Remove attribute(s) from an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name Space-separated list of attributes.
+     * @returns {TinyElement|TinyElement[]}
      */
-    static removeAttr(el: TinyElement | TinyElement[], name: string): void;
+    static removeAttr(el: TinyElement | TinyElement[], name: string): TinyElement | TinyElement[];
     /**
      * Check if an attribute exists on an element.
      * @param {TinyElement} el
@@ -1429,14 +1583,16 @@ declare class TinyHtml {
      * Set a property on an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
-    static addProp(el: TinyElement | TinyElement[], name: string): void;
+    static addProp(el: TinyElement | TinyElement[], name: string): TinyElement | TinyElement[];
     /**
      * Remove a property from an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
-    static removeProp(el: TinyElement | TinyElement[], name: string): void;
+    static removeProp(el: TinyElement | TinyElement[], name: string): TinyElement | TinyElement[];
     /**
      * Toggle a boolean property.
      * @param {TinyElement|TinyElement[]} el
@@ -1447,8 +1603,9 @@ declare class TinyHtml {
     /**
      * Removes an element from the DOM.
      * @param {TinyElement|TinyElement[]} el - The DOM element or selector to remove.
+     * @returns {TinyElement|TinyElement[]}
      */
-    static remove(el: TinyElement | TinyElement[]): void;
+    static remove(el: TinyElement | TinyElement[]): TinyElement | TinyElement[];
     /**
      * Returns the index of the first element within its parent or relative to a selector/element.
      *
@@ -1554,12 +1711,68 @@ declare class TinyHtml {
      * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
      */
     static isScrolledIntoView(el: TinyElement): boolean;
+    /**
+     * Checks if the given element is at least partially visible within the boundaries of a container.
+     *
+     * @param {TinyElement} el - The DOM element to check.
+     * @param {TinyElement} cont - The container element acting as the viewport.
+     * @returns {boolean} True if the element is partially visible within the container, false otherwise.
+     */
+    static isInContainer(el: TinyElement, cont: TinyElement): boolean;
+    /**
+     * Checks if the given element is fully visible within the boundaries of a container (top and bottom).
+     *
+     * @param {TinyElement} el - The DOM element to check.
+     * @param {TinyElement} cont - The container element acting as the viewport.
+     * @returns {boolean} True if the element is fully visible within the container, false otherwise.
+     */
+    static isFullyInContainer(el: TinyElement, cont: TinyElement): boolean;
+    /**
+     * Checks if an element has scrollable content.
+     *
+     * @param {TinyElement} el - The DOM element to check.
+     * @returns {{ v: boolean, h: boolean }} - True if scroll is needed in that direction.
+     */
+    static hasScroll(el: TinyElement): {
+        v: boolean;
+        h: boolean;
+    };
     /**
      * Creates an instance of TinyHtml for a specific Element.
      * Useful when you want to operate repeatedly on the same element using instance methods.
      * @param {ConstructorElValues} el - The element to wrap and manipulate.
      */
     constructor(el: ConstructorElValues);
+    /**
+     * Queries the element for the first element matching the CSS selector and wraps it in a TinyHtml instance.
+     *
+     * @param {string} selector - A valid CSS selector string.
+     * @returns {TinyHtml|null} A TinyHtml instance wrapping the matched element.
+     */
+    querySelector(selector: string): TinyHtml | null;
+    /**
+     * Queries the element for all elements matching the CSS selector and wraps them in TinyHtml instances.
+     *
+     * @param {string} selector - A valid CSS selector string.
+     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the matched elements.
+     */
+    querySelectorAll(selector: string): TinyHtml[];
+    /**
+     * Retrieves all elements with the specified class name and wraps them in TinyHtml instances.
+     *
+     * @param {string} selector - The class name to search for.
+     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     */
+    getElementsByClassName(selector: string): TinyHtml[];
+    /**
+     * Retrieves all elements with the specified local tag name within the given namespace URI,
+     * and wraps them in TinyHtml instances.
+     *
+     * @param {string} localName - The local name (tag) of the elements to search for.
+     * @param {string|null} [namespaceURI='http://www.w3.org/1999/xhtml'] - The namespace URI to search within.
+     * @returns {TinyHtml[]} An array of TinyHtml instances wrapping the found elements.
+     */
+    getElementsByTagNameNS(localName: string, namespaceURI?: string | null): TinyHtml[];
     /**
      * Returns the current target held by this instance.
      *
@@ -1637,9 +1850,9 @@ declare class TinyHtml {
      * @param {string} key - The key under which the data will be stored.
      * @param {any} value - The value to store.
      * @param {boolean} [isPrivate=false] - Whether to store the data in the private store.
-     * @returns {void}
+     * @returns {TinyElement}
      */
-    setData(key: string, value: any, isPrivate?: boolean): void;
+    setData(key: string, value: any, isPrivate?: boolean): TinyElement;
     /**
      * Returns the direct parent node of the given element, excluding document fragments.
      *
@@ -1719,65 +1932,75 @@ declare class TinyHtml {
      * Appends child elements or strings to the end of the target element(s).
      *
      * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
+     * @returns {TinyElement}
      */
-    append(...children: (TinyNode | TinyNode[] | string)[]): void;
+    append(...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Prepends child elements or strings to the beginning of the target element(s).
      *
      * @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
+     * @returns {TinyElement}
      */
-    prepend(...children: (TinyNode | TinyNode[] | string)[]): void;
+    prepend(...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Inserts elements or strings immediately before the target element(s) in the DOM.
      *
      * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
+     * @returns {TinyElement}
      */
-    before(...children: (TinyNode | TinyNode[] | string)[]): void;
+    before(...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Inserts elements or strings immediately after the target element(s) in the DOM.
      *
      * @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
+     * @returns {TinyElement}
      */
-    after(...children: (TinyNode | TinyNode[] | string)[]): void;
+    after(...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Replaces the target element(s) in the DOM with new elements or text.
      *
      * @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
+     * @returns {TinyElement}
      */
-    replaceWith(...newNodes: (TinyNode | TinyNode[] | string)[]): void;
+    replaceWith(...newNodes: (TinyNode | TinyNode[] | string)[]): TinyElement;
     /**
      * Appends the given element(s) to each target element in sequence.
      *
      * @param {TinyNode | TinyNode[]} targets - Target element(s) where content will be appended.
+     * @returns {TinyNode|TinyNode[]}
      */
-    appendTo(targets: TinyNode | TinyNode[]): void;
+    appendTo(targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
     /**
      * Prepends the given element(s) to each target element in sequence.
      *
      * @param {TinyElement | TinyElement[]} targets - Target element(s) where content will be prepended.
+     * @returns {TinyElement|TinyElement[]}
      */
-    prependTo(targets: TinyElement | TinyElement[]): void;
+    prependTo(targets: TinyElement | TinyElement[]): TinyElement | TinyElement[];
     /**
      * Inserts the element before a child of a given target, or before the target itself.
      *
      * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
      * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert before, defaults to target.
+     * @returns {TinyNode|TinyNode[]}
      */
-    insertBefore(target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): void;
+    insertBefore(target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
     /**
      * Inserts the element after a child of a given target, or after the target itself.
      *
      * @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
      * @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert after, defaults to target.
+     * @returns {TinyNode|TinyNode[]}
      */
-    insertAfter(target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): void;
+    insertAfter(target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
     /**
      * Replaces all target elements with the provided element(s).
      * If multiple targets exist, the inserted elements are cloned accordingly.
      *
      * @param {TinyNode | TinyNode[]} targets - The elements to be replaced.
+     * @returns {TinyNode|TinyNode[]}
      */
-    replaceAll(targets: TinyNode | TinyNode[]): void;
+    replaceAll(targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
     /**
      * Returns the full computed CSS styles for the given element.
      *
@@ -1818,8 +2041,9 @@ declare class TinyHtml {
      *
      * @param {string|Object} prop - The property name or an object with key-value pairs
      * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    setStyle(prop: string | Object, value?: string | null): void;
+    setStyle(prop: string | Object, value?: string | null): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Gets the value of a specific inline style property.
      *
@@ -1847,8 +2071,9 @@ declare class TinyHtml {
      * Removes one or more inline CSS properties from the given element(s).
      *
      * @param {string|string[]} prop - A property name or an array of property names to remove.
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    removeStyle(prop: string | string[]): void;
+    removeStyle(prop: string | string[]): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Toggles a CSS property value between two given values.
      *
@@ -1857,21 +2082,24 @@ declare class TinyHtml {
      * @param {string} prop - The CSS property to toggle.
      * @param {string} val1 - The first value (used as "current" check).
      * @param {string} val2 - The second value (used as the "alternative").
+     * @returns {TinyHtmlElement|TinyHtmlElement[]}
      */
-    toggleStyle(prop: string, val1: string, val2: string): void;
+    toggleStyle(prop: string, val1: string, val2: string): TinyHtmlElement | TinyHtmlElement[];
     /**
      * Removes all inline styles (`style` attribute) from the given element(s).
-     *
+     * @returns {TinyElement|TinyElement[]}
      */
-    clearStyle(): void;
+    clearStyle(): TinyElement | TinyElement[];
     /**
      * Focus the element.
+     * @returns {TinyHtmlElement}
      */
-    focus(): void;
+    focus(): TinyHtmlElement;
     /**
      * Blur the element.
+     * @returns {TinyHtmlElement}
      */
-    blur(): void;
+    blur(): TinyHtmlElement;
     /**
      * Gets the width or height of an element based on the box model.
      * @param {"width"|"height"} type - Dimension type.
@@ -1882,13 +2110,15 @@ declare class TinyHtml {
     /**
      * Sets the height of the element.
      * @param {string|number} value - Height value.
+     * @returns {TinyHtmlElement}
      */
-    setHeight(value: string | number): void;
+    setHeight(value: string | number): TinyHtmlElement;
     /**
      * Sets the width of the element.
      * @param {string|number} value - Width value.
+     * @returns {TinyHtmlElement}
      */
-    setWidth(value: string | number): void;
+    setWidth(value: string | number): TinyHtmlElement;
     /**
      * Returns content box height.
      * @returns {number}
@@ -1921,6 +2151,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}}
@@ -1952,16 +2190,40 @@ 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.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
-    setScrollTop(value: number): void;
+    setScrollTop(value: number): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Sets the horizontal scroll position.
      * @param {number} value - Scroll left value.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
-    setScrollLeft(value: number): void;
+    setScrollLeft(value: number): TinyElementAndWindow | TinyElementAndWindow[];
     /**
      * Returns the total border width and individual sides from `border{Side}Width` CSS properties.
      *
@@ -1986,8 +2248,8 @@ declare class TinyHtml {
      * @returns {HtmlElBoxSides} - Total horizontal (x) and vertical (y) paddings, and each side individually.
      */
     padding(): HtmlElBoxSides;
-    addClass(...tokens: string[]): void;
-    removeClass(...tokens: string[]): void;
+    addClass(...tokens: string[]): (TinyElement | TinyElement[]);
+    removeClass(...tokens: string[]): (TinyElement | TinyElement[]);
     /**
      * Replaces an existing class name with a new one.
      * @param {string} token - The class name to be replaced.
@@ -2046,30 +2308,35 @@ declare class TinyHtml {
     /**
      * Set text content of the element.
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
-    setText(value: string): void;
+    setText(value: string): TinyElement | TinyElement[];
     /**
      * Remove all child nodes of the element.
+     * @returns {TinyElement|TinyElement[]}
      */
-    empty(): void;
+    empty(): TinyElement | TinyElement[];
     /**
      * Get the innerHTML of the element.
+     * @param {GetHTMLOptions} [ops]
      * @returns {string}
      */
-    html(): string;
+    html(ops?: GetHTMLOptions): string;
     /**
      * Set the innerHTML of the element.
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
-    setHtml(value: string): void;
+    setHtml(value: string): TinyElement | TinyElement[];
     /**
      * Sets the value of the current HTML value element (input, select, textarea, etc.).
      * Accepts strings, numbers, booleans or arrays of these values, or a callback function that computes them.
      *
      * @param {SetValueList|((el: InputElement, val: SetValueList) => SetValueList)} value - The value to assign or a function that returns it.
+     * @returns {TinyInputElement|TinyInputElement[]}
      * @throws {Error} If the computed value is not a valid string or boolean.
      */
-    setVal(value: SetValueList | ((el: InputElement, val: SetValueList) => SetValueList)): void;
+    setVal(value: SetValueList | ((el: InputElement, val: SetValueList) => SetValueList)): TinyInputElement | TinyInputElement[];
     /**
      * Retrieves the raw value from the HTML input element.
      * If a custom value hook exists, it will be used first.
@@ -2137,44 +2404,50 @@ declare class TinyHtml {
      * @param {string} event - The event type (e.g. 'click', 'keydown').
      * @param {EventRegistryHandle} 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): void;
+    on(event: string, handler: EventRegistryHandle, 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 {EventRegistryOptions} [options={}] - Optional event listener options.
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    once(event: string, handler: EventRegistryHandle, options?: EventRegistryOptions): void;
+    once(event: string, handler: EventRegistryHandle, 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 {boolean|EventListenerOptions} [options] - Optional listener options.
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    off(event: string, handler: EventRegistryHandle, options?: boolean | EventListenerOptions): void;
+    off(event: string, handler: EventRegistryHandle, options?: boolean | EventListenerOptions): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes all event listeners of a specific type from the element.
      *
      * @param {string} event - The event type to remove (e.g. 'click').
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    offAll(event: string): void;
+    offAll(event: string): TinyEventTarget | TinyEventTarget[];
     /**
      * Removes all event listeners of all types from the element.
      *
      * @param {((handler: EventListenerOrEventListenerObject, 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): void;
+    offAllTypes(filterFn?: ((handler: EventListenerOrEventListenerObject, event: string) => boolean) | null): TinyEventTarget | TinyEventTarget[];
     /**
      * Triggers all handlers associated with a specific event on the given element.
      *
      * @param {string} event - Name of the event to trigger.
      * @param {Event|CustomEvent|CustomEventInit} [payload] - Optional event object or data to pass.
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
-    trigger(event: string, payload?: Event | CustomEvent | CustomEventInit): void;
+    trigger(event: string, payload?: Event | CustomEvent | CustomEventInit): TinyEventTarget | TinyEventTarget[];
     /**
      * Get an attribute on an element.
      * @param {string} name
@@ -2185,13 +2458,15 @@ declare class TinyHtml {
      * Set an attribute on an element.
      * @param {string} name
      * @param {string|null} [value=null]
+     * @returns {TinyElement|TinyElement[]}
      */
-    setAttr(name: string, value?: string | null): void;
+    setAttr(name: string, value?: string | null): TinyElement | TinyElement[];
     /**
      * Remove attribute(s) from an element.
      * @param {string} name Space-separated list of attributes.
+     * @returns {TinyElement|TinyElement[]}
      */
-    removeAttr(name: string): void;
+    removeAttr(name: string): TinyElement | TinyElement[];
     /**
      * Check if an attribute exists on an element.
      * @param {string} name
@@ -2207,13 +2482,15 @@ declare class TinyHtml {
     /**
      * Set a property on an element.
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
-    addProp(name: string): void;
+    addProp(name: string): TinyElement | TinyElement[];
     /**
      * Remove a property from an element.
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
-    removeProp(name: string): void;
+    removeProp(name: string): TinyElement | TinyElement[];
     /**
      * Toggle a boolean property.
      * @param {string} name
@@ -2222,8 +2499,9 @@ declare class TinyHtml {
     toggleProp(name: string, force?: boolean): void;
     /**
      * Removes the element from the DOM.
+     * @returns {TinyElement|TinyElement[]}
      */
-    remove(): void;
+    remove(): TinyElement | TinyElement[];
     /**
      * Returns the index of the first element within its parent or relative to a selector/element.
      *
@@ -2295,6 +2573,29 @@ declare class TinyHtml {
      * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
      */
     isScrolledIntoView(): boolean;
+    /**
+     * Checks if the given element is at least partially visible within the boundaries of a container.
+     *
+     * @param {TinyElement} cont - The container element acting as the viewport.
+     * @returns {boolean} True if the element is partially visible within the container, false otherwise.
+     */
+    isInContainer(cont: TinyElement): boolean;
+    /**
+     * Checks if the given element is fully visible within the boundaries of a container (top and bottom).
+     *
+     * @param {TinyElement} cont - The container element acting as the viewport.
+     * @returns {boolean} True if the element is fully visible within the container, false otherwise.
+     */
+    isFullyInContainer(cont: TinyElement): boolean;
+    /**
+     * Checks if an element has scrollable content.
+     *
+     * @returns {{ v: boolean, h: boolean }} - True if scroll is needed in that direction.
+     */
+    hasScroll(): {
+        v: boolean;
+        h: boolean;
+    };
     #private;
 }
 import * as TinyCollision from '../basics/collision.mjs';