@tempots/dom/dom/dom-context.d.ts

Fully-typed frontend framework alternative to React and Angular

import { Clear, ProviderMark } from '../types/domain';
import { Primitive, makeProviderMark } from '@tempots/core';
import { BrowserContext } from './browser-context';
import { HeadlessContext } from './headless-context';
export { makeProviderMark };
/**
 * Options for event listeners.
 *
 * @public
 */
export type HandlerOptions = {
    once?: boolean;
    signal?: AbortSignal;
    passive?: boolean;
    capture?: boolean;
};
/**
 * `DOMContext` is an immutable class that represents the context of a DOM element.
 * It provides methods and properties to manipulate and interact with the DOM element.
 *
 * A reference in a DOMContext is to mark a position within a set of siblings.
 * It is used to insert new elements before the reference.
 *
 * @public
 */
export interface DOMContext {
    /**
     * Creates a new DOM element (eg: HTML or SVG) with the specified tag name and namespace and appends it to the current element.
     *
     * @param tagName - The tag name of the element to create.
     * @param namespace - The namespace URI to create the element in, or `undefined` to create a standard HTML element.
     * @returns The newly created element.
     */
    makeChildElement(tagName: string, namespace: string | undefined): DOMContext;
    /**
     * Creates a new text node with the specified text content and appends it to the current element.
     * @param text - The text content for the new text node.
     * @returns A new `DOMContext` with a reference to the new text node.
     */
    makeChildText(text: Primitive): DOMContext;
    /**
     * Sets the text content of the current element.
     * @param text - The text content to set.
     */
    setText(text: Primitive): void;
    /**
     * Gets the text content of the current element or text node.
     * @returns The text content of the current element or text node.
     */
    getText(): string;
    /**
     * Creates a new `DOMContext` with a reference to a newly created text node.
     * The text node is appended or inserted to the current `DOMContext`.
     * The new `DOMContext` with the reference is returned.
     */
    makeRef(): DOMContext;
    /**
     * Creates a new `DOMContext` instance with a reference to a DOM element selected by the provided `selector`.
     * @param selector - The CSS selector for the target DOM element.
     * @returns A new `DOMContext` instance with a reference to the selected DOM element.
     */
    makePortal(selector: string | HTMLElement): DOMContext;
    /**
     * Retrieves a provider for the given provider mark.
     *
     * @param mark - The provider mark to retrieve the provider for.
     * @returns The provider for the given mark.
     * @throws Throws `ProviderNotFoundError` if the provider for the given mark is not found.
     */
    getProvider<T>(mark: ProviderMark<T>): {
        value: T;
        onUse?: () => void;
    };
    /**
     * Retrieves a provider for the given provider mark, returning `undefined`
     * if the provider is not found instead of throwing.
     *
     * @param mark - The provider mark to retrieve the provider for.
     * @returns The provider value and optional onUse callback, or `undefined` if not found.
     */
    tryGetProvider<T>(mark: ProviderMark<T>): {
        value: T;
        onUse?: () => void;
    } | undefined;
    /**
     * Sets a provider for the given provider mark.
     *
     * @param mark - The provider mark to set the provider for.
     * @param value - The provider to set for the given mark.
     */
    setProvider<T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)): DOMContext;
    clear(removeTree: boolean): void;
    /**
     * Adds an event listener to the element.
     * @param event - The event to listen for.
     * @param listener - The listener to call when the event occurs.
     * @param options - The options for the event listener.
     * @returns A function to remove the event listener.
     */
    on<E>(event: string, listener: (event: E, ctx: DOMContext) => void, options?: HandlerOptions): Clear;
    /**
     * Adds classes to the element.
     * @param tokens - The class names to add.
     */
    addClasses(tokens: string[]): void;
    /**
     * Removes classes from the element.
     * @param tokens - The class names to remove.
     */
    removeClasses(tokens: string[]): void;
    /**
     * Gets the classes of the element.
     * @returns The classes of the element.
     */
    getClasses(): string[];
    /**
     * Returns `true` if the context is a browser DOM context.
     * @returns `true` if the context is a browser DOM context.
     * @deprecated Use `isBrowser()` instead.
     */
    isBrowserDOM(): this is BrowserContext;
    /**
     * Returns `true` if the context is a browser DOM context.
     * @returns `true` if the context is a browser DOM context.
     */
    isBrowser(): this is BrowserContext;
    /**
     * Returns `true` if the context is a headless DOM context.
     * @returns `true` if the context is a headless DOM context.
     */
    isHeadlessDOM(): this is HeadlessContext;
    /**
     * Returns `true` if the context is a headless context.
     * @returns `true` if the context is a headless context.
     */
    isHeadless(): this is HeadlessContext;
    /**
     * Sets the style of the element.
     * @param name - The name of the style to set.
     * @param value - The value of the style to set.
     */
    setStyle(name: string, value: string): void;
    /**
     * Gets the style of the element.
     * @param name - The name of the style to get.
     * @returns The value of the style.
     */
    getStyle(name: string): string;
    /**
     * Returns an object with methods to get and set the value of a property or attribute.
     * @param name - The name of the property to create accessors for.
     * @returns An object with methods to get and set the value of the property.
     */
    makeAccessors(name: string): {
        get(): unknown;
        set(value: unknown): void;
    };
    /**
     * Moves a range of sibling nodes (from `startRef` to `endRef` inclusive)
     * before `targetRef`. All three refs must be children of the same parent element.
     *
     * Used by `KeyedForEach` to reorder keyed items without recreating DOM nodes.
     *
     * @param startRef - The context whose reference marks the start of the range.
     * @param endRef - The context whose reference marks the end of the range.
     * @param targetRef - The context before which the range will be inserted.
     */
    moveRangeBefore(startRef: DOMContext, endRef: DOMContext, targetRef: DOMContext): void;
    /**
     * Removes all sibling nodes between `startRef` and `endRef` (inclusive).
     * Used for bulk removal of keyed entries.
     */
    removeRange(startRef: DOMContext, endRef: DOMContext): void;
    /**
     * Creates a lightweight marker node (Comment node) as a boundary reference.
     */
    makeMarker(): DOMContext;
    /**
     * Removes all sibling nodes before the given reference marker in one
     * operation. Used as a fast path for clearing entire lists.
     */
    removeAllBefore(ref: DOMContext): void;
    /**
     * Detaches the context's container element from the live DOM tree.
     * Use before bulk insertions to avoid incremental layout recalculations.
     */
    detach(): void;
    /**
     * Re-attaches the container element after a detach.
     */
    reattach(): void;
}