@visuallyjs/browser-ui 1.0.0

package/types/core/templates/defs.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Resolves the content for some template, via id.
+ * @internal
+ */
+export type TemplateResolver = (id: string) => string;
+export type RecadoValueFormatter = (v: any, fmt: string) => any;
+/**
+ * Constructor options for Recado instance.
+ * @internal
+ */
+export interface RecadoOptions {
+    templateResolver?: TemplateResolver;
+    templates?: Record<string, string>;
+    defaultTemplate?: string;
+    templateMacros?: Record<string, (d: any) => string>;
+    formatter?: RecadoValueFormatter;
+    /**
+     * The default namespace prefix to use for all elements. Defaults to null, meaning the implementation should just use its default. In the BrowserUIRecado class, this means that elements are created as HTML elements, and ordinarily in the BrowserUI package it is necessary to use an `svg:` prefix to get it to create an SVGElement, for instance `<svg:rect .../>`. In some use cases we know, though, that the templates are going to be SVG, like in the shape library. So to make it more user friendly, in those cases we support specifying that elements without a namespace will be automatically considered to be in the `svg` namespace. Users can write shapes like `<rect .../>`
+     */
+    defaultNamespace?: string;
+}
+/**
+ * @internal
+ */
+export declare const ATTRIBUTE_CONTEXT = "context";
+/**
+ * @internal
+ */
+export declare const ATTRIBUTE_LOOKUP = "lookup";
+/**
+ * @internal
+ */
+export declare const ATTRIBUTE_DEFAULT = "default";
+/**
+ * @internal
+ */
+export declare const TYPE_ELEMENT = "element";
+/**
+ * @internal
+ */
+export declare const TYPE_TEXT = "text";
+/**
+ * @internal
+ */
+export declare const TYPE_TMPL = "tmpl";
+/**
+ * @internal
+ */
+export declare const TYPE_EACH = "each";
+/**
+ * @internal
+ */
+export declare const TYPE_IF = "if";
+/**
+ * @internal
+ */
+export declare const TYPE_ROOT = "root";
+/**
+ * @internal
+ */
+export declare const ATTRIBUTE_CLASS = "class";
+/**
+ * @internal
+ */
+export declare const ATTRIBUTE_STYLE = "style";
+/**
+ * @internal
+ */
+export declare const PLACEHOLDER_VALUE = "$value";
+/**
+ * @internal
+ */
+export declare const PLACEHOLDER_KEY = "$key";
+/**
+ * @internal
+ */
+export declare const TYPE_ATTRIBUTE = "attribute";
+/**
+ * @internal
+ */
+export interface FragmentFacade {
+    toString(): string;
+    appendChild(el: TextNodeFacade | ElementFacade | CommentFacade): void;
+    childNodes: ArrayLike<SupportedElement>;
+}
+/**
+ * @internal
+ */
+export interface ElementFacade {
+    childNodes: Array<ElementFacade | TextNodeFacade | CommentFacade>;
+    getAttribute(name: string): string;
+    setAttributeNS(ns: string, name: string, value: string): void;
+    setAttribute(name: string, value: string): void;
+    toString(): string;
+    appendChild(el: TextNodeFacade | ElementFacade | FragmentFacade | CommentFacade): void;
+    removeChild(el: TextNodeFacade | ElementFacade): void;
+    parentElement: ElementFacade;
+    after(el: TextNodeFacade | ElementFacade): void;
+    before(el: TextNodeFacade | ElementFacade | CommentFacade): void;
+    style: Record<string, any>;
+    nodeType: number;
+}
+/**
+ * @internal
+ */
+export interface TextNodeFacade {
+    toString(): string;
+    nodeValue: string;
+    parentElement: ElementFacade;
+    after(el: TextNodeFacade | ElementFacade): void;
+    nodeType: number;
+}
+/**
+ * @internal
+ */
+export interface CommentFacade {
+    before(el: TextNodeFacade | ElementFacade | CommentFacade | FragmentFacade): void;
+    nodeType: number;
+}
+/**
+ * @internal
+ */
+export type SupportedElement = ElementFacade | TextNodeFacade | CommentFacade;

package/types/core/templates/each-entry.d.ts

@@ -0,0 +1,23 @@
+import { ElementEntry } from "./element-entry";
+import { Recado } from "./core";
+import { AttributeParseResult, ParseStack } from "./parser";
+import { TemplateResolver } from "./defs";
+import { UpdateResult, IExecution, IRootExecution, IEachExecution } from "./executions";
+/**
+ * An `r-each` tag.
+ * @internal
+ */
+export declare class EachEntry extends ElementEntry {
+    key: string;
+    type: string;
+    static tag: string;
+    constructor(data: AttributeParseResult, instance: Recado, templateResolver: TemplateResolver, stack: ParseStack, parseIdStack: Array<string>);
+}
+/**
+ * @internal
+ */
+export declare function addEntryToEachExecution(e: IEachExecution, key: string, execution: IExecution): void;
+/**
+ * @internal
+ */
+export declare function addNewExecutionToEachExecution<T>(ie: IEachExecution, execution: IRootExecution, key: string, updateResult: UpdateResult<T>): void;

