lazy-widgets/dist/xml/BaseXMLUIParser.d.ts

Typescript retained mode GUI for the HTML canvas API

import { Widget } from '../widgets/Widget.js';
import type { WidgetAutoXML, WidgetXMLInputConfig, WidgetAutoXMLConfigValidator } from './WidgetAutoXML.js';
import type { XMLUIParserConfig } from './XMLUIParserConfig.js';
import type { XMLUIParserContext } from './XMLUIParserContext.js';
import type { XMLWidgetFactory } from './XMLWidgetFactory.js';
import type { XMLAttributeValueDeserializer } from './XMLAttributeValueDeserializer.js';
import type { XMLAttributeNamespaceHandler } from './XMLAttributeNamespaceHandler.js';
import type { XMLElementDeserializer } from './XMLElementDeserializer.js';
import type { XMLParameterModeValidator } from './XMLParameterModeValidator.js';
import type { XMLArgumentModifier } from './XMLArgumentModifier.js';
import type { XMLPostInitHook } from './XMLPostInitHook.js';
import type { WidgetConstructor } from '../core/WidgetConstructor.js';
/**
 * The base lazy-widgets XML namespace. All lazy-widgets namespaces will be
 * prefixed with this. lazy-widgets elements must use this namespace.
 *
 * @category XML
 */
export declare const XML_NAMESPACE_BASE = "lazy-widgets";
/**
 * A bare-bones XML UI parser. This must not be used directly as this is an
 * extensible parser; you are supported to create a subclass of this and add all
 * the features/validators that you need.
 *
 * You won't need to create your own parser unless you have an XML format that
 * is not compatible with the default format. Most times it's enough to use
 * {@link XMLUIParser} and register new features if necessary.
 *
 * @category XML
 */
