# ๐ TinyHtml Class
`TinyHtml` is a lightweight utility class that provides DOM element manipulation and querying utilities, inspired by jQuery โ but built with modern native browser APIs.
It supports both static and instance-level operations, making it easy to work with elementsโ dimensions, collisions, and more in a readable and performant way.
Most instance methods that do not return a specific value are designed to return the `TinyHtml` instance itself, enabling **method chaining**.
This allows you to write fluent and expressive code like:
```js
TinyHtml.createElement('div')
.addClass('box')
.setAttr('role', 'dialog')
.appendTo(document.body);
```
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 Debugging System](#-element-debugging-system)
- [๐จ 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
This section documents the internal types, helpers, and data structures used by the `TinyHtml` class. These types provide a flexible abstraction over raw DOM elements and enhanced TinyHtml objects.
---
### ๐งฑ Basic Types
#### `TinyNode`
Represents a raw `Node`, a `TinyHtml` instance, or `null`.
```ts
Node | TinyHtml | null
```
---
#### `TinyElement`
Represents either a raw `Element` or a `TinyHtml` instance.
```ts
Element | TinyHtml
```
---
#### `TinyHtmlElement`
Alias for `HTMLElement | TinyHtml`.
---
#### `TinyEventTarget`
Represents any event target element or a `TinyHtml` instance.
```ts
EventTarget | TinyHtml
```
---
#### `TinyInputElement`
Used for form elements that can hold values (e.g., input, select).
```ts
InputElement | TinyHtml
```
---
#### `TinyElementAndWindow`
Accepts both raw DOM elements and the `window` object.
```ts
ElementAndWindow | TinyHtml
```
---
#### `TinyElementAndWinAndDoc`
Accepts both raw DOM elements, `document`, and the `window` object.
```ts
ElementAndWinAndDoc | TinyHtml
```
---
#### `TinyElementWithDoc`
Accepts both raw DOM elements, the `document` object, or a `TinyHtml` wrapper.
```ts
ElementWithDoc | TinyHtml
```
Used to abstract interactions with either native elements or enhanced wrappers.
---
### ๐ Union Types
#### `ElementWithDoc`
A raw DOM `Element` or the `document` object.
```ts
Element | Document
```
Commonly used when the target might be either a single HTML element or the whole document, particularly in layout and measurement utilities.
---
#### `ElementAndWinAndDoc`
Used for scrollable or measurable targets.
```ts
Element | Window | Document
```
---
#### `ElementAndWindow`
Used for scrollable or measurable targets.
```ts
Element | Window
```
---
#### `WinnowRequest`
Flexible type for querying or filtering elements:
* `string` (CSS selector)
* `Element`
* `Element[]`
* `(index: number, el: Element) => boolean`
---
#### `ConstructorElValues`
Values accepted by the TinyHtml constructor:
```ts
Window | Element | Document | Text
```
---
#### `EventRegistryOptions`
Options for `addEventListener` and `removeEventListener`.
```ts
boolean | AddEventListenerOptions
```
---
#### `EventRegistryItem`
Describes an individual event registration.
```ts
{
handler: EventListenerOrEventListenerObject | null,
options?: EventRegistryOptions
}
```
---
#### `EventRegistryList`
Maps event names (like `"click"`) to lists of `EventRegistryItem`.
```ts
Record
```
---
#### `__eventRegistry`
A `WeakMap` that stores event listeners by element.
```ts
WeakMap
```
---
### ๐พ Element Data
#### `ElementDataStore`
A key-value storage associated with an element.
```ts
Record
```
---
#### `__elementDataMap`
A `WeakMap` to hold internal data for DOM elements.
```ts
WeakMap
```
---
### ๐ฅ Collision System
#### `CollisionDirLock`
Directions supported for collision lock:
```ts
'top' | 'bottom' | 'left' | 'right'
```
---
#### `__elemCollision`
Stores directional collision locks per element.
```ts
{
top: WeakMap,
bottom: WeakMap,
left: WeakMap,
right: WeakMap
}
```
---
### ๐ Box Size Utilities
#### `HtmlElBoxSides`
Describes an elementโs box sizes.
```ts
{
x: number, // total horizontal (left + right)
y: number, // total vertical (top + bottom)
left: number,
right: number,
top: number,
bottom: number
}
```
---
### ๐ข Value Types
#### `SetValueBase`
Primitive types accepted for form inputs.
```ts
string | number | Date | boolean | null
```
---
#### `SetValueList`
A single value or list of values for input fields.
```ts
SetValueBase | SetValueBase[]
```
---
#### `GetValueTypes`
Supported return types for `.val()` operations:
```ts
'string' | 'date' | 'number'
```
---
#### `InputElement`
Supported form controls used by TinyHtml.
```ts
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>}
*/
const __elementAnimateData = new WeakMap();
```
* **Purpose:** Tracks original dimensions and properties of elements for smooth animations.
* **Type:** `WeakMap>`
* **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}
*/
const __elementCurrentAnimation = new WeakMap();
```
* **Purpose:** Keeps track of the active animation per element.
* **Type:** `WeakMap`
* **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} 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} StyleFxResult
*/
```
* **Purpose:** Tracks currently running Web Animations per element.
* **Type:** `Map`
---
### ๐ 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} AnimationSfxData
*/
```
* **Purpose:** Stores start and end states of CSS properties for animations.
* **Type:** `Record`
---
### ๐ 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} StyleEffectsProps
*/
```
* **Purpose:** Groups multiple property handlers for different CSS properties.
* **Type:** `Record`
---
## ๐ Element Debugging System
TinyHtml includes a built-in **element debugging system** to help developers identify issues with elements during validation, construction, or event handling.
This feature is **disabled by default** and can be toggled on or off.
---
### โ๏ธ Enabling Debug Mode
```js
TinyHtml.elemDebug = true; // Enable
TinyHtml.elemDebug = false; // Disable
```
#### API
* **`TinyHtml.elemDebug` (boolean)**
Controls whether TinyHtml emits detailed debug output to the console.
* **Getter**
```js
TinyHtml.elemDebug; // Returns true or false
```
* **Setter**
```js
TinyHtml.elemDebug = true; // Enable debug logs
TinyHtml.elemDebug = false; // Disable debug logs
```
๐จ Throws `TypeError` if the value is not a boolean.
---
### ๐ Debugging Invalid Elements
When debug mode is enabled, TinyHtml will log structured information whenever an invalid or unexpected element is passed to its internal operations.
This is done through the internal method:
```js
TinyHtml._debugElemError(elems, elem);
```
#### Parameters
* **`elems`** โ An array of elements (`ConstructorElValues | EventTarget | TinyElement | null`) involved in the operation.
* **`elem`** *(optional)* โ The specific element that triggered the error.
#### Output Includes
* โ **Error header** in the console
* ๐งญ **Stack trace** (with `console.trace` or captured stack)
* ๐ **`console.table`** showing:
* Index
* `typeof`
* Constructor name
* Summary (DOM tag, ID, class, or nodeType)
* The raw value
* ๐ฏ **Problematic element** highlighted separately via `console.dir`
---
### ๐ Example Output
When debug mode is enabled and an invalid element is detected, you may see something like this:
```
[TinyHtml Debug] Element validation error
Error: [TinyHtml Debug] Element validation error
at TinyHtml._debugElemError (...)
at ...
```
Followed by a **console.table**:
| index | typeOf | constructor | summary | value |
| ----- | ------ | ----------- | ------------------ | ------------- |
| 0 | object | TinyElement | div#main.container | TinyElement{} |
| 1 | string | primitive | | "invalid" |
| 2 | null | null | | null |
And a detailed log of the problematic element:
```
[TinyHtml Debug] Problematic element:
...
```
---
### โ
Summary
* ๐ง Enable debug with `TinyHtml.elemDebug = true;`
* ๐ Detailed errors are shown only when debug mode is on
* ๐ Uses `console.table`, `console.error`, and `console.dir` for clarity
* ๐ Zero runtime overhead when disabled
---
## ๐จ Element Creation
### `TinyHtml.createFrom(tagName, attrs?)`
Creates a new `TinyHtml` element from a given tag name and optional attributes.
* **Parameters**:
* `tagName` *(string)* โ The HTML tag name (e.g., `'div'`, `'span'`, `'button'`).
* `attrs` *(object)* โ *(optional)* Key-value pairs representing HTML attributes.
* **Returns**: `TinyHtml` โ A new `TinyHtml` instance representing the created element.
* **Throws**:
* `TypeError` โ If `tagName` is not a string.
* `TypeError` โ If `attrs` is defined but not a plain object.
### ๐ก Example
```js
const div = TinyHtml.createFrom('div', { class: 'container' });
const span = TinyHtml.createFrom('span', { id: 'my-span', title: null });
```
The method can also be aliased for convenience:
```js
const createElement = TinyHtml.createFrom;
const button = createElement('button', { type: 'submit', class: 'btn' });
```
---
## ๐ Static DOM Selectors
These methods wrap native DOM query methods and return results as `TinyHtml` instances for consistency.
### `TinyHtml.createElement(tagName, ops)`
Creates a new DOM element with the given tag name and optional creation options.
* **Parameters**:
* `tagName` *(string)* โ The tag name of the element to create (e.g., `'div'`, `'span'`).
* `ops` *(ElementCreationOptions)* โ *(optional)* Options for advanced element creation.
* **Returns**: `TinyHtml` โ A `TinyHtml` instance wrapping the newly created element.
* **Throws**:
* `TypeError` โ If `tagName` is not a string.
* `TypeError` โ If `ops` is defined but not an object.
---
### `TinyHtml.createTextNode(value)`
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.
* **Parameters**:
* `value` *(string)* โ 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.
---
### `TinyHtml.createFromHTML(htmlString)`
Creates an `HTMLElement` from an HTML string.
Supports both elements and plain text.
* **Parameters**:
* `htmlString` *(string)* โ The HTML string to convert.
* **Returns**: `TinyHtml` โ A `TinyHtml` instance wrapping the resulting `HTMLElement`.
* **Throws**:
* `Error` โ If the parsed content does not produce a valid `Element` when expecting an HTML structure.
---
### `TinyHtml.query(selector)`
Finds the first element by CSS selector.
- **Parameters**:
- `selector` *(string)* โ CSS selector
- **Returns**: `TinyHtml` or `null`
---
### `TinyHtml.queryAll(selector)`
Finds all elements by CSS selector.
- **Returns**: `TinyHtml`
---
### `TinyHtml.getById(selector)`
Selects an element by ID.
- **Parameters**:
- `selector` *(string)* โ Id selector
- **Returns**: `TinyHtml` or `null`
---
### `TinyHtml.getByClassName(selector)`
Finds elements by class name.
- **Returns**: `TinyHtml`
---
### `TinyHtml.getByName(selector)`
Finds elements by `name` attribute.
- **Returns**: `TinyHtml`
---
### `TinyHtml.getByTagNameNS(localName, namespaceURI?)`
Finds elements by tag name in a namespace (defaults to XHTML).
- **Returns**: `TinyHtml`
---
## ๐ Element Observer
### ๐ `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);
});
// Manually start the observer
TinyHtml.tinyObserver.start();
```
---
## ๐ HTML Parser
### Type Definition
A parsed HTML element represented as an array:
```ts
type HtmlParsed = [
tagName: string, // e.g., 'div', 'span', 'img'
attributes: Record, // Key-value map of all element attributes
...children: (string | HtmlParsed)[] // Nested elements or text content
];
```
---
### `fetchHtmlFile(url, ops?)`
Fetches an HTML file from a URL and parses it into a JSON-like structure.
```ts
static async fetchHtmlFile(url: string | URL | Request, ops?: RequestInit): Promise
```
* **url**: The URL of the HTML file.
* **ops**: (Optional) `fetch()` options (method, headers, etc).
* **Returns**: Promise of parsed JSON structure (`HtmlParsed[]`).
* Throws if content-type is not `text/html`.
---
### `fetchHtmlNodes(url, ops?)`
Fetches an HTML file and returns it as DOM nodes.
```ts
static async fetchHtmlNodes(url: string, ops?: RequestInit): Promise<(HTMLElement | Text)[]>
```
* **Returns**: Array of real DOM nodes (`HTMLElement | Text`).
---
### `fetchHtmlTinyElems(url, ops?)`
Fetches HTML and converts it into an array of `TinyHtml` instances.
```ts
static async fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise
```
* **Returns**: `TinyHtml[]` (custom wrapper elements).
---
### `templateToJson(template)`
Converts the contents of a `` to JSON format.
```ts
static templateToJson(template: HTMLTemplateElement): HtmlParsed[]
```
* **Returns**: Structured JSON representation (`HtmlParsed[]`).
---
### `templateToNodes(template)`
Converts `` content into real DOM nodes.
```ts
static templateToNodes(template: HTMLTemplateElement): (Element | Text)[]
```
* **Returns**: Cloned nodes excluding comments.
* Throws error if unexpected node types are encountered.
---
### `templateToTinyElems(template)`
Converts a `` into `TinyHtml` instances.
```ts
static templateToTinyElems(template: HTMLTemplateElement): TinyHtml[]
```
* **Returns**: Array of `TinyHtml` objects.
---
### `htmlToJson(htmlString)`
Parses an HTML string into structured JSON (`HtmlParsed[]`).
```ts
static htmlToJson(htmlString: string): HtmlParsed[]
```
* **Returns**: Parsed representation as an array of `[tag, attributes, ...children]`.
---
### `jsonToNodes(jsonArray)`
Converts parsed JSON back into actual DOM nodes.
```ts
static jsonToNodes(jsonArray: HtmlParsed[]): (HTMLElement | Text)[]
```
* **Returns**: Array of DOM elements/text nodes.
* Skips comments.
---
### `jsonToTinyElems(jsonArray)`
Converts parsed JSON back into `TinyHtml` instances.
```ts
static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml[]
```
* **Returns**: TinyHtml-wrapped elements.
---
๐ก **Tip**: All conversion methods rely on a consistent internal format (`HtmlParsed[]`). That means you can seamlessly switch between representations (JSON โ DOM โ TinyHtml)!
---
## ๐งฉ Internal Element Access
### `_elCheck(els)`
Validates if all provided items are acceptable constructor values.
* **Parameters**:
* `els` (`ConstructorElValues[]`) โ The elements to validate.
* **Throws**:
* `Error` โ If any element is not a valid target.
* **Returns**: `void`
---
### `add(...el)`
Adds elements to the end of the internal collection.
* **Parameters**:
* `...el` (`ConstructorElValues`) โ The elements to add.
* **Returns**: `TinyHtml` โ A new TinyHtml object containing the combined elements.
---
### `exists(index)`
Checks whether the element exists at the given index.
- **Returns**: `boolean`
---
### `forEach(callback)`
Iterates over all elements in the current instance, executing the provided callback on each one.
* **Parameters**:
* `callback`: `(element: TinyHtml, index: number, items: TinyHtml[]) => void`
Function invoked for each element. Receives the current `TinyHtml`, its index, and the full list.
---
### `get(index)`
Returns the raw DOM element associated with this instance.
- **Returns**: `ConstructorElValues`
---
### `size`
Returns the number of elements currently stored in the internal element list.
- **Returns**: `number`
---
### `extract(index)`
Extracts a single DOM element from the internal list at the specified index.
- **Returns**: `TinyHtml`
---
### `get elements`
Returns the current targets held by this instance.
- **Returns**: `ConstructorElValues[]`
---
### `_getElement(where, index)`
Safely returns the element with error checking.
---
### `_getElements(where)`
Returns the current Elements held by this instance.
---
## ๐ ๏ธ Static Pre-Validation Utilities
These methods normalize, validate, and prepare elements/nodes before operations. They're internal and mainly used inside the class.
### General Templates
#### `_preElemsTemplate(...)`
Validates an array of elements against allowed constructors.
#### `_preElemTemplate(...)`
Validates a single element, optionally allowing `null`.
---
### Common Validators
Each method below ensures type and returns raw DOM objects:
| Method | Target Type | Return |
|-------------------------------|------------------|----------------|
| `_preElems(...)` | `Element[]` | `Element[]` |
| `_preElem(...)` | `Element` | `Element` |
| `_preNodeElems(...)` | `Node[]` | `Node[]` |
| `_preNodeElem(...)` | `Node` | `Node` |
| `_preNodeElemWithNull(...)` | `Node\|null` | `Node\|null` |
| `_preHtmlElems(...)` | `HTMLElement[]` | `HTMLElement[]`|
| `_preHtmlElem(...)` | `HTMLElement` | `HTMLElement` |
| `_preInputElems(...)` | `InputElement[]` | `InputElement[]` |
| `_preInputElem(...)` | `InputElement` | `InputElement` |
| `_preEventTargetElems(...)` | `EventTarget[]` | `EventTarget[]`|
| `_preEventTargetElem(...)` | `EventTarget` | `EventTarget` |
| `_preElemsAndWindow(...)` | `Element\|Window` | `ElementAndWindow[]` |
| `_preElemAndWindow(...)` | `Element\|Window` | `ElementAndWindow` |
| `_preElemsAndWinAndDoc(...)` | `Element\|Window\|Document` | `ElementAndWindow[]` |
| `_preElemAndWinAndDoc(...)` | `Element\|Window\|Document` | `ElementAndWindow` |
| `_preElemsWithDoc(...)` | `Element\|Document` | `ElementWithDoc[]` |
| `_preElemWithDoc(...)` | `Element\|Document` | `ElementWithDoc` |
---
## ๐ Conversion Helpers
These methods convert between raw DOM and `TinyHtml` instances.
### `TinyHtml.toTinyElm(elems)`
Converts one or more raw elements or `TinyHtml` instances into `TinyHtml[]`.
```ts
TinyHtml.toTinyElm(Element | TinyHtml | Array) => TinyHtml[]
```
---
### `TinyHtml.fromTinyElm(elems)`
Extracts native `Element`s from `TinyHtml` instances.
```ts
TinyHtml.fromTinyElm(Element | TinyHtml | Array) => Element[]
```
---
## ๐งน Element Filtering & Matching
This section contains utilities for filtering, matching, and traversing DOM elements using selectors, functions, or references.
---
### ๐ฏ `TinyHtml.winnow(...)`
Advanced filtering engine used internally by many other methods.
- **Parameters**:
- `elems`: Elements to filter.
- `qualifier`: A selector, function, DOM element, or array of them.
- `where`: Context string for debugging.
- `not`: If `true`, invert the match.
- **Returns**: `Element[]`
---
### ๐ Static Filter Utilities
#### `TinyHtml.filter(...)`
Filters elements based on a selector (with optional negation).
#### `TinyHtml.filterOnly(...)`
Same as `.filter()`, but calls `winnow()` directly without the `not` flag.
#### `TinyHtml.not(...)`
Excludes elements matching the qualifier.
#### `TinyHtml.is(...)`
Returns `true` if at least one element matches the qualifier.
#### `TinyHtml.has(...)`
Returns elements that contain a given child (selector or element).
#### `TinyHtml.closest(...)`
Finds the nearest ancestor matching a selector, optionally stopping at a context.
---
### ๐ฆ Instance Filter Methods
#### `.not(selector)`
Returns all current elements excluding the ones that match.
#### `.is(selector)`
Checks if the current element matches the selector or qualifier.
#### `.has(target)`
Returns `true` if the current element contains the given target.
#### `.find(selector)`
Finds matching elements inside the current element.
#### `.closest(selector, context?)`
Finds the closest ancestor (including self) matching a selector or specific element.
#### `.isSameDom(elem)`
Checks if the given element is exactly the same DOM node (`===`).
---
## ๐พ Element Data Store
TinyHtml supports storing arbitrary data on elements, either *publicly* or *privately*.
---
### ๐ Internal Data System
```ts
static _dataSelector = {
public: (where, el) => { ... },
private: (where, el) => { ... },
};
```
* `public`: Data stored in a `WeakMap` attached to DOM nodes.
* `private`: Data stored in an internal property of the `TinyHtml` instance.
---
### ๐๏ธ Static Methods
#### `TinyHtml.data(el, key?, isPrivate?)`
Gets data from the element.
* **Returns**: Entire data object (if `key` omitted) or a single value.
#### `TinyHtml.setData(el, key, value, isPrivate?)`
Sets a value on the elementโs data store.
#### `TinyHtml.hasData(el, key, isPrivate?)`
Checks if a specific key exists in the data store of a DOM element.
#### `TinyHtml.removeData(el, key, isPrivate?)`
Removes a value associated with a specific key from the data store of a DOM element.
---
### ๐ Instance Methods
#### `.data(key?, isPrivate?)`
Shortcut for getting data from the current instanceโs element.
#### `.setData(key, value, isPrivate?)`
Shortcut for setting data on the current element.
#### `.hasData(key, isPrivate?)`
Checks if a specific key exists in the data store of this element.
#### `.removeData(key, isPrivate?)`
Removes a value associated with a specific key from the data store of this element.
---
## ๐ DOM Traversal Methods
Navigate through the DOM tree easily: siblings, parents, children, and more.
---
### ๐ฑ `.parent()` / `TinyHtml.parent(...)`
Gets the **direct parent** of the element (ignores fragments).
---
### ๐ณ `.parents(until?)` / `TinyHtml.parents(...)`
Collects all ancestor elements (like `.closest()`, but goes all the way up).
Stops before `until`, if provided.
---
### โ๏ธ Sibling Navigation
#### `.next()` / `TinyHtml.next(...)`
Returns the next sibling (ignoring non-element nodes).
#### `.prev()` / `TinyHtml.prev(...)`
Returns the previous sibling (ignoring non-element nodes).
#### `.nextAll()` / `TinyHtml.nextAll(...)`
All siblings after the current element.
#### `.prevAll()` / `TinyHtml.prevAll(...)`
All siblings before the current element.
#### `.nextUntil(until)` / `TinyHtml.nextUntil(...)`
All next siblings **up to (not including)** a matching selector or element.
#### `.prevUntil(until)` / `TinyHtml.prevUntil(...)`
All previous siblings **up to (not including)** a matching selector or element.
---
### ๐ง `.siblings()` / `TinyHtml.siblings(...)`
All siblings of the element **excluding itself**.
---
### ๐ถ `.children()` / `TinyHtml.children(...)`
All child nodes (elements only) of the element.
---
### ๐งฉ `.contents()` / `TinyHtml.contents(...)`
Returns the contents of the element:
- For ``, returns its content.
- For `