package/types/core/templates/element-entry.d.ts

@@ -0,0 +1,18 @@
+import { Recado } from "./core";
+import { AttributeParseResult, ParseStack } from "./parser";
+import { AbstractEntry } from './abstract-entry';
+import { TemplateResolver } from "./defs";
+/**
+ * @internal
+ */
+export declare class ElementEntry extends AbstractEntry {
+    protected templateResolver: TemplateResolver;
+    protected stack: ParseStack;
+    protected parseIdStack: Array<string>;
+    static type: string;
+    type: string;
+    namespace: string;
+    atts: Record<string, string>;
+    custom: boolean;
+    constructor(ta: AttributeParseResult, instance: Recado, templateResolver: TemplateResolver, stack: ParseStack, parseIdStack: Array<string>);
+}

package/types/core/templates/elements.d.ts

@@ -0,0 +1,14 @@
+import { AttributeParseResult } from "./parser";
+import { AbstractEntry } from './abstract-entry';
+import { Recado } from "./core";
+import { ElementEntry } from "./element-entry";
+import { TemplateResolver } from "./defs";
+import { Constructable } from "../util";
+/**
+ * @internal
+ */
+export declare const Elements: {
+    construct: (tag: string, ta: AttributeParseResult, instance: Recado, templateResolver: TemplateResolver, stack: Array<AbstractEntry>, parseIdStack: Array<string>) => ElementEntry;
+    register: (name: string, conn: Constructable<ElementEntry>) => void;
+    exists: (tag: string) => boolean;
+};

package/types/core/templates/executions.d.ts

@@ -0,0 +1,100 @@
+import { BindingResult, Recado } from "./core";
+import { AbstractEntry } from './abstract-entry';
+import { CommentFacade, ElementFacade, FragmentFacade, RecadoValueFormatter, SupportedElement, TextNodeFacade } from "./defs";
+import { TextEntry } from './text-entry';
+import { EachEntry } from './each-entry';
+import { CustomTag, MountFunction } from "./custom-tag";
+/**
+ * @internal
+ */
+export interface IExecution {
+    id: string;
+    children: Array<IExecution>;
+    el?: ElementFacade | TextNodeFacade;
+    updaters?: Array<Function>;
+    type: string;
+    entry: AbstractEntry;
+}
+/**
+ * @internal
+ */
+export interface IExecutionWithBindings extends IExecution {
+    bindings: Record<string, BindingResult>;
+}
+/**
+ * @internal
+ */
+export interface IElementExecution extends IExecutionWithBindings {
+    el: ElementFacade;
+    type: "element";
+}
+/**
+ * @internal
+ */
+export interface ITextNodeExecution extends IExecutionWithBindings {
+    el: TextNodeFacade;
+    entry: TextEntry;
+    type: "text";
+}
+/**
+ * @internal
+ */
+export interface IEachExecution extends IExecution {
+    entryMap: Record<string, Array<IExecution>>;
+    type: "each";
+    placeholder: CommentFacade;
+    entry: EachEntry;
+}
+/**
+ * @internal
+ */
+export interface ITmplExecution extends IExecution {
+    placeholder: CommentFacade;
+    type: "tmpl";
+}
+/**
+ * @internal
+ */
+export interface IRootExecution extends IExecutionWithBindings {
+    type: "root";
+    fragment: FragmentFacade;
+    mountings: Array<{
+        mount: MountFunction;
+        el: ElementFacade;
+        parent: ElementFacade;
+        data: Record<string, any>;
+        context: Record<string, any>;
+    }>;
+}
+/**
+ * @internal
+ */
+export declare function setElementBindingResult(e: IElementExecution, name: string, value: string, isProperty: boolean): void;
+/**
+ * @internal
+ */
+export declare function setTextNodeBindingResult(e: ITextNodeExecution, value: string): void;
+/**
+ * @internal
+ */
+export declare function clearExecution(instance: Recado, e: IExecution): Array<SupportedElement>;
+/**
+ * @internal
+ */
+export declare function updateBindings(execution: IExecutionWithBindings, resolveValue: (k: string) => any, expander: (e: string) => any, formatter: RecadoValueFormatter): void;
+/**
+ * @internal
+ */
+export type UpdateResult<T> = {
+    added: Array<{
+        el: SupportedElement;
+    }>;
+    removed: Array<{
+        el: SupportedElement;
+    }>;
+    elements: Array<[T, CustomTag]>;
+};
+/**
+ * @internal
+ */
+export declare function emptyUpdateResult<T>(): UpdateResult<T>;

