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,036 lines • 136 kB
text/typescript
export default TinyHtml;
/**
* 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 | TinyHtml | 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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 | TinyHtml;
/**
* 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>;
/**
* 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)[]];
/**
* 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
*/
/**
* 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.
*
* @class
*/
declare class TinyHtml {
/** @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: (
/**
* @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
*/
/**
* 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.
*
* @class
*/
rect1: TinyCollision.ObjRect, rect2: TinyCollision.ObjRect) => string | null;
getElsPerfColliding: (rect1: TinyCollision.ObjRect /**
* 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
*/
/**
* 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.
*
* @class
*/
, 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;
};
};
/**
* 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[]>} A promise that resolves with the TinyHtml instances.
*/
static fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise<TinyHtml[]>;
/**
* 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[]}
*/
static templateToTinyElems(nodes: HTMLTemplateElement): TinyHtml[];
/**
* 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[]} List of TinyHtml instances.
*/
static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml[];
/**
* 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|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} - 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 | null>): TinyHtml;
/**
* Creates a new DOM element with the specified tag name and options, then wraps it in a TinyHtml instance.
*
* @param {string} tagName - The tag name of the element to create (e.g., 'div', 'span').
* @param {ElementCreationOptions} [ops] - Optional settings for creating the element.
* @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM element.
* @throws {TypeError} If tagName is not a string or ops is not an object.
*/
static createElement(tagName: string, ops?: ElementCreationOptions): TinyHtml;
/**
* Creates a new TinyHtml instance that wraps a DOM TextNode.
*
* This method is useful when you want to insert raw text content into the DOM
* without it being interpreted as HTML. The returned instance behaves like any
* other TinyHtml element and can be appended or manipulated as needed.
*
* @param {string} value - The plain text content to be wrapped in a TextNode.
* @returns {TinyHtml} A TinyHtml instance wrapping the newly created DOM TextNode.
* @throws {TypeError} If the provided value is not a string.
*/
static createTextNode(value: string): TinyHtml;
/**
* Creates an HTMLElement or TextNode from an HTML string.
* Supports both elements and plain text.
*
* @param {string} htmlString - The HTML string to convert.
* @returns {TinyHtml} - A single HTMLElement or TextNode.
*/
static createElementFromHTML(htmlString: string): TinyHtml;
/**
* 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|null} A TinyHtml instance wrapping the matched element.
*/
static query(selector: string, elem?: Document | Element): TinyHtml | 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} An array of TinyHtml instances wrapping the matched elements.
*/
static queryAll(selector: string, elem?: Document | Element): TinyHtml;
/**
* 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|null} A TinyHtml instance wrapping the found element.
*/
static getById(selector: string): TinyHtml | 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} An array of TinyHtml instances wrapping the found elements.
*/
static getByClassName(selector: string, elem?: Document | Element): TinyHtml;
/**
* 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} An array of TinyHtml instances wrapping the found elements.
*/
static getByName(selector: string): TinyHtml;
/**
* 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} An array of TinyHtml instances wrapping the found elements.
*/
static getByTagNameNS(localName: string, namespaceURI?: string | null, elem?: Document | Element): TinyHtml;
/**
* 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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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.
* @readonly
*/
static readonly _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[]} An array of TinyHtml instances corresponding to the input elements.
*/
static toTinyElm(elems: TinyElement | Text | (TinyElement | Text)[]): TinyHtml[];
/**
* 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>}
* @readonly
*/
static readonly _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.
*
* @param {TinyElement} 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 {TinyElement}
*/
static setData(el: TinyElement, key: string, value: any, isPrivate?: boolean): TinyElement;
/**
* Get the sibling element in a given direction.
*
* @param {TinyNode} el
* @param {"previousSibling"|"nextSibling"} direction
* @param {string} where
* @returns {ChildNode|null}
* @readonly
*/
static readonly _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[]}
* @readonly
*/
static readonly _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 readonly _appendChecker(where: string, ...nodes: (TinyNode | TinyNode[] | string)[]): (Node | string)[];
/**
* Appends child elements or strings to the end of the target element(s).
*
* @param {TinyElement} el - The target element(s) to receive children.
* @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to append.
* @returns {TinyElement}
*/
static append(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
/**
* Prepends child elements or strings to the beginning of the target element(s).
*
* @param {TinyElement} el - The target element(s) to receive children.
* @param {...(TinyNode | TinyNode[] | string)} children - The child elements or text to prepend.
* @returns {TinyElement}
*/
static prepend(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
/**
* Inserts elements or strings immediately before the target element(s) in the DOM.
*
* @param {TinyElement} el - The target element(s) before which new content is inserted.
* @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert before the target.
* @returns {TinyElement}
*/
static before(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
/**
* Inserts elements or strings immediately after the target element(s) in the DOM.
*
* @param {TinyElement} el - The target element(s) after which new content is inserted.
* @param {...(TinyNode | TinyNode[] | string)} children - Elements or text to insert after the target.
* @returns {TinyElement}
*/
static after(el: TinyElement, ...children: (TinyNode | TinyNode[] | string)[]): TinyElement;
/**
* Replaces the target element(s) in the DOM with new elements or text.
*
* @param {TinyElement} el - The element(s) to be replaced.
* @param {...(TinyNode | TinyNode[] | string)} newNodes - New elements or text to replace the target.
* @returns {TinyElement}
*/
static replaceWith(el: TinyElement, ...newNodes: (TinyNode | TinyNode[] | string)[]): TinyElement;
/**
* Appends the given element(s) to each target element in sequence.
*
* @param {TinyNode | TinyNode[]} el - The element(s) to append.
* @param {TinyNode | TinyNode[]} targets - Target element(s) where content will be appended.
* @returns {TinyNode|TinyNode[]}
*/
static appendTo(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
/**
* Prepends the given element(s) to each target element in sequence.
*
* @param {TinyElement | TinyElement[]} el - The element(s) to prepend.
* @param {TinyElement | TinyElement[]} targets - Target element(s) where content will be prepended.
* @returns {TinyElement|TinyElement[]}
*/
static prependTo(el: TinyElement | TinyElement[], targets: TinyElement | TinyElement[]): TinyElement | TinyElement[];
/**
* Inserts the element before a child of a given target, or before the target itself.
*
* @param {TinyNode | TinyNode[]} el - The element(s) to insert.
* @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
* @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert before, defaults to target.
* @returns {TinyNode|TinyNode[]}
*/
static insertBefore(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
/**
* Inserts the element after a child of a given target, or after the target itself.
*
* @param {TinyNode | TinyNode[]} el - The element(s) to insert.
* @param {TinyNode | TinyNode[]} target - The reference element where insertion happens.
* @param {TinyNode | TinyNode[] | null} [child=null] - Optional child to insert after, defaults to target.
* @returns {TinyNode|TinyNode[]}
*/
static insertAfter(el: TinyNode | TinyNode[], target: TinyNode | TinyNode[], child?: TinyNode | TinyNode[] | null): TinyNode | TinyNode[];
/**
* Replaces all target elements with the provided element(s).
* If multiple targets exist, the inserted elements are cloned accordingly.
*
* @param {TinyNode | TinyNode[]} el - The new element(s) to insert.
* @param {TinyNode | TinyNode[]} targets - The elements to be replaced.
* @returns {TinyNode|TinyNode[]}
*/
static replaceAll(el: TinyNode | TinyNode[], targets: TinyNode | TinyNode[]): TinyNode | TinyNode[];
/**
* Checks whether the given object is a window.
* @param {*} obj - The object to test.
* @returns {obj is Window} - True if it's a Window.
*/
static isWindow(obj: any): obj is Window;
/**
* Returns the full computed CSS styles for the given element.
*
* @param {TinyElement} el - The element to retrieve styles from.
* @returns {CSSStyleDeclaration} The computed style object for the element.
*/
static css(el: TinyElement): CSSStyleDeclaration;
/**
* Returns the value of a specific computed CSS property from the given element as a string.
*
* @param {TinyElement} el - The element to retrieve the style property from.
* @param {string} prop - The name of the CSS property (camelCase or kebab-case).
* @returns {string|null} The value of the CSS property as a string, or null if not found or invalid.
*/
static cssString(el: TinyElement, prop: string): string | null;
/**
* Returns a subset of computed CSS styles based on the given list of properties.
*
* @param {TinyElement} el - The element to retrieve styles from.
* @param {string[]} prop - An array of CSS property names to retrieve.
* @returns {Partial<CSSStyleDeclaration>} An object containing the requested styles.
*/
static cssList(el: TinyElement, prop: string[]): Partial<CSSStyleDeclaration>;
/**
* Returns the computed CSS float value of a property.
* @param {T