tiny-essentials 1.16.2 → 1.17.1

package/dist/v1/TinyHtml.js

@@ -470,6 +470,19 @@ const {
   areElsCollRight: TinyHtml_areElsCollRight,
 } = collision_namespaceObject;
 
+/**
+ * Callback invoked on each animation frame with the current scroll position,
+ * normalized animation time (`0` to `1`), and a completion flag.
+ *
+ * @typedef {(progress: { x: number, y: number, isComplete: boolean, time: number }) => void} OnScrollAnimation
+ */
+
+/**
+ * A list of supported easing function names for smooth animations.
+ *
+ * @typedef {'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic'} Easings
+ */
+
 /**
  * Represents a raw Node element or an instance of TinyHtml.
  * This type is used to abstract interactions with both plain elements
@@ -525,6 +538,21 @@ const {
  * @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:
@@ -541,7 +569,7 @@ const {
  * 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
  */
 
 /**
@@ -662,40 +690,114 @@ class TinyHtml {
 
   static Utils = { ...collision_namespaceObject };
 
+  /**
+   * 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);
-    if (!newEl) throw new Error(`[TinyHtml] query(): No element found for selector "${selector}".`);
+  static query(selector, elem = document) {
+    const newEl = elem.querySelector(selector);
+    if (!newEl) 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}".`);
+    if (!newEl) return null;
     return new TinyHtml(newEl);
   }
 
@@ -703,13 +805,24 @@ class TinyHtml {
    * 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.
    *
@@ -727,13 +840,30 @@ 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'),
+    );
+  }
+
   //////////////////////////////////////////////////////////////////
 
   /**
@@ -1014,6 +1144,45 @@ class TinyHtml {
     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.
@@ -1360,12 +1529,13 @@ 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;
   }
 
   /**
@@ -1374,7 +1544,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);
@@ -1721,18 +1891,21 @@ 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);
@@ -1741,18 +1914,21 @@ 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);
@@ -1761,18 +1937,21 @@ 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);
@@ -1781,18 +1960,21 @@ 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);
@@ -1801,18 +1983,21 @@ 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);
@@ -1823,6 +2008,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');
@@ -1832,12 +2018,14 @@ class TinyHtml {
         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);
@@ -1848,6 +2036,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');
@@ -1858,12 +2047,14 @@ 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);
@@ -1875,6 +2066,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');
@@ -1882,6 +2074,7 @@ class TinyHtml {
     const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
     if (!targ.parentNode) throw new Error('');
     targ.parentNode.insertBefore(elem, childNode || targ);
+    return el;
   }
 
   /**
@@ -1889,6 +2082,7 @@ class TinyHtml {
    *
    * @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);
@@ -1900,6 +2094,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');
@@ -1907,6 +2102,7 @@ class TinyHtml {
     const childNode = TinyHtml._preNodeElemWithNull(child, 'insertBefore');
     if (!targ.parentNode) throw new Error('');
     targ.parentNode.insertBefore(elem, childNode || targ.nextSibling);
+    return el;
   }
 
   /**
@@ -1914,6 +2110,7 @@ class TinyHtml {
    *
    * @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);
@@ -1925,6 +2122,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');
@@ -1936,6 +2134,7 @@ class TinyHtml {
           parent.replaceChild(i === tars.length - 1 ? elem : elem.cloneNode(true), target);
       });
     });
+    return el;
   }
 
   /**
@@ -1943,6 +2142,7 @@ class TinyHtml {
    * 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);
@@ -1966,7 +2166,12 @@ class 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;
   }
@@ -2416,6 +2621,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) => {
@@ -2428,6 +2634,7 @@ class TinyHtml {
         }
       } else elem.style.setProperty(TinyHtml.toStyleKc(prop), value);
     });
+    return el;
   }
 
   /**
@@ -2438,6 +2645,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);
@@ -2533,6 +2741,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) => {
@@ -2542,12 +2751,14 @@ 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);
@@ -2562,6 +2773,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) => {
@@ -2569,6 +2781,7 @@ class TinyHtml {
       const newVal = current === TinyHtml.toStyleKc(val1) ? val2 : val1;
       TinyHtml.setStyle(elem, prop, newVal);
     });
+    return el;
   }
 
   /**
@@ -2579,6 +2792,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);
@@ -2588,14 +2802,16 @@ 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);
@@ -2607,14 +2823,17 @@ 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);
@@ -2624,19 +2843,46 @@ 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;
+    }
+  }
+
   //////////////////////////////////////////////////////////////////////
 
   /**
@@ -2645,7 +2891,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);
   }
 
   /**
@@ -2654,7 +2900,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);
   }
 
   /**
@@ -2689,16 +2935,40 @@ class TinyHtml {
     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') throw new TypeError('The extra must be a string.');
 
@@ -2786,17 +3056,20 @@ 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);
@@ -2807,17 +3080,20 @@ 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);
@@ -2825,11 +3101,11 @@ class TinyHtml {
 
   /**
    * 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');
   }
 
@@ -2843,11 +3119,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');
   }
 
@@ -2861,11 +3137,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');
   }
 
@@ -2879,11 +3155,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');
   }
 
@@ -2897,14 +3173,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');
   }
 
@@ -2919,14 +3195,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');
   }
 
@@ -2941,6 +3217,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.
@@ -3096,27 +3396,151 @@ class TinyHtml {
   }
 
   /**
-   * 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);
@@ -3126,24 +3550,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);
@@ -3274,15 +3691,16 @@ 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);
@@ -3290,15 +3708,16 @@ class TinyHtml {
 
   /**
    * 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);
@@ -3508,15 +3927,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);
@@ -3525,13 +3947,16 @@ 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);
@@ -3539,35 +3964,40 @@ class TinyHtml {
 
   /**
    * 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);
@@ -3701,6 +4131,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) => {
@@ -3740,6 +4171,7 @@ class TinyHtml {
         if (typeof valToSet === 'string') elem.value = valToSet;
       }
     });
+    return el;
   }
 
   /**
@@ -3747,6 +4179,7 @@ class TinyHtml {
    * 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) {
@@ -4016,6 +4449,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') throw new TypeError('The event name must be a string.');
@@ -4028,6 +4462,7 @@ class TinyHtml {
       if (!Array.isArray(events[event])) events[event] = [];
       events[event].push({ handler, options });
     });
+    return el;
   }
 
   /**
@@ -4036,6 +4471,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);
@@ -4048,6 +4484,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') throw new TypeError('The event name must be a string.');
@@ -4065,6 +4502,7 @@ class TinyHtml {
         typeof options === 'boolean' ? options : { ...options, once: true },
       );
     });
+    return el;
   }
 
   /**
@@ -4073,6 +4511,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);
@@ -4085,6 +4524,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') throw new TypeError('The event name must be a string.');
@@ -4097,6 +4537,7 @@ class TinyHtml {
         if (events[event].length === 0) delete events[event];
       }
     });
+    return el;
   }
 
   /**
@@ -4105,6 +4546,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);
@@ -4115,6 +4557,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') throw new TypeError('The event name must be a string.');
@@ -4127,12 +4570,14 @@ 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);
@@ -4144,6 +4589,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')
@@ -4162,6 +4608,7 @@ class TinyHtml {
 
       __eventRegistry.delete(elem);
     });
+    return el;
   }
 
   /**
@@ -4169,6 +4616,7 @@ class TinyHtml {
    *
    * @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);
@@ -4180,6 +4628,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') throw new TypeError('The event name must be a string.');
@@ -4195,6 +4644,7 @@ class TinyHtml {
 
       elem.dispatchEvent(evt);
     });
+    return el;
   }
 
   /**
@@ -4202,6 +4652,7 @@ class TinyHtml {
    *
    * @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);
@@ -4244,6 +4695,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') throw new TypeError('The "name" must be a string.');
@@ -4253,12 +4705,14 @@ class TinyHtml {
       if (value === null) elem.removeAttribute(name);
       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);
@@ -4268,15 +4722,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);
@@ -4331,6 +4788,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') throw new TypeError('The "name" must be a string.');
@@ -4340,11 +4798,13 @@ 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);
@@ -4354,6 +4814,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') throw new TypeError('The "name" must be a string.');
@@ -4363,11 +4824,13 @@ 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);
@@ -4408,13 +4871,16 @@ 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);
@@ -4758,6 +5224,14 @@ 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);
 
@@ -4784,6 +5258,14 @@ 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);
 
@@ -4801,6 +5283,111 @@ 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);
+  }
 }
 
 /* harmony default export */ const libs_TinyHtml = (TinyHtml);