tiny-essentials 1.17.0 → 1.17.1

package/dist/v1/libs/TinyHtml.cjs

@@ -11,6 +11,19 @@ const {
   areElsCollRight,
 } = collision;
 
+/**
+ * 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
@@ -2419,7 +2432,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);
   }
 
   /**
@@ -2428,7 +2441,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);
   }
 
   /**
@@ -2745,6 +2758,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.
@@ -2900,26 +2937,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.
@@ -2937,17 +3095,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 });
   }
 
   /**

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
@@ -1084,6 +1098,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 +1143,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.
@@ -2093,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}}
@@ -2124,6 +2190,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.

package/dist/v1/libs/TinyHtml.mjs

@@ -1,5 +1,16 @@
 import * as TinyCollision from '../basics/collision.mjs';
 const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, } = TinyCollision;
+/**
+ * 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
@@ -2179,7 +2190,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);
     }
     /**
      * Sets the horizontal scroll position of the window.
@@ -2188,7 +2199,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);
     }
     /**
      * Gets the vertical scroll position of the window.
@@ -2464,6 +2475,28 @@ class TinyHtml {
         return TinyHtml.outerWidth(this, includeMargin);
     }
     //////////////////////////////////////////////////
+    /**
+     * 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.
@@ -2598,28 +2631,142 @@ class TinyHtml {
         return TinyHtml.scrollLeft(this);
     }
     /**
-     * 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.
@@ -2637,19 +2784,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 });
     }
     /**
      * Sets the horizontal scroll position.