@thi.ng/rdom/dom.d.ts

Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible

import { type MaybeDeref } from "@thi.ng/api/deref";
import type { NumOrElement } from "./api.js";
/**
 * hdom-style DOM tree creation from hiccup format. Returns DOM element of
 * `tree` root. See {@link $el} for further details.
 *
 * @remarks
 * Supports elements given in these forms:
 *
 * - {@link IComponent} instance
 * - [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html)
 *   instance (must resolve to another supported type in this list)
 * - `["div#id.class", {...attribs}, ...children]`
 * - `[COMMENT, "foo", "bar"...]` (DOM comment node)
 * - `[IComponent, ...mountargs]`
 * - `[function, ...args]`
 * - `["tag", {...attribs}, noArgFunction, "other"]`
 * - ES6 iterable of the above (for child values only!)
 *
 * Any other values will be cast to strings and added as spans to current
 * `parent`.
 *
 * Note: `COMMENT` is defined as constant in thi.ng/hiccup package. Also see
 * {@link $comment} function to create comments directly.
 *
 * @param tree -
 * @param parent -
 * @param idx -
 */
export declare const $tree: (tree: any, parent: ParentNode, idx?: NumOrElement) => Promise<any>;
/**
 * Create a single DOM element and optionally attaches it to `parent`.
 *
 * @remarks
 * If `tag` is a namespaced tagname (e.g. `prefix:tag`), the element will be
 * created via `document.createElementNS()` and the prefix will be resolved via
 * known aliases registered by {@link registerPrefix}. SVG element names do not
 * need to be prefixed and are recognized automatically.
 *
 * Supports Emmet-style tag names in this form: `tag#id.class1.class2`.
 * `attribs` is a plain object of element attributes. See {@link $attribs} for
 * further details.
 *
 * If `parent` is given, but no `idx` arg, the new element will be appended as
 * child.
 *
 * @param tag -
 * @param attribs -
 * @param body -
 * @param parent -
 * @param idx -
 */
export declare const $el: (tag: string, attribs: any, body?: any, parent?: ParentNode, idx?: NumOrElement) => Element;
/**
 * Similar to {@link $el}, but creates a new comment DOM node using provided
 * body. If `parent` is given, the comment will be attached or inserted as child
 * at `idx`. Returns comment node.
 *
 * @remarks
 * See thi.ng/hiccup docs for reference:
 * https://docs.thi.ng/umbrella/hiccup/functions/serialize.html
 *
 * @param body
 * @param parent
 * @param idx
 */
export declare const $comment: (body: string | string[], parent?: ParentNode, idx?: NumOrElement) => Comment;
/**
 * Appends or inserts `child` as child element of `parent`. The default `idx` of
 * -1 means the child will be appended, else uses `parent.insertBefore()` to
 * insert at given index.
 *
 * @param parent
 * @param child
 * @param idx
 */
export declare const $addChild: (parent: ParentNode, child: Node | Comment, idx?: NumOrElement) => void;
/**
 * Removes given element or comment from the DOM.
 *
 * @param el
 */
export declare const $remove: (el: Element | Comment) => void;
/**
 * Migrates given element to `newParent`, following the same append or insertion
 * logic as {@link $addChild}.
 *
 * @param newParent
 * @param el
 * @param idx
 */
export declare const $moveTo: (newParent: ParentNode, el: Element | Comment, idx?: NumOrElement) => void;
/**
 * Removes all content from given element.
 *
 * @param el
 */
export declare const $clear: (el: Element) => Element;
/**
 * Same as `el.textContent = body`, however if `body` is an
 * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) it'll be
 * first automatically deref'd and coerced to a string. If `body === undefined`
 * an empty string will be used.
 *
 * @param el -
 * @param body -
 */
export declare const $text: (el: HTMLElement | SVGElement, body: any) => void;
/**
 * Same as `el.innerHtml = body`, use with caution! If `body` is an
 * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) it'll be
 * automatically deref'd.
 *
 * @param el -
 * @param body -
 */
export declare const $html: (el: HTMLElement | SVGElement, body: MaybeDeref<string>) => void;
/**
 * Takes an object of attributes and applies them to given DOM element.
 *
 * @remarks
 * The following rules & transformations are applied (in the stated order):
 *
 * - [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) values
 *   are `deref`d
 * - attributes prefixed with `on` are considered event listeners and can either
 *   have a function value or tuple of `[listener, opts]`, where `opts` are the
 *   standard `.addEventListener()` options
 * - function values for any other attribs are first called with the entire
 *   `attribs` object and return value used
 * - array values are converted into space-delimited string
 *
 * CSS classes can be given as `class` attribute, with its value either a
 * string, a string array or an object of booleans. If the latter, the given
 * class names are either added to or removed from the current list of classes.
 * See
 * [`mergeClasses`](https://docs.thi.ng/umbrella/hiccup/functions/mergeClasses.html)
 * for details.
 *
 * CSS style rules can be defined via the `style` attrib. Please see
 * {@link $style} for further details.
 *
 * Data attributes are to be given as object under the `data` attribute name,
 * with its values being merged with the element's current `dataset` property.
 *
 * Depending on element type, the `value` attribute will be updated keeping the
 * current cursor position / selection intact. (**NOT** done for disabled or
 * readonly elements due to issues with Safari)
 *
 * @param el -
 * @param attribs -
 */
export declare const $attribs: (el: Element, attribs: any) => Element;
/**
 * Takes an object (or string) of CSS properties, compiles them into a single
 * CSS string and sets it as `style` attribute on the given element.
 *
 * @remarks
 * All property values can be
 * [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) values,
 * in which case they're are first `deref`d before use. If the value is a
 * function, it will be called with the entire `rules` object as arg and the
 * return value used.
 *
 * @param el -
 * @param rules -
 */
export declare const $style: (el: Element, rules: string | any) => void;
/**
 * Adds or removes the given CSS classes from a DOM element. If a class is
 * currently present it will be removed, otherwise added.
 *
 * @param el
 * @param classes
 */
export declare const $toggleClasses: (el: Element, ...classes: string[]) => void;
/**
 * Registers an XML namespace prefix and its URL for later use, e.g. to define
 * namespaced elements/attributes via {@link $el}, {@link $tree}.
 *
 * @param prefix -
 * @param url -
 */
export declare const registerPrefix: (prefix: string, url: string) => void;
//# sourceMappingURL=dom.d.ts.map