tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
1,048 lines • 185 kB
text/typescript
export default TinyHtml;
/**
* Represents a TinyHtml instance with any constructor element values.
*/
export type TinyHtmlAny = TinyHtml<ConstructorElValues>;
/**
* Represents the valid values that can be appended to a TinyNode.
*/
export type AppendCheckerTemplate = TinyNode | TinyNode[] | string | false | null | undefined;
/**
* Represents the the collection of values that can be appended to a TinyNode.
*/
export type AppendCheckerValues = AppendCheckerTemplate | AppendCheckerTemplate[];
/**
* Callback function used for hover events.
*/
export type HoverEventCallback = (ev: MouseEvent) => void;
/**
* 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).
*/
export type StyleFxResult = Map<HTMLElement, Animation | null>;
/**
* 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.
*/
export type AnimationSfxData = Record<string, (string | number)[]>;
/**
* Function signature for style effects repeat detectors.
*/
export type StyleEffectsRdFn = (effects: AnimationSfxData) => boolean;
/**
* Function signature for style effect property handlers.
*/
export type StyleEffectsFn = (el: HTMLElement, keyframes: AnimationSfxData, prop: string, style: CSSStyleDeclaration) => void;
/**
* A collection of style effect property handlers.
*/
export type StyleEffectsProps = Record<string, StyleEffectsFn>;
/**
* Callback invoked on each animation frame with the current scroll position,
* normalized animation time (`0` to `1`), and a completion flag.
*/
export type OnScrollAnimation = (progress: {
x: number;
y: number;
isComplete: boolean;
time: number;
}) => void;
/**
* A list of supported easing function names for smooth animations.
*/
export type Easings = "linear" | "easeInQuad" | "easeOutQuad" | "easeInOutQuad" | "easeInCubic" | "easeOutCubic" | "easeInOutCubic";
/**
* Represents a raw Node element or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyNode = Node | TinyHtmlAny | null;
/**
* Represents a raw DOM element or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyElement = Element | TinyHtmlAny;
/**
* Represents a raw DOM html element or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyHtmlElement = HTMLElement | TinyHtmlAny;
/**
* Represents a raw DOM event target element or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyEventTarget = EventTarget | TinyHtmlAny;
/**
* Represents a raw DOM input element or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyInputElement = InputElement | TinyHtmlAny;
/**
* Represents a raw DOM element/window or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyElementAndWindow = ElementAndWindow | TinyHtmlAny;
/**
* Represents a value that can be either a DOM Element or the global Window object.
* Useful for functions that operate generically on scrollable or measurable targets.
*/
export type ElementAndWindow = Element | Window;
/**
* 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.
*/
export type TinyElementAndWinAndDoc = ElementAndWinAndDoc | TinyHtmlAny;
/**
* 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.
*/
export type ElementAndWinAndDoc = Element | Window | Document;
/**
* Represents a raw DOM element with document or an instance of TinyHtml.
* This type is used to abstract interactions with both plain elements
* and wrapped elements via the TinyHtml class.
*/
export type TinyElementWithDoc = ElementWithDoc | TinyHtmlAny;
/**
* Represents a value that can be either a DOM Element, or the document object.
* Useful for functions that operate generically on measurable targets.
*/
export type ElementWithDoc = Element | Document;
/**
* A parameter type used for filtering or matching elements.
* It can be:
* - A string (CSS selector),
* - A raw DOM element,
* - An array of raw DOM elements,
* - A filtering function that receives an index and element,
* and returns true if it matches.
*/
export type WinnowRequest = string | Element | Element[] | ((index: number, el: Element) => boolean);
/**
* Elements accepted as constructor values for TinyHtml.
* These include common DOM elements and root containers.
*/
export type ConstructorElValues = Window | Element | Document | Text;
/**
* Options passed to `addEventListener` or `removeEventListener`.
* Can be a boolean or an object of type `AddEventListenerOptions`.
*/
export type EventRegistryOptions = boolean | AddEventListenerOptions;
/**
* Structure describing a registered event callback and its options.
*/
export type EventRegistryItem = {
/**
* - The function to be executed when the event is triggered.
*/
handler: EventListenerOrEventListenerObject | null;
/**
* - Optional configuration passed to the listener.
*/
options?: EventRegistryOptions | undefined;
};
/**
* Maps event names (e.g., `"click"`, `"keydown"`) to a list of registered handlers and options.
*/
export type EventRegistryList = Record<string, EventRegistryItem[]>;
/**
* A key-value store associated with a specific DOM element.
* Keys are strings, and values can be of any type.
*/
export type ElementDataStore = Record<string, any>;
/**
* Mapping of animation shortcuts to their effect definitions.
* Similar to jQuery's predefined effects (slideDown, fadeIn, etc.).
*/
export type StyleEffects = Record<string, string | (string | number)[]>;
/**
* Possible directions from which a collision was detected and locked.
*/
export type CollisionDirLock = "top" | "bottom" | "left" | "right";
export type HtmlElBoxSides = {
/**
* - Total horizontal size (left + right)
*/
x: number;
/**
* - Total vertical size (top + bottom)
*/
y: number;
left: number;
right: number;
top: number;
bottom: number;
};
/**
* - Primitive types accepted as input values.
*/
export type SetValueBase = string | number | Date | boolean | null;
/**
* Types of value extractors supported by TinyHtml._valTypes.
*/
export type GetValueTypes = "string" | "date" | "number";
/**
* - A single value or an array of values to be assigned to the input element.
*/
export type SetValueList = SetValueBase | SetValueBase[];
/**
* A list of HTML form elements that can have a `.value` property used by TinyHtml.
* Includes common input types used in forms.
*/
export type InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement;
/**
* Represents a parsed HTML element in JSON-like array form.
*/
export type HtmlParsed = [tagName: string, // The tag name of the element (e.g., 'div', 'img')
attributes: Record<string, string>, // All element attributes as key-value pairs
...children: (string | HtmlParsed)[]];
/**
* Represents all possible inputs accepted by the TinyHtml constructor.
* Can be a single element, an array of elements, array-like DOM collections,
* or a CSS selector string.
*/
export type TinyHtmlConstructor = (ConstructorElValues | ConstructorElValues[] | NodeListOf<Element> | HTMLCollectionOf<Element> | NodeListOf<HTMLElement> | string);
/**
* Possible directions from which a collision was detected and locked.
*
* @typedef {'top'|'bottom'|'left'|'right'} CollisionDirLock
*/
/**
* @typedef {Object} HtmlElBoxSides
* @property {number} x - Total horizontal size (left + right)
* @property {number} y - Total vertical size (top + bottom)
* @property {number} left
* @property {number} right
* @property {number} top
* @property {number} bottom
*/
/**
* @typedef {string | number | Date | boolean | null} SetValueBase - Primitive types accepted as input values.
*/
/**
* @typedef {'string' | 'date' | 'number'} GetValueTypes
* Types of value extractors supported by TinyHtml._valTypes.
*/
/**
* @typedef {SetValueBase|SetValueBase[]} SetValueList - A single value or an array of values to be assigned to the input element.
*/
/**
* A list of HTML form elements that can have a `.value` property used by TinyHtml.
* Includes common input types used in forms.
*
* @typedef {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement|HTMLOptionElement} InputElement
*/
/**
* Represents a parsed HTML element in JSON-like array form.
*
* @typedef {[
* tagName: string, // The tag name of the element (e.g., 'div', 'img')
* attributes: Record<string, string>, // All element attributes as key-value pairs
* ...children: (string | HtmlParsed)[] // Text or nested elements
* ]} HtmlParsed
*/
/**
* Represents all possible inputs accepted by the TinyHtml constructor.
* Can be a single element, an array of elements, array-like DOM collections,
* or a CSS selector string.
*
* @typedef {(
* ConstructorElValues |
* ConstructorElValues[] |
* NodeListOf<Element> |
* HTMLCollectionOf<Element> |
* NodeListOf<HTMLElement> |
* string
* )} TinyHtmlConstructor
*/
/**
* TinyHtml is a utility class that provides static and instance-level methods
* for precise dimension and position computations on HTML elements.
* It mimics some jQuery functionalities while using native browser APIs.
*
* Inspired by the jQuery project's open source implementations of element dimension
* and offset utilities. This class serves as a lightweight alternative using modern DOM APIs.
*
* @template {TinyHtmlConstructor} TinyHtmlT
* @class
*/
declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
/** @typedef {import('../basics/collision.mjs').ObjRect} ObjRect */
static Utils: {
getElsRelativeCenterOffset(rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect): {
x: number;
y: number;
};
getElsCollDirDepth(rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect): {
inDir: Dirs | null;
dirX: Dirs | null;
dirY: Dirs | null;
depthX: number;
depthY: number;
};
getElsCollDetails(rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect): {
depth: CollData;
dirs: CollDirs;
isNeg: NegCollDirs;
};
areElsCollTop: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollBottom: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollLeft: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollRight: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollPerfTop: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollPerfBottom: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollPerfLeft: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsCollPerfRight: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
areElsPerfColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => boolean;
getElsColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => string | null;
getElsPerfColliding: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => "top" | "bottom" | "left" | "right" | null;
getElsCollOverlap: (rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => {
overlapLeft: number;
overlapRight: number;
overlapTop: number;
overlapBottom: number;
};
getElsCollOverlapPos: ({ overlapLeft, overlapRight, overlapTop, overlapBottom, }?: {
overlapLeft?: number | undefined;
overlapRight?: number | undefined;
overlapTop?: number | undefined;
overlapBottom?: number | undefined;
}) => {
dirX: Dirs;
dirY: Dirs;
};
getRectCenter: (rect: TinyCollision.ObjRect) => {
x: number;
y: number;
};
};
/** @type {number} */
static "__#private@#version": number;
/** @returns {number} */
static get version(): number;
/**
* Controls whether TinyHtml emits detailed debug output to the console.
* When enabled, helper methods print structured diagnostics for easier troubleshooting.
* @type {boolean}
*/
static "__#private@#elemDebug": boolean;
/**
* Enables or disables debug output.
* @param {boolean} value True to enable debug output; false to disable.
* @throws {TypeError} Thrown if the provided value is not a boolean.
* @returns {void}
*/
static set elemDebug(value: boolean);
/**
* Gets whether debug output is enabled.
* @returns {boolean} True if debug output is enabled; otherwise, false.
*/
static get elemDebug(): boolean;
/**
* Logs a standardized debug error for element validation, including a console.table
* with the involved elements. Use this when an element argument is invalid, unexpected,
* or fails a guard/validation.
*
* The output includes:
* - A concise error header
* - A stack trace (when supported)
* - A table of elements (index, typeof, constructor, summary, value)
* - The specific problematic element, if provided
*
* @param {(ConstructorElValues | EventTarget | TinyElement | null)[]} elems
* A list of elements participating in the operation (may include nulls).
* @param {ConstructorElValues | EventTarget | TinyElement | null} [elem]
* The specific element that triggered the error, if available.
* @returns {void}
*/
static _debugElemError(elems: (ConstructorElValues | EventTarget | TinyElement | null)[], elem?: ConstructorElValues | EventTarget | TinyElement | null, ...args: any[]): void;
/**
* Parse inline styles into an object.
* @param {string} styleText
* @returns {Record<string,string>}
*/
static parseStyle(styleText: string): Record<string, string>;
/**
* Flag to determine if element observer should start automatically.
* @type {boolean}
*/
static "__#private@#autoStartElemObserver": boolean;
/**
* Set the auto-start flag for the observer.
* @param {boolean} value
*/
static set autoStartElemObserver(value: boolean);
/**
* Get the auto-start flag for the observer.
* @returns {boolean}
*/
static get autoStartElemObserver(): boolean;
/** @type {TinyElementObserver} */
static "__#private@#tinyObserver": TinyElementObserver;
/** @returns {TinyElementObserver} */
static get tinyObserver(): TinyElementObserver;
/**
* Fetches an HTML file from the given URL, parses it to JSON.
*
* @param {string | URL | globalThis.Request} url - The URL of the HTML file.
* @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
* @returns {Promise<HtmlParsed[]>} A promise that resolves with the parsed JSON representation of the HTML structure.
*/
static fetchHtmlFile(url: string | URL | globalThis.Request, ops?: RequestInit): Promise<HtmlParsed[]>;
/**
* Fetches an HTML file from the given URL, parses it to JSON, then converts it to DOM nodes.
*
* @param {string} url - The URL of the HTML file.
* @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
* @returns {Promise<(HTMLElement|Text)[]>} A promise that resolves with the DOM nodes.
*/
static fetchHtmlNodes(url: string, ops?: RequestInit): Promise<(HTMLElement | Text)[]>;
/**
* Fetches an HTML file from the given URL, parses it to JSON, then converts it to TinyHtml instances.
*
* @param {string} url - The URL of the HTML file.
* @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
* @returns {Promise<TinyHtml<TinyElement|Text>[]>} A promise that resolves with the TinyHtml instances.
*/
static fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise<TinyHtml<TinyElement | Text>[]>;
/**
* Converts the content of a <template> to an array of HtmlParsed.
*
* @param {HTMLTemplateElement} nodes
* @returns {HtmlParsed[]}
*/
static templateToJson(nodes: HTMLTemplateElement): HtmlParsed[];
/**
* Converts the content of a <template> to real DOM nodes.
*
* @param {HTMLTemplateElement} nodes
* @returns {(Element|Text)[]}
*/
static templateToNodes(nodes: HTMLTemplateElement): (Element | Text)[];
/**
* Converts the content of a <template> to an array of TinyHtml elements.
*
* @param {HTMLTemplateElement} nodes
* @returns {TinyHtml<Element|Text>[]}
*/
static templateToTinyElems(nodes: HTMLTemplateElement): TinyHtml<Element | Text>[];
/**
* Parses a full HTML string into a JSON-like structure.
*
* @param {string} htmlString - Full HTML markup as a string.
* @returns {HtmlParsed[]} An array of parsed HTML elements in structured format.
*/
static htmlToJson(htmlString: string): HtmlParsed[];
/**
* Converts a JSON-like HTML structure back to DOM Elements.
*
* @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
* @returns {(HTMLElement|Text)[]} List of DOM nodes.
*/
static jsonToNodes(jsonArray: HtmlParsed[]): (HTMLElement | Text)[];
/**
* Converts a JSON-like HTML structure back to TinyHtml instances.
*
* @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
* @returns {TinyHtml<HTMLElement | Text>[]} List of TinyHtml instances.
*/
static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml<HTMLElement | Text>[];
/**
* Creates a new TinyHtml element from a tag name and optional attributes.
*
* You can alias this method for convenience:
* ```js
* const createElement = TinyHtml.createFrom;
* const myDiv = createElement('div', { class: 'box' });
* ```
*
* @param {string} tagName - The HTML tag name (e.g., 'div', 'span', 'button').
* @param {Record<string, string|number|null>} [attrs] - Optional key-value pairs representing HTML attributes.
* If the value is `null`, the attribute will still be set with an empty value.
* @returns {TinyHtml<HTMLElement>} - A new instance of TinyHtml representing the created element.
* @throws {TypeError} - If `tagName` is not a string, or `attrs` is not a plain object when defined.
*/
static createFrom(tagName: string, attrs?: Record<string, string | number | null>): TinyHtml<HTMLElement>;
/**
* 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<HTMLElement>} 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: string, ops?: ElementCreationOptions): TinyHtml<HTMLElement>;
/**
* 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<Text>} A TinyHtml instance wrapping the newly created DOM TextNode.
* @throws {TypeError} If the provided value is not a string.
*/
static createTextNode(value: string): TinyHtml<Text>;
/**
* @deprecated Use the {@link createFromHTML} instead.
*
* 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<Element>} - A single HTMLElement or TextNode.
*/
static createElementFromHTML(htmlString: string): TinyHtml<Element>;
/**
* 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<Element>} - A single HTMLElement or TextNode.
*/
static createFromHTML(htmlString: string): TinyHtml<Element>;
/**
* 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<Element>} - A single HTMLElement or TextNode.
*/
static createFromHtml(htmlString: string): TinyHtml<Element>;
/**
* 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.
* @param {Document|Element} elem - Target element.
* @returns {TinyHtml<Element>|null} A TinyHtml instance wrapping the matched element.
*/
static query(selector: string, elem?: Document | Element): TinyHtml<Element> | null;
/**
* 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<NodeListOf<Element>>} An array of TinyHtml instances wrapping the matched elements.
*/
static queryAll(selector: string, elem?: Document | Element): TinyHtml<NodeListOf<Element>>;
/**
* 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<HTMLElement>|null} A TinyHtml instance wrapping the found element.
*/
static getById(selector: string): TinyHtml<HTMLElement> | null;
/**
* 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<HTMLCollectionOf<Element>>} An array of TinyHtml instances wrapping the found elements.
*/
static getByClassName(selector: string, elem?: Document | Element): TinyHtml<HTMLCollectionOf<Element>>;
/**
* Retrieves all elements with the specified name attribute and wraps them in TinyHtml instances.
*
* @param {string} selector - The name attribute to search for.
* @returns {TinyHtml<NodeListOf<HTMLElement>>} An array of TinyHtml instances wrapping the found elements.
*/
static getByName(selector: string): TinyHtml<NodeListOf<HTMLElement>>;
/**
* 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.
* @param {Document|Element} elem - Target element.
* @returns {TinyHtml<HTMLCollectionOf<Element>>} An array of TinyHtml instances wrapping the found elements.
*/
static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml<HTMLCollectionOf<Element>>;
/**
* Prepares and validates multiple elements against allowed types.
*
* @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input elements to validate.
* @param {string} where - The method name or context calling this.
* @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
* @param {string[]} elemName - The list of expected element names for error reporting.
* @returns {any[]} - A flat array of validated elements.
* @throws {Error} - If any element is not an instance of one of the allowed types.
*/
static _preElemsTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[]): any[];
/**
* Prepares and validates a single element against allowed types.
*
* @param {TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[]} elems - The input element or list to validate.
* @param {string} where - The method name or context calling this.
* @param {any[]} TheTinyElements - The list of allowed constructors (e.g., Element, Document).
* @param {string[]} elemName - The list of expected element names for error reporting.
* @param {boolean} [canNull=false] - Whether `null` is allowed as a valid value.
* @returns {any} - The validated element or `null` if allowed.
* @throws {Error} - If the element is not valid or if multiple elements are provided.
*/
static _preElemTemplate(elems: TinyElement | EventTarget | null | (TinyElement | EventTarget | null)[], where: string, TheTinyElements: any[], elemName: string[], canNull?: boolean): any;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single elements.
*
* @param {TinyElement|TinyElement[]} elems - A single element or array of elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {Element[]} - Always returns an array of elements.
*/
static _preElems(elems: TinyElement | TinyElement[], where: string): Element[];
/**
* Ensures the input is returned as an single element.
* Useful to normalize operations across multiple or single elements.
*
* @param {TinyElement|TinyElement[]} elems - A single element or array of elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {Element} - Always returns an single element.
*/
static _preElem(elems: TinyElement | TinyElement[], where: string): Element;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single nodes.
*
* @param {TinyNode|TinyNode[]} elems - A single node or array of nodes.
* @param {string} where - The method or context name where validation is being called.
* @returns {Node[]} - Always returns an array of nodes.
*/
static _preNodeElems(elems: TinyNode | TinyNode[], where: string): Node[];
/**
* Ensures the input is returned as an single node.
* Useful to normalize operations across multiple or single nodes.
*
* @param {TinyNode|TinyNode[]} elems - A single node or array of nodes.
* @param {string} where - The method or context name where validation is being called.
* @returns {Node} - Always returns an single node.
*/
static _preNodeElem(elems: TinyNode | TinyNode[], where: string): Node;
/**
* Ensures the input is returned as an single node.
* Useful to normalize operations across multiple or single nodes.
*
* @param {TinyNode|TinyNode[]} elems - A single node or array of nodes.
* @param {string} where - The method or context name where validation is being called.
* @returns {Node|null} - Always returns an single node or null.
*/
static _preNodeElemWithNull(elems: TinyNode | TinyNode[], where: string): Node | null;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single html elements.
*
* @param {TinyElement|TinyElement[]} elems - A single html element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {HTMLElement[]} - Always returns an array of html elements.
*/
static _preHtmlElems(elems: TinyElement | TinyElement[], where: string): HTMLElement[];
/**
* Ensures the input is returned as an single html element.
* Useful to normalize operations across multiple or single html elements.
*
* @param {TinyElement|TinyElement[]} elems - A single html element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {HTMLElement} - Always returns an single html element.
*/
static _preHtmlElem(elems: TinyElement | TinyElement[], where: string): HTMLElement;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single event target elements.
*
* @param {TinyInputElement|TinyInputElement[]} elems - A single event target element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {InputElement[]} - Always returns an array of event target elements.
*/
static _preInputElems(elems: TinyInputElement | TinyInputElement[], where: string): InputElement[];
/**
* Ensures the input is returned as an single event target element.
* Useful to normalize operations across multiple or single event target elements.
*
* @param {TinyInputElement|TinyInputElement[]} elems - A single event target element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {InputElement} - Always returns an single event target element.
*/
static _preInputElem(elems: TinyInputElement | TinyInputElement[], where: string): InputElement;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single event target elements.
*
* @param {TinyEventTarget|TinyEventTarget[]} elems - A single event target element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {EventTarget[]} - Always returns an array of event target elements.
*/
static _preEventTargetElems(elems: TinyEventTarget | TinyEventTarget[], where: string): EventTarget[];
/**
* Ensures the input is returned as an single event target element.
* Useful to normalize operations across multiple or single event target elements.
*
* @param {TinyEventTarget|TinyEventTarget[]} elems - A single event target element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {EventTarget} - Always returns an single event target element.
*/
static _preEventTargetElem(elems: TinyEventTarget | TinyEventTarget[], where: string): EventTarget;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single element/window elements.
*
* @param {TinyElementAndWindow|TinyElementAndWindow[]} 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.
*/
static _preElemsAndWindow(elems: TinyElementAndWindow | TinyElementAndWindow[], where: string): ElementAndWindow[];
/**
* Ensures the input is returned as an single element/window element.
* Useful to normalize operations across multiple or single element/window elements.
*
* @param {TinyElementAndWindow|TinyElementAndWindow[]} 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.
*/
static _preElemAndWindow(elems: TinyElementAndWindow | TinyElementAndWindow[], where: string): ElementAndWindow;
/**
* 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/document/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/document/window elements.
*/
static _preElemsAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow[];
/**
* 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/document/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/document/window element.
*/
static _preElemAndWinAndDoc(elems: TinyElementAndWinAndDoc | TinyElementAndWinAndDoc[], where: string): ElementAndWindow;
/**
* Ensures the input is returned as an array.
* Useful to normalize operations across multiple or single element with document elements.
*
* @param {TinyElementWithDoc|TinyElementWithDoc[]} elems - A single element with document element or array of html elements.
* @param {string} where - The method or context name where validation is being called.
* @returns {ElementWithDoc[]} - Always returns an array of element with document elements.
*/
static _preElemsWithDoc(elems: TinyElementWithDoc | TinyElementWithDoc[], where: string): ElementWithDoc[];
/**
* Ensures the input is returned as an single element with document element.
* Useful to normalize operations across multiple or single element with document elements.
*
* @param {TinyElementWithDoc|TinyElementWithDoc[]} 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 {ElementWithDoc} - Always returns an single element/window element.
*/
static _preElemWithDoc(elems: TinyElementWithDoc | TinyElementWithDoc[], where: string): ElementWithDoc;
/**
* Normalizes and converts one or more DOM elements (or TinyHtml instances)
* into an array of `TinyHtml` instances.
*
* - If a plain DOM element is passed, it is wrapped into a `TinyHtml` instance.
* - If a `TinyHtml` instance is already passed, it is preserved.
* - If an array is passed, all elements inside are converted accordingly.
*
* This ensures consistent access to methods of the `TinyHtml` class regardless
* of the input form.
*
* @param {TinyElement|Text|(TinyElement|Text)[]} elems - A single element or an array of elements (DOM or TinyHtml).
* @returns {TinyHtml<TinyElement|Text>[]} An array of TinyHtml instances corresponding to the input elements.
*/
static toTinyElm(elems: TinyElement | Text | (TinyElement | Text)[]): TinyHtml<TinyElement | Text>[];
/**
* Extracts native `Element` instances from one or more elements,
* which can be either raw DOM elements or wrapped in `TinyHtml`.
*
* - If a `TinyHtml` instance is passed, its internal DOM element is extracted.
* - If a raw DOM element is passed, it is returned as-is.
* - If an array is passed, each element is processed accordingly.
*
* This function guarantees that the return value is always an array of
* raw `Element` objects, regardless of whether the input was
* a mix of `TinyHtml` or native DOM elements.
*
* @param {TinyElement|TinyElement[]} elems - A single element or an array of elements (DOM or TinyHtml`).
* @returns {Element[]} An array of Element instances extracted from the input.
*/
static fromTinyElm(elems: TinyElement | TinyElement[]): Element[];
/**
* Filters an array of elements based on a selector, function, element, or array of elements.
*
* @param {TinyElement|TinyElement[]} elems
* @param {WinnowRequest} qualifier
* @param {string} where - The context/method name using this validation.
* @param {boolean} not Whether to invert the result (used for .not())
* @returns {Element[]}
*/
static winnow(elems: TinyElement | TinyElement[], qualifier: WinnowRequest, where: string, not?: boolean): Element[];
/**
* Filters a set of elements by a CSS selector.
*
* @param {TinyElement|TinyElement[]} elems
* @param {string} selector
* @param {boolean} not
* @returns {Element[]}
*/
static filter(elems: TinyElement | TinyElement[], selector: string, not?: boolean): Element[];
/**
* Returns only the elements matching the given selector or function.
*
* @param {TinyElement|TinyElement[]} elems
* @param {WinnowRequest} selector
* @returns {Element[]}
*/
static filterOnly(elems: TinyElement | TinyElement[], selector: WinnowRequest): Element[];
/**
* Returns only the elements **not** matching the given selector or function.
*
* @param {TinyElement|TinyElement[]} elems
* @param {WinnowRequest} selector
* @returns {Element[]}
*/
static not(elems: TinyElement | TinyElement[], selector: WinnowRequest): Element[];
/**
* Finds elements matching a selector within a context.
*
* @param {TinyElement|TinyElement[]} context
* @param {string} selector
* @returns {Element[]}
*/
static find(context: TinyElement | TinyElement[], selector: string): Element[];
/**
* Checks if at least one element matches the selector.
*
* @param {TinyElement|TinyElement[]} elems
* @param {WinnowRequest} selector
* @returns {boolean}
*/
static is(elems: TinyElement | TinyElement[], selector: WinnowRequest): boolean;
/**
* Returns elements from the current list that contain the given target(s).
* @param {TinyElement|TinyElement[]} roots - A single element or an array of elements (DOM or TinyHtml).
* @param {string|TinyElement|TinyElement[]} target - Selector or DOM element(s).
* @returns {Element[]} Elements that contain the target.
*/
static has(roots: TinyElement | TinyElement[], target: string | TinyElement | TinyElement[]): Element[];
/**
* Finds the closest ancestor (including self) that matches the selector.
*
* @param {TinyElement|TinyElement[]} els - A single element or an array of elements (DOM or TinyHtml).
* @param {string|Element} selector - A selector string or DOM element to match.
* @param {Element|null} [context] - An optional context to stop searching.
* @returns {Element[]}
*/
static closest(els: TinyElement | TinyElement[], selector: string | Element, context?: Element | null): Element[];
/**
* Compares two DOM elements to determine if they refer to the same node in the document.
*
* This performs a strict equality check (`===`) between the two elements.
*
* @param {TinyNode} elem - The first DOM element to compare.
* @param {TinyNode} otherElem - The second DOM element to compare.
* @returns {boolean} `true` if both elements are the same DOM node; otherwise, `false`.
*/
static isSameDom(elem: TinyNode, otherElem: TinyNode): boolean;
/**
* Internal data selectors for accessing public or private data stores.
*
* @type {Record<string, (where: string, elem: TinyElement) => ElementDataStore>}
*/
static _dataSelector: Record<string, (where: string, elem: TinyElement) => ElementDataStore>;
/**
* Retrieves data associated with a DOM element.
*
* If a `key` is provided, the corresponding value is returned.
* If no `key` is given, a shallow copy of all stored data is returned.
*
* @param {TinyElement} el - The DOM element.
* @param {string|null} [key] - The specific key to retrieve from the data store.
* @param {boolean} [isPrivate=false] - Whether to access the private data store.
* @returns {ElementDataStore|undefined|any} - The stored value, all data, or undefined if the key doesn't exist.
*/
static data(el: TinyElement, key?: string | null, isPrivate?: boolean): ElementDataStore | undefined | any;
/**
* Stores a value associated with a specific key for a DOM element.
*
* @template {TinyElement} T
* @param {T} el - The DOM element.
* @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 {T}
*/
static setData<T extends TinyElement>(el: T, key: string, value: any, isPrivate?: boolean): T;
/**
* Checks if a specific key exists in the data store of a DOM element.
*
* @template {TinyElement} T
* @param {T} el - The DOM element.
* @param {string} key - The key to check.
* @param {boolean} [isPrivate=false] - Whether to check the private store.
* @returns {boolean}
*/
static hasData<T extends TinyElement>(el: T, key: string, isPrivate?: boolean): boolean;
/**
* Removes a value associated with a specific key from the data store of a DOM element.
*
* @param {TinyElement} el - The DOM element.
* @param {string} key - The key to remove.
* @param {boolean} [isPrivate=false] - Whether to remove from the private store.
* @returns {boolean}
*/
static removeData(el: TinyElement, key: string, isPrivate?: boolean): boolean;
/**
* Get the sibling element in a given direction.
*
* @param {TinyNode} el
* @param {"previousSibling"|"nextSibling"} direction
* @param {string} where
* @returns {ChildNode|null}
*/
static _getSibling(el: TinyNode, direction: "previousSibling" | "nextSibling", where: string): ChildNode | null;
/**
* Get all sibling elements excluding the given one.
*
* @param {Node|null} start
* @param {Node|null} [exclude]
* @returns {ChildNode[]}
*/
static _getSiblings(start: Node | null, exclude?: Node | null): ChildNode[];
/**
* Traverse DOM in a direction collecting elements.
*
* @param {TinyNode} el
* @param {"parentNode"|"nextSibling"|"previousSibling"} direction
* @param {TinyNode|string} [until]
* @param {string} [where='domDir']
* @returns {ChildNode[]}
*/
static domDir(el: TinyNode, direction: "parentNode" | "nextSibling" | "previousSibling", until?: TinyNode | string, where?: string): ChildNode[];
/**
* Returns the direct parent node of the given element, excluding document fragments.
*
* @param {TinyNode} el - The DOM node to find the parent of.
* @returns {ParentNode|null} The parent node or null if not found.
*/
static parent(el: TinyNode): ParentNode | null;
/**
* Returns all ancestor nodes of the given element, optionally stopping before a specific ancestor.
*
* @param {TinyNode} el - The DOM node to start from.
* @param {TinyNode|string} [until] - A node or selector to stop before.
* @returns {ChildNode[]} An array of ancestor nodes.
*/
static parents(el: TinyNode, until?: TinyNode | string): ChildNode[];
/**
* Returns the next sibling of the given element.
*
* @param {TinyNode} el - The DOM node to start from.
* @returns {ChildNode|null} The next sibling or null if none found.
*/
static next(el: TinyNode): ChildNode | null;
/**
* Returns the previous sibling of the given element.
*
* @param {TinyNode} el - The DOM node to start from.
* @returns {ChildNode|null} The previous sibling or null if none found.
*/
static prev(el: TinyNode): ChildNode | null;
/**
* Returns all next sibling nodes after the given element.
*
* @param {TinyNode} el - The DOM node to start from.
* @returns {ChildNode[]} An array of next sibling nodes.
*/
static nextAll(el: TinyNode): ChildNode[];
/**
* Returns all previous sibling nodes before the given element.
*
* @param {TinyNode} el - The DOM node to start from.
* @returns {ChildNode[]} An array of previous sibling nodes.
*/
static prevAll(el: TinyNode): ChildNode[];
/**
* Returns all next sibling nodes up to (but not including) the node matched by a selector or element.
*
* @param {TinyNode} el - The DOM node to start from.
* @param {TinyNode|string} [until] - A node or selector to stop before.
* @returns {ChildNode[]} An array of next sibling nodes.
*/
static nextUntil(el: TinyNode, until?: TinyNode | string): ChildNode[];
/**
* Returns all previous sibling nodes up to (but not including) the node matched by a selector or element.
*
* @param {TinyNode} el - The DOM node to start from.
* @param {TinyNode|string} [until] - A node or selector to stop before.
* @returns {ChildNode[]} An array of previous sibling nodes.
*/
static prevUntil(el: TinyNode, until?: TinyNode | string): ChildNode[];
/**
* Returns all sibling nodes of the given element, excluding itself.
*
* @param {TinyNode} el - The DOM node to find siblings of.
* @returns {ChildNode[]} An array of sibling nodes.
*/
static siblings(el: TinyNode): ChildNode[];
/**
* Returns all child nodes of the given element.
*
* @param {TinyNode} el - The DOM node to get children from.
* @returns {ChildNode[]} An array of child nodes.
*/
static children(el: TinyNode): ChildNode[];
/**
* Returns the contents of the given node. For `<template>` it returns its content; for `<iframe>`, the document.
*
* @param {TinyNode} el - The DOM node to get contents from.
* @returns {(ChildNode|DocumentFragment)[]|Document[]} An array of child nodes or the content document of an iframe.
*/
static contents(el: TinyNode): (ChildNode | DocumentFragment)[] | Document[];
/**
* Clone each element.
* @param {TinyNode|TinyNode[]} el
* @param {boolean} [deep=true]
* @returns {Node[]}
*/
static clone(el: TinyNode | TinyNode[], deep?: boolean): Node[];
static _appendChecker(where: string, ...nodes: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): (Node | string)[];
/**
* Appends child elements or strings to the end of the target element(s).
*
* @template {TinyElement} T
* @param {T} el - The target element(s) to receive children.
* @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to append.
* @returns {T}
*/
static append<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): T;
/**
* Prepends child elements or strings to the beginning of the target element(s).
*
* @template {TinyElement} T
* @param {T} el - The target element(s) to receive children.
* @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - The child elements or text to prepend.
* @returns {T}
*/
static prepend<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): T;
/**
* Inserts elements or strings immediately before the target element(s) in the DOM.
*
* @template {TinyElement} T
* @param {T} el - The target element(s) before which new content is inserted.
* @param {...(AppendCheckerValues|Record<string, AppendCheckerValues>)} children - Elements or text to insert before the target.
* @returns {T}
*/
static before<T extends TinyElement>(el: T, ...children: (AppendCheckerValues | Record<string, AppendCheckerValues>)[]): T;
/**
* Inserts elements or strings immediately after the target element(s) in the DOM.