export declare abstract class BaseXMLUIParser {
    /** The DOMParser to actually parse the XML into nodes */
    private domParser;
    /** A map which assigns a factory function to an element name. */
    private factories;
    /**
     * A map which assigns a validator function to a unique name, allowing a
     * validator to be referred to by string. Referred to as built-in
     * validators.
     */
    private validators;
    /**
     * A map which assigns a single character string prefix to a string
     * deserializer.
     */
    private attributeValueDeserializers;
    /** A map which assigns an attribute namespace to a handler function. */
    private attributeNamespaceHandlers;
    /** A map which assigns an element name to a an XML element deserializer. */
    private elementDeserializers;
    /** A map which defines custom parameter modes. */
    private parameterModes;
    /** A list of functions that modify a factory's parameter list. */
    private argumentModifiers;
    /**
     * A list of functions that are invoked after a widget is instanced, so that
     * the instance can be modified post-initialization.
     */
    private postInitHooks;
    /**
     * Parse a value in an attribute. The value will be deserialized according
     * to its prefix. If there is no prefix, the value is treated as a string.
     *
     * @param rawValue - The value in the attribute, with the prefix included
     * @param context - The current parser context, which will be passed to a deserializer if the value is prefixed with a registered deserializer prefix
     */
    parseAttributeValue(rawValue: string, context: XMLUIParserContext): unknown;
    /**
     * Find the next unset parameter of a given mode.
     *
     * @param paramConfig - The input mapping of the widget being built
     * @param parametersSet - A list containing which of the parameters in the input mapping are already set
     * @param mode - The parameter mode to find
     * @returns Returns the index of the next unset parameter of the wanted mode. If none are found, -1 is returned.
     */
    findNextParamOfType(paramConfig: WidgetXMLInputConfig, parametersSet: Array<boolean>, mode: string): number;
    /** Create a new widget instance given a config and context */
    private instantiateWidget;
    /**
     * Register a widget factory to an element name, with a given input mapping.
     *
     * @param nameOrWidgetClass - The camelCase or PascalCase name of the widget, which will be converted to kebab-case and be used as the element name for the widget. If a widget class is passed, then the class name will be used and converted to kebab-case.
     * @param inputMapping - The input mapping for the widget factory
     * @param factory - A function which creates a new instance of a widget
     */
    registerFactory<T extends Widget = Widget>(nameOrWidgetClass: string | WidgetConstructor<T>, inputMapping: WidgetXMLInputConfig, factory: XMLWidgetFactory): void;
    /**
     * Register a built-in validator; assigns a string to a validator function,
     * so that the validator function can be referred to via a string instead of
     * via a function.
     *
     * @param key - The validator key - the string that will be used instead of the function
     * @param validator - A function which can throw an error on an invalid value, and transform an input value. Can be chained
     */
    registerValidator(key: string, validator: WidgetAutoXMLConfigValidator): void;
    /**
     * Register a attribute value deserializer; assigns a deserializer function
     * to a single character prefix. The value will be passed to the
     * deserializer without the prefix.
     *
     * @param prefix - A single character prefix that decides which deserializer to use. Must be unique
     * @param deserializer - A function that transforms a string without the prefix into any value
     */
    registerAttributeValueDeserializer(prefix: string, deserializer: XMLAttributeValueDeserializer): void;
    /**
     * Register a attribute namespace handler; assigns a handler function to a
     * unique namespace. The attribute object will be passed to the handler
     * function.
     *
     * @param namespace - A unique namespace. When this namespace is found in an attribute, instead of ignoring the attribute, the attribute will be passed to the handler
     * @param handler - A function that provides custom functionality when an attribute with the wanted namespace is used
     */
    registerAttributeNamespaceHandler(namespace: string, handler: XMLAttributeNamespaceHandler): void;
    /**
     * Register an element deserializer function; elements with the wanted name
     * will be treated as parameters serialized as an element instead of an
     * attribute.
     *
     * @param nodeName - A unique node name. Widgets will not be able to be registered with this name
     * @param parameterMode - The parameter mode to treat the value as
     * @param deserializer - The deserializer function that turns the XML element into a value
     */
    registerElementDeserializer(nodeName: string, parameterMode: string, deserializer: XMLElementDeserializer): void;
    /**
     * Registers a parameter mode; defines whether the parameter mode can be a
     * list, can be optional and how it's validated.
     *
     * @param parameterMode - A string that is used as a key for this parameter mode
     * @param validator - A function that validates whether a deserialized value is valid for this mode
     * @param canBeList - If true, when a parameter with this mode has a config with a `list` field set to true, the parameter will be treated as a list
     * @param canBeOptional - If true, when a parameter with this mode has a config with a `optional` field set to true, the parameter will be optional (no error thrown if undefined)
     */
    registerParameterMode(parameterMode: string, validator: XMLParameterModeValidator, canBeList: boolean, canBeOptional: boolean): void;
    /**
     * Auto-register a factory for a given widget. Instead of passing an input
     * mapping and name, these are instead supplied in the
     * {@link Widget.autoXML} field of the widget class. If it's null, an error
     * is thrown.
     *
     * @param widgetClass - The class to auto-register
     */
    autoRegisterFactory<T extends Widget = Widget>(widgetClass: WidgetConstructor<T> & {
        autoXML: WidgetAutoXML;
    }): void;
    /**
     * Register an argument modifier.
     *
     * @param modifier - A function that modifies an argument list passed to a factory. The function will be added to the end of the modifier list
     */
    registerArgumentModifier(modifier: XMLArgumentModifier): void;
    /**
     * Register a post-initialization hook.
     *
     * @param hook - A function that will be called after a widget instance is created. The instance will be passed to the function, so it can be used to modify the instance post-initialization
     */
    registerPostInitHook(hook: XMLPostInitHook): void;
    /**
     * Parse an XML element which is expected to represent a widget. If the XML
     * element doesn't represent a widget, then an error is thrown; this will
     * happen if no factory is registered to the element name.
     *
     * @param context - The current parser context, shared with all other initializations
     * @param elem - The element to parse
     * @returns Returns the new widget instance
     */
    parseWidgetElem(context: XMLUIParserContext, elem: Element): Widget;
    /**
     * Parse a <ui-tree> element. Expected to contain at least one widget
     * element, and can contain <script> elements. Scripts must finish execution
     * or this will never return.
     *
     * @param uiTreeElem - The <ui-tree> element to parse
     * @param context - The current parser context, shared with all other initializations
     * @returns Returns the new widget instance. All scripts are finished executing when the widget is returned.
     */
    parseUITreeElem(uiTreeElem: Element, context: XMLUIParserContext): Widget;
    /**
     * Parse an XML document which can contain multiple <ui-tree> descendants.
     *
     * @param xmlDoc - The XML document to parse
     * @param config - The configuration object to use for the parser
     * @returns Returns a pair containing, respectively, a Map which maps a UI tree name to a widget, and the parser context after all UI trees are parsed
     */
    parseFromXMLDocument(xmlDoc: XMLDocument, config?: XMLUIParserConfig): [Map<string, Widget>, XMLUIParserContext];
    /**
     * Parse an XML string. {@link BaseXMLUIParser#parseFromXMLDocument} will be
     * called.
     *
     * @param str - A string containing an XML document
     * @param config - The configuration object to use for the parser
     * @returns Returns a pair containing, respectively, a Map which maps a UI tree name to a widget, and the parser context after all UI trees are parsed
     */
    parseFromString(str: string, config?: XMLUIParserConfig): [Map<string, Widget>, XMLUIParserContext];
    /**
     * Parse an XML string from a URL. {@link BaseXMLUIParser#parseFromString}
     * will be called.
     *
     * @param resource - The URL to download the XML from
     * @param config - The configuration object to use for the parser
     * @param requestOptions - Options to use for the HTTP request
     * @returns Returns a pair containing, respectively, a Map which maps a UI tree name to a widget, and the parser context after all UI trees are parsed. Returned asynchronously as a promise
     */
    parseFromURL(resource: RequestInfo | URL, config?: XMLUIParserConfig, requestOptions?: RequestInit): Promise<[Map<string, Widget>, XMLUIParserContext]>;
}