DNA

Progressive Web Components.

API Reference

Classes

Constants

namespace, customElements, connect, disconnect, DOM, render, Fragment, h, html, css, delegateEventListener, undelegateEventListener, dispatchEvent, dispatchAsyncEvent, defineListeners, property, getProperty, getProperties, defineProperties, defineProperty, isComponent, isComponentConstructor, extend, Component, until

Enums

NamespaceURI

Types

Template, TemplateItem, HyperNode, ComponentConstructorInterface, ClassFieldDescriptor, ClassFieldAttributeConverter, ClassFieldPropertyConverter, ClassFieldObserver, ClassFieldValidator, DelegatedEventCallback, DelegatedEventDescriptor, ComponentInterface, IterableNodeList, TemplateFunction, Context, TemplateItems, Observable, Subscription, HyperProperties, TemplateFilter, AsyncEvent

class CustomElementRegistry

The CustomElementRegistry interface provides methods for registering custom elements and querying registered elements.

Properties

Name	Type	Readonly	Description
native	`boolean`	✓	Support native registry.
registry	`{ [key: string]: HTMLElement; }`	✓	A global registry.
tagNames	`{ [key: string]: string; }`	✓	A map of tag names.
queue	`{ [key: string]: Array<(value?: any): void>; }`	✓	Collect "whenDefined" promises.

Methods

method get

Get the Custom Element definition for a tag.

(name: string): HTMLElement|undefined

Params

Name	Type	Optional	Description
name	`string`		The name of the tag.

Returns: HTMLElement|undefined The definition for the given tag.

method define

Define a new Custom Element.

(name: string, constructor: HTMLElement, options?: ElementDefinitionOptions): void

Params

Name	Type	Optional	Description
name	`string`		The tag name for the element.
constructor	`HTMLElement`		The Custom Element constructor.
options	`ElementDefinitionOptions`	✓	A set of definition options, like `extends` for native tag extension.

Returns: void

method whenDefined

It returns a Promise that resolves when the named element is defined.

(name: string): Promise<HTMLElement>

Params

Name	Type	Optional	Description
name	`string`		The Custom Element name.

Returns: Promise<HTMLElement> A Promise that resolves when the named element is defined.

method upgrade

It upgrades all custom elements in a subtree even before they are connected to the main document.

(root: HTMLElement): void

Params

Name	Type	Optional	Description
root	`HTMLElement`		A Node instance with descendant elements that are to be upgraded.

Returns: void

constant namespace

Type:

Window & globalThis

constant customElements

The global DNA registry instance.

Type:

CustomElementRegistry

constant connect

Invoke connectedCallback method of a Node (and its descendents). It does nothing if life cycle is disabled.

Type:

(node: Node, force?: boolean): void

constant disconnect

Invoke disconnectedCallback method of a Node (and its descendents). It does nothing if life cycle is disabled.

Type:

(node: Node): void

constant DOM

DOM is a singleton that components uses to access DOM methods. By default, it uses browsers' DOM implementation, but it can be set to use a different one. For example, in a Node context it is possibile to use DNA thanks to the jsdom dom implementation. It also handle element life cycle for custom elements unless otherwise specified.

Type:

{
    createDocumentFragment: (): DocumentFragment;
    createElement(tagName: string, options?: ElementCreationOptions|undefined): Element;
    createElementNS(namespaceURI: string, tagName: string): Element;
    createTextNode: (data: string): Text;
    createComment(data: string): Comment;
    createEvent(typeArg: string, eventInitDict?: CustomEventInit<any>): CustomEvent<any>;
    appendChild<T extends Node>(parent: Node, newChild: T, slot?: boolean): T;
    removeChild<T_1 extends Node>(parent: Node, oldChild: T_1, slot?: boolean): T_1;
    insertBefore<T_2 extends Node>(parent: Node, newChild: T_2, refChild: Node|null, slot?: boolean): T_2;
    replaceChild<T_3 extends Node>(parent: Node, newChild: Node, oldChild: T_3, slot?: boolean): T_3;
    getAttribute(element: Element, qualifiedName: string): string|null;
    hasAttribute(element: Element, qualifiedName: string): boolean;
    setAttribute(element: Element, qualifiedName: string, value: string): void;
    removeAttribute(element: Element, qualifiedName: string): void;
    matches(element: Element, selectorString: string): boolean;
}

constant render

Render a set of Nodes into another, with some checks for Nodes in order to avoid useless changes in the tree and to mantain or update the state of compatible Nodes.

