mancha/dist/renderer.d.ts

Javscript HTML rendering engine

import type { DebugLevel, EffectMeta, ParserParams, PerformanceReport, RenderParams } from "./interfaces.js";
import type { StoreState } from "./store.js";
import { SignalStore } from "./store.js";
export type EvalListener = (result: unknown, dependencies: string[]) => unknown;
/**
 * Represents an abstract class for rendering and manipulating HTML content.
 * Extends the `ReactiveProxyStore` class.
 *
 * @template T - The type of the store state. Defaults to `StoreState`.
 */
export declare abstract class IRenderer<T extends StoreState = StoreState> extends SignalStore<T> {
    abstract readonly impl: string;
    private _debugLevel;
    protected readonly dirpath: string;
    /** Performance data collected during rendering. Reset on each mount(). */
    private _perfData;
    /** Debug level ordering for comparison. */
    private static readonly DEBUG_LEVELS;
    readonly _skipNodes: Set<Node>;
    readonly _customElements: Map<string, Node>;
    /**
     * Queue for retrying failed element.value assignments.
     *
     * Some DOM elements (notably <select>) silently fail when setting .value if
     * the required child elements don't exist yet. For example, setting
     * select.value = "banana" does nothing if no <option value="banana"> exists.
     *
     * This happens when :bind on a parent element runs before :for on child
     * elements creates those children (due to BFS traversal order).
     *
     * The fix: after setting .value, check if it actually worked. If not, queue
     * a retry callback. These callbacks are executed at the end of renderNode()
     * after all child elements have been created.
     */
    readonly _pendingValueRetries: Array<() => void>;
    abstract parseHTML(content: string, params?: ParserParams): Document | DocumentFragment;
    abstract serializeHTML(root: DocumentFragment | Node): string;
    abstract createElement(tag: string, owner?: Document | null): Element;
    abstract createComment(content: string, owner?: Document | null): Node;
    abstract textContent(node: Node, tag: string): void;
    /**
     * Sets the debug level for the current instance.
     *
     * @param flag - Boolean for backwards compat (true -> 'lifecycle') or a DebugLevel.
     * @returns The current instance of the class.
     */
    debug(flag: boolean | DebugLevel): this;
    /**
     * Returns whether debugging is enabled (any level except 'off').
     */
    get debugging(): boolean;
    /**
     * Checks if the current debug level is at least the specified level.
     */
    private shouldLog;
    /**
     * Resets performance data. Called at the start of mount().
     */
    private resetPerfData;
    /**
     * Generates a DOM path for an element (e.g., "html>body>div>ul>li:nth-child(2)").
     */
    private getNodePath;
    /**
     * Builds an effect identifier from metadata.
     */
    buildEffectId(meta?: EffectMeta): string;
    /**
     * Records an effect execution for performance tracking.
     */
    recordEffectExecution(meta: EffectMeta | undefined, duration: number): void;
    /**
     * Returns a structured performance report.
     */
    performanceReport(): PerformanceReport;
    /**
     * Override effect() to add performance tracking.
     * Tracks effect execution time and logs slow effects (>16ms).
     */
    effect<T>(observer: () => T, meta?: EffectMeta): T;
    /**
     * Fetches the remote file at the specified path and returns its content as a string.
     * @param fpath - The path of the remote file to fetch.
     * @param params - Optional parameters for the fetch operation.
     * @returns A promise that resolves to the content of the remote file as a string.
     */
    fetchRemote(fpath: string, params?: RenderParams): Promise<string>;
    /**
     * Fetches a local path and returns its content as a string.
     *
     * @param fpath - The file path of the resource.
     * @param params - Optional render parameters.
     * @returns A promise that resolves to the fetched resource as a string.
     */
    fetchLocal(fpath: string, params?: RenderParams): Promise<string>;
    /**
     * Preprocesses a string content with optional rendering and parsing parameters.
     *
     * @param content - The string content to preprocess.
     * @param params - Optional rendering and parsing parameters.
     * @returns A promise that resolves to a DocumentFragment representing the preprocessed content.
     */
    preprocessString(content: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
    /**
     * Preprocesses a remote file by fetching its content and applying preprocessing steps.
     * @param fpath - The path to the remote file.
     * @param params - Optional parameters for rendering and parsing.
     * @returns A Promise that resolves to a DocumentFragment representing the preprocessed content.
     */
    preprocessRemote(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
    /**
     * Preprocesses a local file by fetching its content and applying preprocessing steps.
     * @param fpath - The path to the local file.
     * @param params - Optional parameters for rendering and parsing.
     * @returns A promise that resolves to the preprocessed document fragment.
     */
    preprocessLocal(fpath: string, params?: RenderParams & ParserParams): Promise<Document | DocumentFragment>;
    /**
     * Creates a subrenderer from the current renderer instance.
     * @returns A new instance of the renderer with the same state as the original.
     */
    subrenderer(): IRenderer;
    /**
     * Logs the provided arguments if verbose debugging is enabled.
     * @param args - The arguments to be logged.
     */
    log(...args: unknown[]): void;
    /**
     * Preprocesses a node by applying all the registered preprocessing plugins.
     *
     * @template T - The type of the input node.
     * @param {T} root - The root node to preprocess.
     * @param {RenderParams} [params] - Optional parameters for preprocessing.
     * @returns {Promise<T>} - A promise that resolves to the preprocessed node.
     */
    preprocessNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
    /**
     * Renders the node and applies all the registered rendering plugins.
     *
     * @template T - The type of the root node (Document, DocumentFragment, or Node).
     * @param {T} root - The root node to render.
     * @param {RenderParams} [params] - Optional parameters for rendering.
     * @returns {Promise<T>} - A promise that resolves to the fully rendered root node.
     */
    renderNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
    /**
     * Mounts the Mancha application to a root element in the DOM.
     *
     * @param root - The root element to mount the application to.
     * @param params - Optional parameters for rendering the application.
     * @returns A promise that resolves when the mounting process is complete.
     */
    mount(root: Document | DocumentFragment | Node, params?: RenderParams): Promise<void>;
}