tiny-essentials 1.21.10 → 1.22.1

package/docs/v1/libs/TinyHtml.md

@@ -16,6 +16,55 @@ TinyHtml.createElement('div')
 
 This design keeps your code concise while maintaining clarity and control over the DOM structure.
 
+## 📑 Table of Contents
+
+- [🧩 Type Definitions – Core Building Blocks](#-type-definitions--core-building-blocks)
+- [🔨 Element Creation](#-element-creation)
+- [🔎 Static DOM Selectors](#-static-dom-selectors)
+- [🔍 Element Observer](#-element-observer)
+- [📑 HTML Parser](#-html-parser)
+- [🧩 Internal Element Access](#-internal-element-access)
+- [🛠️ Static Pre-Validation Utilities](#-static-pre-validation-utilities)
+- [🔁 Conversion Helpers](#-conversion-helpers)
+- [🧹 Element Filtering & Matching](#-element-filtering--matching)
+- [💾 Element Data Store](#-element-data-store)
+- [🔄 DOM Traversal Methods](#-dom-traversal-methods)
+- [🧱 DOM Manipulation](#-dom-manipulation)
+- [🧮 Easing Functions](#-easing-functions)
+- [🧭 Smooth Scrolling](#-smooth-scrolling)
+- [⚙️ Internal Scroll Mechanism](#-internal-scroll-mechanism)
+- [📏 Dimensions (Size API)](#-dimensions-size-api)
+- [📌 Position, Scroll & Box Spacing](#-position-scroll--box-spacing)
+- [🎨 Class Manipulation](#-class-manipulation)
+- [📄 Content & Element Info](#-content--element-info)
+- [🎛️ Form Value Handling & Input Hooks](#-form-value-handling--input-hooks)
+- [🎉 Event Handling](#-event-handling)
+- [🧬 Attribute & Property Manipulation](#-attribute--property-manipulation)
+- [🛠️ Element Utilities](#-element-utilities)
+- [📦 Collision Detection](#-collision-detection)
+- [🔐 Collision Locking System](#-collision-locking-system)
+- [🧼 Collision Lock Reset](#-collision-lock-reset)
+- [👁️ Viewport Detection](#-viewport-detection)
+- [🧠 Property Name Normalization](#-property-name-normalization)
+- [🔁 Attribute ↔ Property Mapping](#-attribute--property-mapping)
+- [🎨 CSS Property Aliases (`cssPropAliases`)](#-css-property-aliases-csspropaliases)
+- [✂️ Utility Functions](#-utility-functions)
+- [🧩 Style Methods](#-style-methods)
+- [🧪 Reading Computed Styles](#-reading-computed-styles)
+- [🎬 Animate Stuff](#-animate-stuff)
+  - [🎬 Animate DOM (Data)](#-animate-dom-data)
+  - [⏹ Animate DOM (cancelOldStyleFx)](#-animate-dom-canceloldstylefx)
+  - [⏱ Animate DOM (styleFxSpeeds)](#-animate-dom-stylefxspeeds)
+  - [🎨 Animate DOM (styleEffects)](#-animate-dom-styleeffects)
+  - [🔄 Animate DOM (styleEffectInverse)](#-animate-dom-styleeffectinverse)
+  - [🔁 Animate DOM (styleEffectsRd)](#-animate-dom-styleeffectsrd)
+  - [🧩 Animate DOM (styleEffectsProps)](#-animate-dom-styleeffectsprops)
+- [🎨 Style FX Manager](#-style-fx-manager)
+- [✨ Animate FXs](#-animate-fxs)
+- [🖱️ Focus & Blur](#-focus--blur)
+- [🌐 Window Scroll & Viewport Helpers](#-window-scroll--viewport-helpers)
+
+---
 
 ## 🧩 Type Definitions – Core Building Blocks
 
@@ -310,6 +359,172 @@ HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement
 
 ---
 
+### 💾 Internal Animation Storage
+
+```ts
+/**
+ * Internal storage for animation-related data, associated with elements.
+ * Used to remember original dimensions (height/width) and other properties
+ * so that animations like `slideUp` and `slideDown` can restore or continue
+ * smoothly, mimicking jQuery's behavior.
+ *
+ * Each element is mapped to a plain object with keys such as `origHeight`,
+ * `origWidth`, etc.
+ *
+ * @type {WeakMap<HTMLElement, Record<string, string|number>>}
+ */
+const __elementAnimateData = new WeakMap();
+```
+
+* **Purpose:** Tracks original dimensions and properties of elements for smooth animations.
+* **Type:** `WeakMap<HTMLElement, Record<string, string | number>>`
+* **Notes:** Uses a `WeakMap` so that memory is automatically freed when elements are removed from the DOM.
+
+---
+
+### 🎬 Active Animation Tracking
+
+```ts
+/**
+ * Stores the currently active animation for each element,
+ * allowing cancellation or replacement of ongoing animations.
+ *
+ * @type {WeakMap<HTMLElement, { animation: Animation, id: string }>}
+ */
+const __elementCurrentAnimation = new WeakMap();
+```
+
+* **Purpose:** Keeps track of the active animation per element.
+* **Type:** `WeakMap<HTMLElement, { animation: Animation, id: string }>`
+* **Notes:** Useful for stopping or replacing animations mid-flight.
+
+---
+
+### ✨ Style Effects Definitions
+
+```ts
+/**
+ * Mapping of animation shortcuts to their effect definitions.
+ * Similar to jQuery's predefined effects (slideDown, fadeIn, etc.).
+ *
+ * @typedef {Record<string, string|(string|number)[]>} StyleEffects
+ */
+```
+
+* **Purpose:** Defines reusable animation shortcuts.
+* **Example:** `"fadeIn": ["opacity", 0, 1]`
+
+---
+
+### 🖱️ Hover Event Callback
+
+```ts
+/**
+ * Callback function used for hover events.
+ * @callback HoverEventCallback
+ * @param {MouseEvent} ev - The mouse event triggered on enter or leave.
+ * @returns {void} Returns nothing.
+ */
+```
+
+* **Purpose:** Defines the expected signature for hover event callbacks.
+* **Parameters:** `MouseEvent ev`
+* **Returns:** `void`
+
+---
+
+### 🏃 Active Style Animation Collection
+
+```ts
+/**
+ * Represents a collection of active style-based animations.
+ *
+ * Each HTMLElement is associated with an array of its currently running
+ * `Animation` objects (from the Web Animations API).
+ *
+ * @typedef {Map<HTMLElement, Animation|null>} StyleFxResult
+ */
+```
+
+* **Purpose:** Tracks currently running Web Animations per element.
+* **Type:** `Map<HTMLElement, Animation|null>`
+
+---
+
+### 📊 Animation Keyframe Data
+
+```ts
+/**
+ * Represents a collection of animation keyframe data mapped by CSS property.
+ *
+ * - The **key** is the CSS property name (e.g. `"height"`, `"opacity"`).
+ * - The **value** is an array of values representing the start and end
+ *   states of the property during the animation.
+ *
+ * @typedef {Record<string, (string|number)[]>} AnimationSfxData
+ */
+```
+
+* **Purpose:** Stores start and end states of CSS properties for animations.
+* **Type:** `Record<string, (string|number)[]>`
+
+---
+
+### 🔁 Style Effects Repeat Detector
+
+```ts
+/**
+ * Function signature for style effects repeat detectors.
+ *
+ * @typedef {(effects: AnimationSfxData) => boolean} StyleEffectsRdFn
+ */
+```
+
+* **Purpose:** Determines if a style effect should repeat.
+* **Type:** `(effects: AnimationSfxData) => boolean`
+
+---
+
+### ⚡ Style Effect Property Handler
+
+```ts
+/**
+ * Function signature for style effect property handlers.
+ *
+ * @typedef {(
+ *   el: HTMLElement,
+ *   keyframes: AnimationSfxData,
+ *   prop: string,
+ *   style: CSSStyleDeclaration
+ * ) => void} StyleEffectsFn
+ */
+```
+
+* **Purpose:** Handles applying keyframe data to a specific CSS property on an element.
+* **Parameters:**
+
+  * `el: HTMLElement` – target element
+  * `keyframes: AnimationSfxData` – property keyframes
+  * `prop: string` – CSS property
+  * `style: CSSStyleDeclaration` – inline style object
+
+---
+
+### 🛠️ Style Effect Property Handlers Collection
+
+```ts
+/**
+ * A collection of style effect property handlers.
+ *
+ * @typedef {Record<string, StyleEffectsFn>} StyleEffectsProps
+ */
+```
+
+* **Purpose:** Groups multiple property handlers for different CSS properties.
+* **Type:** `Record<string, StyleEffectsFn>`
+
+---
+
 ## 🔨 Element Creation
 
 ### `TinyHtml.createFrom(tagName, attrs?)`
@@ -445,6 +660,107 @@ Finds elements by tag name in a namespace (defaults to XHTML).
 
 ---
 
+## 🔍 Element Observer
+
+### ⚡ `autoStartElemObserver`
+
+A **flag** that determines whether the internal element observer should automatically start when some library code initializes.
+
+* **Type** 🔘 — `boolean`
+* **Default** 🏁 — `true`
+
+#### 📥 Getter
+
+```js
+TinyHtml.autoStartElemObserver; // returns true or false
+```
+
+Returns the current state of the auto-start flag.
+
+#### 📤 Setter
+
+```js
+TinyHtml.autoStartElemObserver = false;
+```
+
+Updates the flag.
+⚠️ Throws a `TypeError` if the value is not a boolean.
+
+---
+
+### 👀 `tinyObserver`
+
+The internal **[`TinyElementObserver`](./TinyElementObserver.md)** instance used by TinyHtml to track DOM changes.
+It is configured to observe the **document root element** (`document.documentElement`) and comes with **built-in detectors** for **style** and **class** attribute changes.
+
+* **Type** 📦 — `TinyElementObserver`
+
+#### 🔧 Configuration
+
+* **Target element**: `document.documentElement` (if available).
+* **Detectors**:
+
+  * 🎨 **Style Detector (`tinyStyleEvent`)**
+    Detects changes to inline styles (`style` attribute).
+
+    * Compares old vs new styles using `diffStrings`.
+    * Dispatches:
+
+      ```js
+      new CustomEvent('tinyhtml.stylechanged', { detail: changes })
+      ```
+  * 🏷️ **Class Detector (`tinyClassEvent`)**
+    Detects changes to the `class` attribute.
+
+    * Compares old vs new classes using `diffArrayList`.
+    * Dispatches:
+
+      ```js
+      new CustomEvent('tinyhtml.classchanged', { detail: changes })
+      ```
+* **Observer config** ⚙️:
+
+  ```js
+  {
+    attributeOldValue: true,
+    attributes: true,
+    subtree: true,
+    attributeFilter: ['style', 'class']
+  }
+  ```
+
+#### 📥 Getter
+
+```js
+const observer = TinyHtml.tinyObserver;
+```
+
+Retrieves the internal `TinyElementObserver` instance.
+
+---
+
+### ✨ Example Usage
+
+```js
+// Listen for style changes on any element in the document
+document.addEventListener('tinyhtml.stylechanged', (e) => {
+  console.log('🎨 Style changed:', e.detail);
+});
+
+// Listen for class changes
+document.addEventListener('tinyhtml.classchanged', (e) => {
+  console.log('🏷️ Class changed:', e.detail);
+});
+
+// Disable auto-start (if needed)
+TinyHtml.autoStartElemObserver = false;
+
+// Manually start the observer
+TinyHtml.tinyObserver.start();
+```
+
+---
+
 ## 📑 HTML Parser
 
 ### Type Definition
@@ -1144,9 +1460,6 @@ This API set focuses on **measuring element offsets**, **scroll positions**, and
 
 ### 📍 Element Positioning
 
-#### `.animate(keyframes, ops?)` / `TinyHtml.animate(el, keyframes, ops?)`
-Applies an animation to one or more TinyElement instances using the Web Animations API.
-
 #### `.offset()` / `TinyHtml.offset(el)`
 Returns the coordinates `{ top, left }` of the element **relative to the document**.
 
@@ -1669,6 +1982,34 @@ TinyHtml.hasExactEventListener(el, "click", onClick);
 
 ---
 
+### 🐭 `hover()`
+
+Hover Event Shortcut
+
+```js
+element.hover(
+  (e) => console.log("Mouse entered!"),
+  (e) => console.log("Mouse left!")
+);
+```
+
+* `hover(fnOver, fnOut)`: Attaches a pair of event listeners for `mouseenter` and `mouseleave`.
+
+  * `fnOver`: Runs when the mouse enters the element.
+  * `fnOut`: Runs when the mouse leaves. If omitted, `fnOver` is used for both.
+  * `options`: Optional event listener options.
+
+You can also use the static version:
+
+```js
+TinyHtml.hover([el1, el2], 
+  () => console.log("Hovered in!"), 
+  () => console.log("Hovered out!")
+);
+```
+
+---
+
 ### 📥 `on()` / `once()`
 
 Registering Events
@@ -2275,6 +2616,22 @@ TinyHtml provides multiple utilities for reading CSS styles from elements, both
 
 ---
 
+### 🎨 `static parseStyle(styleText)`
+
+Parses an inline CSS style string into an **object** representation.
+
+* **`styleText`** 📝 — CSS inline style string (e.g., `"color: red; font-size: 12px;"`).
+* **Returns** 📦 — An object mapping CSS properties to their values.
+
+**Example:**
+
+```js
+parseStyle('color: red; font-size: 12px;');
+// ➡ { color: 'red', 'font-size': '12px' }
+```
+
+---
+
 ### 🧬 `TinyHtml.css(el)` / `el.css()`
 
 Returns the full computed style object for a given element.
@@ -2347,6 +2704,443 @@ myTinyElem.cssFloats(['paddingTop', 'paddingBottom']);
 
 ---
 
+## 🎬 Animate DOM (Data)
+
+### `getAnimateData(el, where)`  
+🔍 Retrieves stored animation data for a given element and key.  
+If no data exists yet, it initializes storage for that element.  
+
+- **Parameters**:  
+  - `el` 👉 `HTMLElement` — The element whose data should be retrieved.  
+  - `where` 👉 `string` — The key to read (e.g., `"origHeight"`).  
+- **Returns**: `string | number | undefined` — The stored value, or `undefined`.  
+
+---
+
+### `setAnimateData(el, where, value)`  
+💾 Stores animation data for a given element and key.  
+Used to cache original size/values for animations.  
+
+- **Parameters**:  
+  - `el` 👉 `HTMLElement` — The element whose data should be set.  
+  - `where` 👉 `string` — The key to store under (e.g., `"origHeight"`).  
+  - `value` 👉 `string | number` — The value to store.  
+- **Throws**: `TypeError` if the arguments are invalid.  
+
+---
+
+## ⏹ Animate DOM (cancelOldStyleFx)
+
+### `#cancelOldStyleFx`  
+⚙️ Global configuration flag controlling whether old style-based animations  
+are cancelled before a new one starts. Defaults to **true**.  
+
+- **Type**: `boolean`  
+
+---
+
+### `cancelOldStyleFx` (getter / setter)  
+🛠 Controls whether old animations are automatically cancelled before new ones begin.  
+
+- **Getter**: Returns a `boolean`.  
+- **Setter**: Accepts a `boolean`. Throws `TypeError` otherwise.  
+
+---
+
+## ⏱ Animate DOM (styleFxSpeeds)
+
+### `#styleFxSpeeds`  
+⚡ Predefined animation speed options, inspired by `jQuery.fx.speeds`.  
+
+- **Example**:  
+```js
+  TinyHtml.animate(el, keyframes, 'fast');
+  TinyHtml.slideDown(el, 'slow');
+```
+
+* **Type**: `Record<string, number | KeyframeAnimationOptions>`
+
+---
+
+### `styleFxSpeeds` (getter / setter)
+
+🔄 Access or replace the full speed definitions.
+
+* **Getter**: Returns a cloned copy of speeds.
+* **Setter**: Accepts a valid object. Throws `TypeError` otherwise.
+
+---
+
+### `getStyleFxSpeed(name)`
+
+📥 Get a predefined speed by name.
+
+* **Parameters**:
+
+  * `name` 👉 `string` — The name of the speed entry.
+* **Returns**: `number | KeyframeAnimationOptions | undefined`
+
+---
+
+### `setStyleFxSpeed(name, value)`
+
+📤 Add or overwrite a speed entry.
+
+* **Parameters**:
+
+  * `name` 👉 `string`
+  * `value` 👉 `number | KeyframeAnimationOptions`
+
+---
+
+### `deleteStyleFxSpeed(name)`
+
+🗑 Delete a predefined speed by name.
+
+* **Returns**: `boolean`
+
+---
+
+### `hasStyleFxSpeed(name)`
+
+❓ Check if a predefined speed exists.
+
+* **Returns**: `boolean`
+
+---
+
+## 🎨 Animate DOM (styleEffects)
+
+### `#styleEffects`
+
+🎭 Predefined style-based animation effects.
+
+* **Default values**:
+
+  * `slideDown`
+  * `slideUp`
+  * `fadeIn`
+  * `fadeOut`
+
+---
+
+### `styleEffects` (getter / setter)
+
+📦 Manage the collection of style effects.
+
+* **Getter**: Returns a deep-cloned copy.
+* **Setter**: Replaces all effects with validation.
+
+---
+
+### `getStyleEffect(name)`
+
+📥 Retrieve a style effect by name.
+
+* **Returns**: `StyleEffects | undefined`
+
+---
+
+### `setStyleEffect(name, value)`
+
+📝 Register or overwrite a style effect.
+
+* **Throws**: `TypeError` if invalid.
+
+---
+
+### `deleteStyleEffect(name)`
+
+🗑 Delete a style effect by name.
+
+* **Returns**: `boolean`
+
+---
+
+### `hasStyleEffect(name)`
+
+❓ Check if a style effect exists.
+
+* **Returns**: `boolean`
+
+---
+
+## 🔄 Animate DOM (styleEffectInverse)
+
+### `#styleEffectInverse`
+
+↔️ Maps effects to their inverse.
+
+* **Default values**:
+
+  * `slideDown ↔ slideUp`
+  * `fadeIn ↔ fadeOut`
+
+---
+
+### `styleEffectInverse` (getter / setter)
+
+🔀 Manage inverse mappings.
+
+* **Getter**: Returns a cloned copy.
+* **Setter**: Replaces all inverse mappings.
+
+---
+
+### `getStyleEffectInverse(name)`
+
+📥 Retrieve inverse effect by name.
+
+* **Returns**: `string | null`
+
+---
+
+### `setStyleEffectInverse(name, value)`
+
+📝 Register or overwrite inverse mapping.
+
+---
+
+### `deleteStyleEffectInverse(name)`
+
+🗑 Delete an inverse mapping.
+
+* **Returns**: `boolean`
+
+---
+
+### `hasStyleEffectInverse(name)`
+
+❓ Check if an inverse mapping exists.
+
+* **Returns**: `boolean`
+
+---
+
+## 🔁 Animate DOM (styleEffectsRd)
+
+### `#styleEffectsRd`
+
+🔎 Repeat detector functions.
+Used to check if animations would produce no visible change.
+
+---
+
+### `styleEffectsRd` (getter / setter)
+
+⚙️ Manage repeat detectors.
+
+---
+
+### `getStyleEffectRd(name)`
+
+📥 Retrieve a repeat detector.
+
+* **Returns**: `StyleEffectsRdFn | null`
+
+---
+
+### `setStyleEffectRd(name, fn)`
+
+📝 Register or overwrite a repeat detector.
+
+---
+
+### `deleteStyleEffectRd(name)`
+
+🗑 Delete a repeat detector by name.
+
+---
+
+### `hasStyleEffectRd(name)`
+
+❓ Check if a repeat detector exists.
+
+* **Returns**: `boolean`
+
+---
+
+## 🧩 Animate DOM (styleEffectsProps)
+
+### `#styleEffectsProps`
+
+🛠 Effect property handlers for **show** and **hide**.
+Each function generates appropriate keyframes depending on the property.
+
+* **Supported props**:
+
+  * `height` / `width`
+  * `margin*` / `padding*`
+  * `opacity`
+  * Any other style property
+
+* **Type**: `StyleEffectsProps`
+
+---
+
+### `static get styleEffectsProps(): StyleEffectsProps`
+
+Returns a shallow-cloned copy of the property effect handlers.
+
+---
+
+### `static set styleEffectsProps(value: StyleEffectsProps): void`
+
+Replace the entire styleEffectsProps map with a new one.
+Throws a `TypeError` if `value` is not a plain object or if any property is not a function.
+
+---
+
+### `static getStyleEffectProp(name: string): StyleEffectsFn | null`
+
+Get a style effect property handler by name.
+Returns the handler function or `null` if not found.
+
+---
+
+### `static setStyleEffectProp(name: string, fn: StyleEffectsFn): void`
+
+Register or overwrite a style effect property handler.
+Throws a `TypeError` if `name` is not a string or `fn` is not a function.
+
+---
+
+### `static deleteStyleEffectProp(name: string): boolean`
+
+Delete a style effect property handler by name.
+Returns `true` if deleted, `false` otherwise.
+
+---
+
+### `static hasStyleEffectProp(name: string): boolean`
+
+Check if a style effect property handler exists.
+
+---
+
+## 🎨 Style FX Manager
+
+### `static genStyleFx(type: string, includeWidth = false): Record<string, string>`
+
+Generates effect parameters to create standard animations.
+
+* `type`: Effect type (e.g. `"show"`, `"hide"`).
+* `includeWidth`: Whether to also include `width` and `opacity`.
+
+---
+
+### `static applyStyleFx(el, id, props, ops?): StyleFxResult`
+
+Applies style-based effects (slide, fade) to one or more elements.
+Converts abstract effect definitions (e.g. `{ height: "show" }`) into Web Animations API keyframes.
+
+---
+
+### `applyStyleFx(id, props, ops?): StyleFxResult`
+
+Instance method version of `applyStyleFx`.
+
+---
+
+## 🎬 Animate Stuff
+
+### `static getCurrentAnimationId(el: HTMLElement): string | null | undefined`
+
+Get the current animation entry for a given element.
+Returns the animation `id`, `null`, or `undefined`.
+
+---
+
+### `static animate(el, keyframes, ops?, id?, cancelOldAnim?): Animation[]`
+
+Applies an animation to one or multiple elements.
+Optionally cancels any currently running animation on the same element.
+
+---
+
+### `animate(keyframes, ops?, id?, cancelOldAnim?): Animation[]`
+
+Instance method version of `animate`.
+
+---
+
+### `static stop(el): boolean[]`
+
+Stops the current animation(s) on one or multiple elements.
+Returns an array of booleans indicating success per element.
+
+---
+
+### `stop(): boolean[]`
+
+Instance method version of `stop`.
+
+---
+
+## ✨ Animate FXs
+
+### `static slideDown(el, ops?): StyleFxResult`
+
+Show animation (`slideDown`).
+
+### `slideDown(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
+### `static slideUp(el, ops?): StyleFxResult`
+
+Hide animation (`slideUp`).
+
+### `slideUp(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
+### `static slideToggle(el, ops?): StyleFxResult`
+
+Toggle slide animation.
+Determines visibility and plays `slideDown` or `slideUp`.
+
+### `slideToggle(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
+### `static fadeIn(el, ops?): StyleFxResult`
+
+Fade in animation.
+
+### `fadeIn(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
+### `static fadeOut(el, ops?): StyleFxResult`
+
+Fade out animation.
+
+### `fadeOut(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
+### `static fadeToggle(el, ops?): StyleFxResult`
+
+Toggle fade animation.
+Determines visibility and plays `fadeIn` or `fadeOut`.
+
+### `fadeToggle(ops?): StyleFxResult`
+
+Instance method version.
+
+---
+
 ## 🖱️ Focus & Blur
 
 TinyHtml provides utility methods to programmatically focus or blur HTML elements.