package/types/core/templates/expressions.d.ts

@@ -0,0 +1,47 @@
+import { RecadoValueFormatter } from "./defs";
+/**
+ * @internal
+ */
+export interface StackEntry {
+    t: string;
+    c: Array<StackEntry>;
+    e?: string;
+    v: any;
+    index?: number;
+}
+/**
+ * @internal
+ */
+export interface ParsedExpression {
+    left: StackEntry;
+    right: StackEntry;
+    comparator?: string;
+}
+/**
+ Split the expression into its terms, nesting groups as necessary. The output of this is an object of the form
+ @internal
+ */
+export declare function parseExpression(expression: string): StackEntry;
+/**
+ * Entry point for parsing expressions.
+ * @param expression
+ * @internal
+ */
+export declare function processExpression(expression: string): ParsedExpression;
+/**
+ * Evaluate a parsed expression. If the parsed expression has a comparator defined, the left and right expressions are
+ * evaluated separately, and then compared according to the comparator. Otherwise, the left expression is evaluated and its
+ * value is returned.
+ * @param expression
+ * @param variableResolver
+ * @internal
+ */
+export declare function evaluateExpression(expression: ParsedExpression, variableResolver: (v: string) => any, expander: (e: string) => any, format: string, formatter: RecadoValueFormatter): any;
+/**
+ * Evaluate a single expression, ie. an expression that is known to not contain a comparator. This is exposed for testing
+ * but is internal.
+ * @param expression
+ * @param variableResolver
+ * @internal
+ */
+export declare function evaluateSingleExpression(expression: Array<StackEntry>, variableResolver: (v: string) => any, expander: (v: string) => any, format: string, formatter: RecadoValueFormatter): any;

package/types/core/templates/fake-dom.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @internal
+ */
+import { CommentFacade, ElementFacade, FragmentFacade, TextNodeFacade } from "./defs";
+export declare class Fakement implements FragmentFacade {
+    childNodes: Array<ElementFacade | TextNodeFacade | CommentFacade>;
+    constructor();
+    removeChild(n: FakeElement): void;
+    appendChild(n: ElementFacade | TextNodeFacade): void;
+    insertAfter(ref: TextNodeFacade | ElementFacade, element: TextNodeFacade | ElementFacade): void;
+    insertBefore(ref: CommentFacade | ElementFacade, element: TextNodeFacade | ElementFacade): void;
+    toString(): string;
+}
+export declare class FakeElement extends Fakement implements ElementFacade {
+    nodeType: number;
+    parentElement: FakeElement;
+    tag: string;
+    atts: Record<string, string>;
+    style: Record<string, any>;
+    constructor(tag: string);
+    getAttribute(name: string): string;
+    setAttributeNS(ns: string, name: string, value: string): void;
+    setAttribute(name: string, value: string): void;
+    toString(): string;
+    after(element: TextNodeFacade | ElementFacade): void;
+    before(element: TextNodeFacade | ElementFacade): void;
+}
+export declare class FakeTextNode implements TextNodeFacade {
+    nodeValue: string;
+    parentElement: FakeElement;
+    constructor(nodeValue: string);
+    toString(): string;
+    after(element: TextNodeFacade | ElementFacade): void;
+    nodeType: number;
+}
+export declare class FakeComment implements CommentFacade {
+    nodeValue: string;
+    parentElement: FakeElement;
+    constructor(nodeValue: string);
+    before(element: TextNodeFacade | ElementFacade): void;
+    nodeType: number;
+}

package/types/core/templates/headless.d.ts

@@ -0,0 +1,15 @@
+import { FakeElement } from "./fake-dom";
+import { Recado } from "./core";
+import { CommentFacade, ElementFacade, FragmentFacade, TextNodeFacade } from "./defs";
+/**
+ * @internal
+ */
+export declare class HeadlessRecado extends Recado {
+    _getDefaultTemplateResolver(): (id: string) => string;
+    ce(tag: string): ElementFacade;
+    cf(): FragmentFacade;
+    ctn(value: string): TextNodeFacade;
+    cc(content: string): CommentFacade;
+    removeElement(e: FakeElement): void;
+    removeTextNode(e: TextNodeFacade): void;
+}

package/types/core/templates/if-entry.d.ts

