tiny-essentials 1.16.2 → 1.17.1

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
@@ -48,6 +59,19 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  *
  * @typedef {Element|Window} ElementAndWindow
  */
+/**
+ * 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.
+ *
+ * @typedef {ElementAndWinAndDoc|TinyHtml} TinyElementAndWinAndDoc
+ */
+/**
+ * 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.
+ *
+ * @typedef {Element|Window|Document} ElementAndWinAndDoc
+ */
 /**
  * A parameter type used for filtering or matching elements.
  * It can be:
@@ -63,7 +87,7 @@ const { areElsColliding, areElsPerfColliding, areElsCollTop, areElsCollBottom, a
  * Elements accepted as constructor values for TinyHtml.
  * These include common DOM elements and root containers.
  *
- * @typedef {Window|Element|Document} ConstructorElValues
+ * @typedef {Window|Element|Document|Text} ConstructorElValues
  */
 /**
  * The handler function used in event listeners.
@@ -167,52 +191,130 @@ const __elemCollision = {
 class TinyHtml {
     /** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
     static Utils = { ...TinyCollision };
+    /**
+     * 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, ops) {
+        if (typeof tagName !== 'string')
+            throw new TypeError(`[TinyHtml] createElement(): The tagName must be a string.`);
+        if (typeof ops !== 'undefined' && typeof ops !== 'object')
+            throw new TypeError(`[TinyHtml] createElement(): The ops must be a object.`);
+        return new TinyHtml(document.createElement(tagName, ops));
+    }
+    /**
+     * 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) {
+        if (typeof value !== 'string')
+            throw new TypeError(`[TinyHtml] createTextNode(): The value must be a string.`);
+        return new TinyHtml(document.createTextNode(value));
+    }
+    /**
+     * 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) {
+        const template = document.createElement('template');
+        htmlString = htmlString.trim();
+        // If it's only text (e.g., no "<" tag), return a TextNode
+        if (!htmlString.startsWith('<')) {
+            return TinyHtml.createTextNode(htmlString);
+        }
+        template.innerHTML = htmlString;
+        if (!(template.content.firstChild instanceof Element))
+            throw new Error('');
+        return new TinyHtml(template.content.firstChild);
+    }
     /**
      * 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) {
-        const newEl = document.querySelector(selector);
+    static query(selector, elem = document) {
+        const newEl = elem.querySelector(selector);
         if (!newEl)
-            throw new Error(`[TinyHtml] query(): No element found for selector "${selector}".`);
+            return null;
         return new TinyHtml(newEl);
     }
+    /**
+     * 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) {
+        return TinyHtml.query(selector, TinyHtml._preElem(this, 'query'));
+    }
     /**
      * 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) {
-        const newEls = document.querySelectorAll(selector);
+    static queryAll(selector, elem = document) {
+        const newEls = elem.querySelectorAll(selector);
         return TinyHtml.toTinyElm([...newEls]);
     }
+    /**
+     * 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) {
+        return TinyHtml.queryAll(selector, TinyHtml._preElem(this, 'queryAll'));
+    }
     /**
      * 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) {
         const newEl = document.getElementById(selector);
         if (!newEl)
-            throw new Error(`[TinyHtml] getById(): No element found with ID "${selector}".`);
+            return null;
         return new TinyHtml(newEl);
     }
     /**
      * 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) {
-        const newEls = document.getElementsByClassName(selector);
+    static getByClassName(selector, elem = document) {
+        const newEls = elem.getElementsByClassName(selector);
         return TinyHtml.toTinyElm([...newEls]);
     }
+    /**
+     * 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) {
+        return TinyHtml.getByClassName(selector, TinyHtml._preElem(this, 'getByClassName'));
+    }
     /**
      * Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
      *
@@ -229,12 +331,24 @@ 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, namespaceURI = 'http://www.w3.org/1999/xhtml') {
-        const newEls = document.getElementsByTagNameNS(namespaceURI, localName);
+    static getByTagNameNS(localName, namespaceURI = 'http://www.w3.org/1999/xhtml', elem = document) {
+        const newEls = elem.getElementsByTagNameNS(namespaceURI, localName);
         return TinyHtml.toTinyElm([...newEls]);
     }
+    /**
+     * 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, namespaceURI = 'http://www.w3.org/1999/xhtml') {
+        return TinyHtml.getByTagNameNS(localName, namespaceURI, TinyHtml._preElem(this, 'getByTagNameNS'));
+    }
     //////////////////////////////////////////////////////////////////
     /**
      * Returns the current target held by this instance.
@@ -477,6 +591,34 @@ class TinyHtml {
     static _preElemAndWindow(elems, where) {
         return TinyHtml._preElemTemplate(elems, where, [Element, Window], ['Element', 'Window']);
     }
+    /**
+     * 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 _preElemsAndWinAndDoc(elems, where) {
+        const result = TinyHtml._preElemsTemplate(elems, where, [Element, Window, Document], ['Element', 'Window', 'Document']);
+        return result.map((elem) => (!(elem instanceof Document) ? elem : elem.documentElement));
+    }
+    /**
+     * 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 _preElemAndWinAndDoc(elems, where) {
+        const result = TinyHtml._preElemTemplate(elems, where, [Element, Window, Document], ['Element', 'Window', 'Document']);
+        if (result instanceof Document)
+            return result.documentElement;
+        return result;
+    }
     /**
      * Normalizes and converts one or more DOM elements (or TinyHtml instances)
      * into an array of `TinyHtml` instances.
@@ -779,13 +921,14 @@ 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, key, value, isPrivate = false) {
         const data = TinyHtml._dataSelector[!isPrivate ? 'public' : 'private']('setData', el);
         if (typeof key !== 'string')
             throw new TypeError('The key must be a string.');
         data[key] = value;
+        return el;
     }
     /**
      * Stores a value associated with a specific key for a DOM element.
@@ -793,7 +936,7 @@ 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, value, isPrivate = false) {
         return TinyHtml.setData(this, key, value, isPrivate);
@@ -1111,17 +1254,20 @@ 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, ...children) {
         const elem = TinyHtml._preElem(el, 'append');
         elem.append(...TinyHtml._appendChecker('append', ...children));
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.append(this, ...children);
@@ -1129,17 +1275,20 @@ class TinyHtml {
     /**
      * 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, ...children) {
         const elem = TinyHtml._preElem(el, 'prepend');
         elem.prepend(...TinyHtml._appendChecker('prepend', ...children));
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.prepend(this, ...children);
@@ -1147,17 +1296,20 @@ class TinyHtml {
     /**
      * 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, ...children) {
         const elem = TinyHtml._preElem(el, 'before');
         elem.before(...TinyHtml._appendChecker('before', ...children));
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.before(this, ...children);
@@ -1165,17 +1317,20 @@ class TinyHtml {
     /**
      * 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, ...children) {
         const elem = TinyHtml._preElem(el, 'after');
         elem.after(...TinyHtml._appendChecker('after', ...children));
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.after(this, ...children);
@@ -1183,17 +1338,20 @@ class TinyHtml {
     /**
      * 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, ...newNodes) {
         const elem = TinyHtml._preElem(el, 'replaceWith');
         elem.replaceWith(...TinyHtml._appendChecker('replaceWith', ...newNodes));
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.replaceWith(this, ...newNodes);
@@ -1203,6 +1361,7 @@ class TinyHtml {
      *
      * @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, targets) {
         const elems = TinyHtml._preNodeElems(el, 'appendTo');
@@ -1210,11 +1369,13 @@ class TinyHtml {
         tars.forEach((target, i) => {
             elems.forEach((elem) => target.appendChild(i === tars.length - 1 ? elem : elem.cloneNode(true)));
         });
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.appendTo(this, targets);
@@ -1224,6 +1385,7 @@ class TinyHtml {
      *
      * @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, targets) {
         const elems = TinyHtml._preElems(el, 'prependTo');
@@ -1234,11 +1396,13 @@ class TinyHtml {
                 .reverse()
                 .forEach((elem) => target.prepend(i === tars.length - 1 ? elem : elem.cloneNode(true)));
         });
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.prependTo(this, targets);
@@ -1249,6 +1413,7 @@ class TinyHtml {
      * @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, target, child = null) {
         const elem = TinyHtml._preNodeElem(el, 'insertBefore');
@@ -1257,12 +1422,14 @@ class TinyHtml {
         if (!targ.parentNode)
             throw new Error('');
         targ.parentNode.insertBefore(elem, childNode || targ);
+        return el;
     }
     /**
      * 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, child) {
         return TinyHtml.insertBefore(this, target, child);
@@ -1273,6 +1440,7 @@ class TinyHtml {
      * @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, target, child = null) {
         const elem = TinyHtml._preNodeElem(el, 'insertAfter');
@@ -1281,12 +1449,14 @@ class TinyHtml {
         if (!targ.parentNode)
             throw new Error('');
         targ.parentNode.insertBefore(elem, childNode || targ.nextSibling);
+        return el;
     }
     /**
      * 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, child) {
         return TinyHtml.insertAfter(this, target, child);
@@ -1297,6 +1467,7 @@ class TinyHtml {
      *
      * @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, targets) {
         const elems = TinyHtml._preNodeElems(el, 'replaceAll');
@@ -1308,12 +1479,14 @@ class TinyHtml {
                     parent.replaceChild(i === tars.length - 1 ? elem : elem.cloneNode(true), target);
             });
         });
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.replaceAll(this, targets);
@@ -1332,7 +1505,10 @@ class TinyHtml {
     constructor(el) {
         if (el instanceof TinyHtml)
             throw new Error(`[TinyHtml] You are trying to put a TinyHtml inside another TinyHtml in constructor.`);
-        if (!(el instanceof Element) && !(el instanceof Window) && !(el instanceof Document))
+        if (!(el instanceof Element) &&
+            !(el instanceof Window) &&
+            !(el instanceof Document) &&
+            !(el instanceof Text))
             throw new Error(`[TinyHtml] Invalid Target in constructor.`);
         this.#el = el;
     }
@@ -1764,6 +1940,7 @@ 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, prop, value = null) {
         TinyHtml._preHtmlElems(el, 'setStyle').forEach((elem) => {
@@ -1775,6 +1952,7 @@ class TinyHtml {
             else
                 elem.style.setProperty(TinyHtml.toStyleKc(prop), value);
         });
+        return el;
     }
     /**
      * Sets one or more CSS inline style properties on the given element(s).
@@ -1784,6 +1962,7 @@ 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, value) {
         return TinyHtml.setStyle(this, prop, value);
@@ -1872,6 +2051,7 @@ 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, prop) {
         TinyHtml._preHtmlElems(el, 'removeStyle').forEach((elem) => {
@@ -1883,11 +2063,13 @@ class TinyHtml {
             else
                 elem.style.removeProperty(TinyHtml.toStyleKc(prop));
         });
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.removeStyle(this, prop);
@@ -1901,6 +2083,7 @@ 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, prop, val1, val2) {
         TinyHtml._preHtmlElems(el, 'toggleStyle').forEach((elem) => {
@@ -1908,6 +2091,7 @@ class TinyHtml {
             const newVal = current === TinyHtml.toStyleKc(val1) ? val2 : val1;
             TinyHtml.setStyle(elem, prop, newVal);
         });
+        return el;
     }
     /**
      * Toggles a CSS property value between two given values.
@@ -1917,6 +2101,7 @@ 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, val1, val2) {
         return TinyHtml.toggleStyle(this, prop, val1, val2);
@@ -1925,13 +2110,15 @@ class TinyHtml {
      * 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) {
         TinyHtml._preElems(el, 'clearStyle').forEach((elem) => elem.removeAttribute('style'));
+        return el;
     }
     /**
      * Removes all inline styles (`style` attribute) from the given element(s).
-     *
+     * @returns {TinyElement|TinyElement[]}
      */
     clearStyle() {
         return TinyHtml.clearStyle(this);
@@ -1941,13 +2128,16 @@ class TinyHtml {
      * Focus the element.
      *
      * @param {TinyHtmlElement} el - The element or a selector string.
+     * @returns {TinyHtmlElement}
      */
     static focus(el) {
         const elem = TinyHtml._preHtmlElem(el, 'focus');
         elem.focus();
+        return el;
     }
     /**
      * Focus the element.
+     * @returns {TinyHtmlElement}
      */
     focus() {
         return TinyHtml.focus(this);
@@ -1956,17 +2146,42 @@ class TinyHtml {
      * Blur the element.
      *
      * @param {TinyHtmlElement} el - The element or a selector string.
+     * @returns {TinyHtmlElement}
      */
     static blur(el) {
         const elem = TinyHtml._preHtmlElem(el, 'blur');
         elem.blur();
+        return el;
     }
     /**
      * Blur the element.
+     * @returns {TinyHtmlElement}
      */
     blur() {
         return TinyHtml.blur(this);
     }
+    /**
+     * 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) {
+        if (typeof value !== 'undefined' &&
+            (value === 'true' ||
+                value === '1' ||
+                value === true ||
+                value === 'on' ||
+                (typeof value === 'number' && value > 0))) {
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
     //////////////////////////////////////////////////////////////////////
     /**
      * Sets the vertical scroll position of the window.
@@ -1975,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.
@@ -1984,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.
@@ -2014,16 +2229,38 @@ class TinyHtml {
     static winInnerWidth() {
         return window.innerWidth || document.documentElement.clientWidth;
     }
+    /**
+     * 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() {
+        return window.scrollY === 0;
+    }
+    /**
+     * 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() {
+        return window.innerHeight + window.scrollY >= document.body.offsetHeight;
+    }
     /**
      * 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, type, extra = 'content') {
-        const elem = TinyHtml._preElemAndWindow(el, 'getDimension');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'getDimension');
         if (typeof type !== 'string')
             throw new TypeError('The type must be a string.');
         if (typeof extra !== 'string')
@@ -2094,16 +2331,19 @@ class TinyHtml {
      * @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, value) {
         const elem = TinyHtml._preHtmlElem(el, 'setHeight');
         if (typeof value !== 'number' && typeof value !== 'string')
             throw new TypeError('The value must be a string or number.');
         elem.style.height = typeof value === 'number' ? `${value}px` : value;
+        return el;
     }
     /**
      * Sets the height of the element.
      * @param {string|number} value - Height value.
+     * @returns {TinyHtmlElement}
      */
     setHeight(value) {
         return TinyHtml.setHeight(this, value);
@@ -2113,27 +2353,30 @@ class TinyHtml {
      * @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, value) {
         const elem = TinyHtml._preHtmlElem(el, 'setWidth');
         if (typeof value !== 'number' && typeof value !== 'string')
             throw new TypeError('The value must be a string or number.');
         elem.style.width = typeof value === 'number' ? `${value}px` : value;
+        return el;
     }
     /**
      * Sets the width of the element.
      * @param {string|number} value - Width value.
+     * @returns {TinyHtmlElement}
      */
     setWidth(value) {
         return TinyHtml.setWidth(this, value);
     }
     /**
      * Returns content box height.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
     static height(el) {
-        const elem = TinyHtml._preElemAndWindow(el, 'height');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'height');
         return TinyHtml.getDimension(elem, 'height', 'content');
     }
     /**
@@ -2145,11 +2388,11 @@ class TinyHtml {
     }
     /**
      * Returns content box width.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
     static width(el) {
-        const elem = TinyHtml._preElemAndWindow(el, 'width');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'width');
         return TinyHtml.getDimension(elem, 'width', 'content');
     }
     /**
@@ -2161,11 +2404,11 @@ class TinyHtml {
     }
     /**
      * Returns padding box height.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
     static innerHeight(el) {
-        const elem = TinyHtml._preElemAndWindow(el, 'innerHeight');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'innerHeight');
         return TinyHtml.getDimension(elem, 'height', 'padding');
     }
     /**
@@ -2177,11 +2420,11 @@ class TinyHtml {
     }
     /**
      * Returns padding box width.
-     * @param {TinyElementAndWindow} el - Target element.
+     * @param {TinyElementAndWinAndDoc} el - Target element.
      * @returns {number}
      */
     static innerWidth(el) {
-        const elem = TinyHtml._preElemAndWindow(el, 'innerWidth');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'innerWidth');
         return TinyHtml.getDimension(elem, 'width', 'padding');
     }
     /**
@@ -2193,14 +2436,14 @@ class TinyHtml {
     }
     /**
      * 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, includeMargin = false) {
         if (typeof includeMargin !== 'boolean')
             throw new TypeError('The "includeMargin" must be a boolean.');
-        const elem = TinyHtml._preElemAndWindow(el, 'outerHeight');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'outerHeight');
         return TinyHtml.getDimension(elem, 'height', includeMargin ? 'margin' : 'border');
     }
     /**
@@ -2213,14 +2456,14 @@ class TinyHtml {
     }
     /**
      * 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, includeMargin = false) {
         if (typeof includeMargin !== 'boolean')
             throw new TypeError('The "includeMargin" must be a boolean.');
-        const elem = TinyHtml._preElemAndWindow(el, 'outerWidth');
+        const elem = TinyHtml._preElemAndWinAndDoc(el, 'outerWidth');
         return TinyHtml.getDimension(elem, 'width', includeMargin ? 'margin' : 'border');
     }
     /**
@@ -2232,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.
@@ -2366,29 +2631,146 @@ class TinyHtml {
         return TinyHtml.scrollLeft(this);
     }
     /**
-     * Sets the vertical scroll position.
-     * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
-     * @param {number} value - Scroll top value.
+     * 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.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
     setScrollTop(value) {
         return TinyHtml.setScrollTop(this, value);
@@ -2397,26 +2779,17 @@ class TinyHtml {
      * Sets the horizontal scroll position.
      * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
      * @param {number} value - Scroll left value.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
     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 TinyHtml.scrollToXY(el, { targetX: value });
     }
     /**
      * Sets the horizontal scroll position.
      * @param {number} value - Scroll left value.
+     * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
      */
     setScrollLeft(value) {
         return TinyHtml.setScrollLeft(this, value);
@@ -2513,28 +2886,30 @@ class TinyHtml {
     /////////////////////////////////////////////
     /**
      * Adds one or more CSS class names to the element.
-     * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => void} - One or more class names to add.
+     * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to add.
      */
     static addClass(el, ...args) {
         TinyHtml._preElems(el, 'addClass').forEach((elem) => elem.classList.add(...args));
+        return el;
     }
     /**
      * Adds one or more CSS class names to the element.
-     * @type {(...tokens: string[]) => void} - One or more class names to add.
+     * @type {(...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to add.
      */
     addClass(...args) {
         return TinyHtml.addClass(this, ...args);
     }
     /**
      * Removes one or more CSS class names from the element.
-     * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => void} - One or more class names to remove.
+     * @type {(el: TinyElement|TinyElement[], ...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to remove.
      */
     static removeClass(el, ...args) {
         TinyHtml._preElems(el, 'removeClass').forEach((elem) => elem.classList.remove(...args));
+        return el;
     }
     /**
      * Removes one or more CSS class names from the element.
-     * @type {(...tokens: string[]) => void} - One or more class names to remove.
+     * @type {(...tokens: string[]) => (TinyElement|TinyElement[])} - One or more class names to remove.
      */
     removeClass(...args) {
         return TinyHtml.removeClass(this, ...args);
@@ -2724,15 +3099,18 @@ class TinyHtml {
      * Set text content of elements.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
     static setText(el, value) {
         if (typeof value !== 'string')
             throw new Error('Value is not a valid string.');
         TinyHtml._preElems(el, 'setText').forEach((el) => (el.textContent = value));
+        return el;
     }
     /**
      * Set text content of the element.
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
     setText(value) {
         return TinyHtml.setText(this, value);
@@ -2740,45 +3118,53 @@ class TinyHtml {
     /**
      * Remove all child nodes from each element.
      * @param {TinyElement|TinyElement[]} el
+     * @returns {TinyElement|TinyElement[]}
      */
     static empty(el) {
         TinyHtml._preElems(el, 'empty').forEach((el) => (el.textContent = ''));
+        return el;
     }
     /**
      * Remove all child nodes of the element.
+     * @returns {TinyElement|TinyElement[]}
      */
     empty() {
         return TinyHtml.empty(this);
     }
     /**
      * Get the innerHTML of the element.
-     * @param {TinyElement|TinyElement[]} el
+     * @param {TinyElement} el
+     * @param {GetHTMLOptions} [ops]
      * @returns {string}
      */
-    static html(el) {
+    static html(el, ops) {
         const elem = TinyHtml._preElem(el, 'html');
-        return elem.innerHTML;
+        return elem.getHTML(ops);
     }
     /**
      * Get the innerHTML of the element.
+     * @param {GetHTMLOptions} [ops]
      * @returns {string}
      */
-    html() {
-        return TinyHtml.html(this);
+    html(ops) {
+        return TinyHtml.html(this, ops);
     }
     /**
      * Set the innerHTML of each element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
     static setHtml(el, value) {
         if (typeof value !== 'string')
             throw new Error('Value is not a valid string.');
         TinyHtml._preElems(el, 'setHtml').forEach((el) => (el.innerHTML = value));
+        return el;
     }
     /**
      * Set the innerHTML of the element.
      * @param {string} value
+     * @returns {TinyElement|TinyElement[]}
      */
     setHtml(value) {
         return TinyHtml.setHtml(this, value);
@@ -2899,6 +3285,7 @@ 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, value) {
         TinyHtml._preInputElems(el, 'setVal').forEach((elem) => {
@@ -2937,12 +3324,14 @@ class TinyHtml {
                     elem.value = valToSet;
             }
         });
+        return el;
     }
     /**
      * 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) {
@@ -3199,6 +3588,7 @@ 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, event, handler, options) {
         if (typeof event !== 'string')
@@ -3214,6 +3604,7 @@ class TinyHtml {
                 events[event] = [];
             events[event].push({ handler, options });
         });
+        return el;
     }
     /**
      * Registers an event listener on the specified element.
@@ -3221,6 +3612,7 @@ 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, handler, options) {
         return TinyHtml.on(this, event, handler, options);
@@ -3232,6 +3624,7 @@ 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, event, handler, options = {}) {
         if (typeof event !== 'string')
@@ -3244,6 +3637,7 @@ class TinyHtml {
             };
             TinyHtml.on(elem, event, wrapped, typeof options === 'boolean' ? options : { ...options, once: true });
         });
+        return el;
     }
     /**
      * Registers an event listener that runs only once, then is removed.
@@ -3251,6 +3645,7 @@ 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[]}
      */
     once(event, handler, options = {}) {
         return TinyHtml.once(this, event, handler, options);
@@ -3262,6 +3657,7 @@ 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, event, handler, options) {
         if (typeof event !== 'string')
@@ -3275,6 +3671,7 @@ class TinyHtml {
                     delete events[event];
             }
         });
+        return el;
     }
     /**
      * Removes a specific event listener from an element.
@@ -3282,6 +3679,7 @@ 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[]}
      */
     off(event, handler, options) {
         return TinyHtml.off(this, event, handler, options);
@@ -3291,6 +3689,7 @@ class TinyHtml {
      *
      * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
      * @param {string} event - The event type to remove (e.g. 'click').
+     * @returns {TinyEventTarget|TinyEventTarget[]}
      */
     static offAll(el, event) {
         if (typeof event !== 'string')
@@ -3304,11 +3703,13 @@ class TinyHtml {
                 delete events[event];
             }
         });
+        return el;
     }
     /**
      * 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) {
         return TinyHtml.offAll(this, event);
@@ -3319,6 +3720,7 @@ class TinyHtml {
      * @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, filterFn = null) {
         if (filterFn !== null && typeof filterFn !== 'function')
@@ -3336,12 +3738,14 @@ class TinyHtml {
             }
             __eventRegistry.delete(elem);
         });
+        return el;
     }
     /**
      * 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 = null) {
         return TinyHtml.offAllTypes(this, filterFn);
@@ -3352,6 +3756,7 @@ class TinyHtml {
      * @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, event, payload = {}) {
         if (typeof event !== 'string')
@@ -3366,12 +3771,14 @@ class TinyHtml {
                 });
             elem.dispatchEvent(evt);
         });
+        return el;
     }
     /**
      * 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, payload = {}) {
         return TinyHtml.trigger(this, event, payload);
@@ -3410,6 +3817,7 @@ class TinyHtml {
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
      * @param {string|null} [value=null]
+     * @returns {TinyElement|TinyElement[]}
      */
     static setAttr(el, name, value = null) {
         if (typeof name !== 'string')
@@ -3422,11 +3830,13 @@ class TinyHtml {
             else
                 elem.setAttribute(name, value);
         });
+        return el;
     }
     /**
      * Set an attribute on an element.
      * @param {string} name
      * @param {string|null} [value=null]
+     * @returns {TinyElement|TinyElement[]}
      */
     setAttr(name, value) {
         return TinyHtml.setAttr(this, name, value);
@@ -3435,15 +3845,18 @@ class TinyHtml {
      * Remove attribute(s) from an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name Space-separated list of attributes.
+     * @returns {TinyElement|TinyElement[]}
      */
     static removeAttr(el, name) {
         if (typeof name !== 'string')
             throw new TypeError('The "name" must be a string.');
         TinyHtml._preElems(el, 'removeAttr').forEach((elem) => elem.removeAttribute(name));
+        return el;
     }
     /**
      * Remove attribute(s) from an element.
      * @param {string} name Space-separated list of attributes.
+     * @returns {TinyElement|TinyElement[]}
      */
     removeAttr(name) {
         return TinyHtml.removeAttr(this, name);
@@ -3495,6 +3908,7 @@ class TinyHtml {
      * Set a property on an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
     static addProp(el, name) {
         if (typeof name !== 'string')
@@ -3505,10 +3919,12 @@ class TinyHtml {
             // @ts-ignore
             elem[name] = true;
         });
+        return el;
     }
     /**
      * Set a property on an element.
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
     addProp(name) {
         return TinyHtml.addProp(this, name);
@@ -3517,6 +3933,7 @@ class TinyHtml {
      * Remove a property from an element.
      * @param {TinyElement|TinyElement[]} el
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
     static removeProp(el, name) {
         if (typeof name !== 'string')
@@ -3527,10 +3944,12 @@ class TinyHtml {
             // @ts-ignore
             elem[name] = false;
         });
+        return el;
     }
     /**
      * Remove a property from an element.
      * @param {string} name
+     * @returns {TinyElement|TinyElement[]}
      */
     removeProp(name) {
         return TinyHtml.removeProp(this, name);
@@ -3570,12 +3989,15 @@ 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) {
         TinyHtml._preElems(el, 'remove').forEach((elem) => elem.remove());
+        return el;
     }
     /**
      * Removes the element from the DOM.
+     * @returns {TinyElement|TinyElement[]}
      */
     remove() {
         return TinyHtml.remove(this);
@@ -3886,6 +4308,12 @@ class TinyHtml {
      */
     static isInViewport(el) {
         const elem = TinyHtml._preElem(el, 'isInViewport');
+        if (!elem.checkVisibility({
+            contentVisibilityAuto: false,
+            opacityProperty: false,
+            visibilityProperty: false,
+        }))
+            return false;
         const elementTop = TinyHtml.offset(elem).top;
         const elementBottom = elementTop + TinyHtml.outerHeight(elem);
         const viewportTop = TinyHtml.scrollTop(window);
@@ -3908,6 +4336,12 @@ class TinyHtml {
      */
     static isScrolledIntoView(el) {
         const elem = TinyHtml._preElem(el, 'isScrolledIntoView');
+        if (!elem.checkVisibility({
+            contentVisibilityAuto: false,
+            opacityProperty: false,
+            visibilityProperty: false,
+        }))
+            return false;
         const docViewTop = TinyHtml.scrollTop(window);
         const docViewBottom = docViewTop + TinyHtml.height(window);
         const elemTop = TinyHtml.offset(elem).top;
@@ -3922,5 +4356,90 @@ class TinyHtml {
     isScrolledIntoView() {
         return TinyHtml.isScrolledIntoView(this);
     }
+    /**
+     * 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, cont) {
+        const elem = TinyHtml._preElem(el, 'isInContainer');
+        const container = TinyHtml._preElem(cont, 'isInContainer');
+        if (!elem.checkVisibility({
+            contentVisibilityAuto: false,
+            opacityProperty: false,
+            visibilityProperty: false,
+        }))
+            return false;
+        const elemRect = elem.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        const verticallyVisible = elemRect.bottom > containerRect.top && elemRect.top < containerRect.bottom;
+        const horizontallyVisible = elemRect.right > containerRect.left && elemRect.left < containerRect.right;
+        return verticallyVisible && horizontallyVisible;
+    }
+    /**
+     * 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) {
+        return TinyHtml.isInContainer(this, cont);
+    }
+    /**
+     * 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, cont) {
+        const elem = TinyHtml._preElem(el, 'isScrolledIntoView');
+        const container = TinyHtml._preElem(cont, 'isInContainer');
+        if (!elem.checkVisibility({
+            contentVisibilityAuto: false,
+            opacityProperty: false,
+            visibilityProperty: false,
+        }))
+            return false;
+        const elemRect = elem.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        const isFullyVisible = elemRect.top >= containerRect.top &&
+            elemRect.bottom <= containerRect.bottom &&
+            elemRect.left >= containerRect.left &&
+            elemRect.right <= containerRect.right;
+        return isFullyVisible;
+    }
+    /**
+     * 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) {
+        return TinyHtml.isFullyInContainer(this, cont);
+    }
+    /**
+     * 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) {
+        const elem = TinyHtml._preElem(el, 'hasScroll');
+        return {
+            v: elem.scrollHeight > elem.clientHeight,
+            h: elem.scrollWidth > elem.clientWidth,
+        };
+    }
+    /**
+     * Checks if an element has scrollable content.
+     *
+     * @returns {{ v: boolean, h: boolean }} - True if scroll is needed in that direction.
+     */
+    hasScroll() {
+        return TinyHtml.hasScroll(this);
+    }
 }
 export default TinyHtml;