Type:

(input: Template, root?: Node): Node|Node[]|void

constant Fragment

A constructor alias used for JSX fragments </>.

Type:

Symbol

constant h

HyperFunction factory to use as JSX pragma.

Type:

(tagOrComponent: string|HTMLElement|Fragment|TemplateFunction|Node, properties?: HyperProperties|null, children: TemplateItems): HyperNode

constant html

Compile a template string into virtual DOM template.

Type:

(string: string|TemplateStringsArray, values: any[]): Template

constant css

Scope a CSS string, adding a compnent-specific trailing selector to all rules. It also converts :host selectors for cross browser compatibility.

Type:

(name: string, cssText: string, extend?: string|undefined): string

constant delegateEventListener

Delegate an Event listener.

Type:

(element: Element, eventName: string, selector: string|null, callback: DelegatedEventCallback, options?: AddEventListenerOptions|undefined): void

See also

[MDN]https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

constant undelegateEventListener

Remove an Event delegation.

Type:

(element: Element, eventName: string, selector: string|null, callback: DelegatedEventCallback): void

constant dispatchEvent

Dispatch a custom Event.

Type:

(element: Element, event: Event|string, detail?: CustomEventInit<any>|undefined, bubbles?: boolean, cancelable?: boolean, composed?: boolean): boolean

constant dispatchAsyncEvent

Dispatch an async custom Event.

Type:

(element: Element, event: Event|string, detail?: CustomEventInit<any>|undefined, bubbles?: boolean, cancelable?: boolean, composed?: boolean): Promise<any[]>

constant defineListeners

Define component constructor listeners.

Type:

(constructor: ComponentConstructorInterface<HTMLElement>): void

constant property

A decorator for class fields definition.

Type:

(descriptor?: ClassFieldDescriptor): any

constant getProperty

Retrieve property descriptor.

Type:

(constructor: ComponentConstructorInterface<HTMLElement>, propertyKey: string): ClassFieldDescriptor|null

constant getProperties

Retrieve all properties descriptors.

Type:

(constructor: ComponentConstructorInterface<HTMLElement>): {
    [propertyKey: string]: ClassFieldDescriptor;
}

constant defineProperties

Define component constructor properties.

Type:

(constructor: ComponentConstructorInterface<HTMLElement>): void

constant defineProperty

Define an observed property.

Type:

(constructor: ComponentConstructorInterface<HTMLElement>, propertyKey: string, descriptor: ClassFieldDescriptor, symbolKey?: Symbol|undefined, initializer?: Function|undefined): PropertyDescriptor

constant isComponent

Check if a node is a component.

Type:

(node: any): node is ComponentInterface

constant isComponentConstructor

Check if a constructor is a component constructor.

Type:

(constructor: Function): constructor is ComponentConstructorInterface

constant extend

Get a native HTMLElement constructor to extend by its name.

Type:

<T extends {
    constructor(): HTMLElement;
    prototype: HTMLElement;
}>(constructor: T): ComponentConstructorInterface<InstanceType<T>>

constant Component

The DNA base Component constructor, a Custom Element constructor with declarative properties and event delegations, custom template and a complete life cycle implementation. All DNA components must extends this class.

Type:

ComponentConstructorInterface<HTMLElement>

constant until

It renders the template when then provided Thenable is in pending status.

Type:

(thenable: any, template: Template): any

enum NamespaceURI

A list of namespaceURI bound with their tagName.

Member	Description	Value
svg		`"http://www.w3.org/2000/svg"`

type Template

A generic template. Can be a single atomic item or a list of items.

TemplateItem|TemplateItems

type TemplateItem

The atomic template item. It can be a node, a Hyper or Interpolate function or a primitive value.

Element|Text|Node|HyperNode|Promise<any>|Observable<any>|string|number|boolean|undefined|null

type HyperNode

A virtual description of a Node, generate by the h helper and used in the render function.

{
    node?: Node;
    Component?: ComponentConstructorInterface<HTMLElement>;
    Function?: TemplateFunction;
    tag?: string;
    is?: string;
    key?: any;
    isFragment?: boolean;
    isSlot?: boolean;
    namespaceURI?: NamespaceURI;
    properties?: any;
    children: TemplateItems;
}

type ComponentConstructorInterface

The basic DNA Component interface. It's a Custom Element, but with some extra useful method.