@@ -0,0 +1,25 @@
+import { AttributeParseResult, ParseStack } from "./parser";
+import { Recado } from "./core";
+import { ElementEntry } from './element-entry';
+import { CommentFacade, RecadoValueFormatter, TemplateResolver } from "./defs";
+import { ParsedExpression } from "./expressions";
+import { IExecution } from "./executions";
+/**
+ * @internal
+ */
+export declare class IfEntry extends ElementEntry {
+    type: string;
+    static tag: string;
+    tag: string;
+    test: string;
+    expression: ParsedExpression;
+    constructor(data: AttributeParseResult, instance: Recado, templateResolver: TemplateResolver, stack: ParseStack, parseIdStack: Array<string>);
+}
+export interface IIfExecution extends IExecution {
+    resolution: boolean;
+    entry: IfEntry;
+    type: "if";
+    placeholder: CommentFacade;
+    defaultNamespace?: string;
+}
+export declare function resolveIfExecution(e: IIfExecution, templateData: Record<string, any>, expander: (e: string) => any, format: string, formatter: RecadoValueFormatter): boolean;

package/types/core/templates/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./defs";
+export * from "./core";
+export * from "./parser";
+export * from "./abstract-entry";
+export * from "./element-entry";
+export * from "./comment-entry";
+export * from "./text-entry";
+export * from "./each-entry";
+export * from "./if-entry";
+export * from "./tmpl-entry";
+export * from "./elements";
+export * from "./custom-tag";
+export * from './headless';
+export * from './expressions';

package/types/core/templates/parser.d.ts

@@ -0,0 +1,84 @@
+import { Recado } from "./core";
+import { AbstractEntry } from './abstract-entry';
+import { ParsedExpression } from "./expressions";
+/**
+ * @internal
+ * @param d
+ * @param attributesRe
+ */
+export declare function parseAttributes(d: string, attributesRe: RegExp): Array<string>;
+/**
+ * @internal
+ * @param a
+ */
+export declare function peek<T>(a: Array<T>): T;
+/**
+ * @internal
+ * @param stack
+ */
+export declare function isLoopPresent(stack: ParseStack): boolean;
+/**
+ * @internal
+ */
+export type AttributeParseResult = {
+    el: string;
+    atts: Record<string, string>;
+    bindings: Record<string, any>;
+};
+/**
+ * eg [ "$\{sourceExpression\}", "sourceExpression" ] - an array with the original source, and then the expression that has been extracted by stripping the delimiters, and then a flag indicating whether or not this expression should only be evaluated the first time and not on update
+ * @internal
+*/
+export type BindingExpression = [string, string, boolean];
+/**
+ * @internal
+ */
+export type Binding = {
+    w: string;
+    expressions: Array<BindingExpression>;
+    id: string;
+};
+/**
+ * add a variable expansion binding.
+ * @param bindingId
+ * @param match
+ * @param entry
+ * @param predicate
+ * @param instance
+ * @internal
+ */
+export declare function _addBinding(bindingId: string, match: string, entry: any, predicate: any, instance: Recado): string;
+/**
+ * Register, and expand a binding for, the given attribute.
+ * @param id
+ * @param value
+ * @param output
+ * @param predicate
+ * @param instance
+ * @internal
+ */
+export declare function _bindOneAtt(id: string, value: string, output: AttributeParseResult, predicate: any, instance: Recado): void;
+/**
+ * @internal
+ * @param el
+ * @param instance
+ */
+export declare function parseAtts(el: string, instance: Recado): AttributeParseResult;
+/**
+ * @internal
+ */
+export type ParseStack = Array<AbstractEntry>;
+/**
+ * A binding that has been compiled into an expression AST.
+ * @internal
+ */
+export interface CompiledBinding {
+    id: string;
+    name: string;
+    expressions: Array<{
+        source: string;
+        expression: ParsedExpression;
+        once: boolean;
+        format: string;
+    }>;
+}

package/types/core/templates/text-entry.d.ts

@@ -0,0 +1,17 @@
+import { Recado } from "./core";
+import { AbstractEntry } from './abstract-entry';
+/**
+ * @internal
+ */
+export type TextEntryOptions = {
+    value: string;
+};
+/**
+ * @internal
+ */
+export declare class TextEntry extends AbstractEntry {
+    type: string;
+    static TEXT_BINDING_NAME: string;
+    value: string;
+    constructor(options: TextEntryOptions, instance: Recado);
+}

package/types/core/templates/tmpl-entry.d.ts

@@ -0,0 +1,13 @@
+import { ElementEntry } from "./element-entry";
+import { AttributeParseResult, ParseStack } from "./parser";
+import { Recado } from "./core";
+/**
+ * @internal
+ */
+export declare class TmplEntry extends ElementEntry {
+    templateId: string;
+    lookup: string;
+    default: string;
+    static tag: string;
+    constructor(ta: AttributeParseResult, instance: Recado, templateResolver: (id: string) => string, stack: ParseStack, parseIdStack: Array<string>);
+}