{
    observedAttributes: string[];
    properties?: {
        [key: string]: ClassFieldDescriptor|Function|Function[];
    };
    listeners?: {
        [key: string]: DelegatedEventCallback|DelegatedEventDescriptor;
    };
    shim?: boolean;
    constructor(node?: HTMLElement, properties?: {
        [key: string]: any;
    }): ComponentInterface<T>;
    constructor(properties?: {
        [key: string]: any;
    }): ComponentInterface<T>;
    constructor(): ComponentInterface<T>;
    prototype: ComponentInterface<T>;
}

See also

[W3C specification]https://w3c.github.io/webcomponents/spec/custom/.

type ClassFieldDescriptor

A list of properties for an class field description.

PropertyDescriptor & {
    name?: PropertyKey;
    attribute?: true|string;
    defaultValue?: any;
    type?: Function|Function[];
    fromAttribute?: ClassFieldAttributeConverter;
    toAttribute?: ClassFieldPropertyConverter;
    observe?: ClassFieldObserver;
    observers?: ClassFieldObserver[];
    validate?: ClassFieldValidator;
    getter?: (value?: any): any;
    setter?: (newValue?: any): any;
    event?: true|string;
    symbol?: Symbol;
    initializer?: Function;
}

type ClassFieldAttributeConverter

Convert attribute to property value.

(value: string|null): any

type ClassFieldPropertyConverter

Convert property to attribute value.

(value: any): string|null|undefined

type ClassFieldObserver

The observer signature for class fields.

(oldValue: any, newValue: any): any

type ClassFieldValidator

A validation function for the class field.

(value: any): boolean

type DelegatedEventCallback

Describe the signature of a delegated event callback.

(event: Event, target?: Node): any

type DelegatedEventDescriptor

A descriptor for an event delegation.

AddEventListenerOptions & {
    callback: DelegatedEventCallback;
}

type ComponentInterface

T & {
    is: string;
    slotChildNodes: IterableNodeList;
    adoptedStyleSheets?: CSSStyleSheet[];
    connectedCallback(): void;
    disconnectedCallback(): void;
    attributeChangedCallback(attributeName: string, oldValue: null|string, newValue: null|string): void;
    propertyChangedCallback(propertyName: string, oldValue: any, newValue: any): void;
    render(): Template;
    forceUpdate(): void;
    observe(propertyName: string, callback: ClassFieldObserver): void;
    unobserve(propertyName: string, callback: ClassFieldObserver): void;
    dispatchEvent(event: Event): boolean;
    dispatchEvent(event: string, detail?: any, bubbles?: boolean, cancelable?: boolean, composed?: boolean): boolean;
    dispatchAsyncEvent(event: Event): Promise<any[]>;
    dispatchAsyncEvent(event: string, detail?: any, bubbles?: boolean, cancelable?: boolean, composed?: boolean): Promise<any[]>;
    delegateEventListener(event: string, selector: string|null, callback: DelegatedEventCallback): void;
    undelegateEventListener(event?: string, selector?: string|null, callback?: DelegatedEventCallback): void;
    emulateLifeCycle(): void;
}

type IterableNodeList

Node[] & {
    item(index: number): Node|null;
}

type TemplateFunction

A function that returns a template.

(props: {
    children: Template;
    [key: string]: any;
}, state: any, update: (): boolean, live: (): boolean, context: Context): Template

type Context

The node context interface.

{
    isElement?: boolean;
    isText?: boolean;
    tagName?: string;
    is?: string;
    key?: any;
    props: WeakMap<Context, {
        [key: string]: any;
    }>;
    state: Map<string, any>;
    childNodes?: IterableNodeList;
    slotChildNodes?: IterableNodeList;
    first?: Node;
    last?: Node;
    function?: TemplateFunction;
    fragments: Context[];
    parent?: Context;
    root?: Context;
}

type TemplateItems

A list of template items.

TemplateItem[]

type Observable

Observable-like minimal interface.

{
    pipe(operator: (value: T): any): Observable<T>;
    subscribe(nextCallback: (value: T): any, errorCallback: (error: Error): any, completeCallback: (): any): Subscription;
}

type Subscription

Subscription-like minimal interface.

{
    unsubscribe(): void;
}

type HyperProperties

The properties of a HyperNode.

{
    is?: string;
    slot?: string;
    key?: any;
    xlmns?: NamespaceURI;
    children?: TemplateItems;
    [key: string]: any;
}

type TemplateFilter

A filter function signature for template items.

(item: Node): boolean

type AsyncEvent

Event & {
    respondWith(callback: (): Promise<any>): void;
}