DNA
Progressive Web Components.
API Reference
Classes
Constants
namespace, customElements, customElement, COMPONENT_SYMBOL, CONSTRUCTED_SYMBOL, connect, disconnect, DOM, render, Fragment, h, html, css, delegateEventListener, undelegateEventListener, dispatchEvent, dispatchAsyncEvent, defineListeners, property, getProperty, getProperties, defineProperties, defineProperty, isComponent, isComponentConstructor, extend, Component, until
Enums
Types
ComponentConstructorInterface, ClassFieldDescriptor, ClassFieldAttributeConverter, ClassFieldPropertyConverter, ClassFieldObserver, ClassFieldValidator, DelegatedEventCallback, DelegatedEventDescriptor, ComponentInterface, IterableNodeList, Template, TemplateItem, HyperNode, TemplateFunction, HyperProperties, TemplateItems, HyperClasses, Context, Observable, Subscription, ClassDescriptor, ClassElement, 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 & {
shim?: boolean;
}, options?: ElementDefinitionOptions): void
Params
Name | Type | Optional | Description |
---|---|---|---|
name | string |
The tag name for the element. | |
constructor | HTMLElement & {
shim?: boolean;
} |
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
customElement
Decorate and define component classes.
Type:
(name: string, options?: ElementDefinitionOptions|undefined): (classOrDescriptor: ComponentConstructorInterface<HTMLElement>|ClassDescriptor): any
constant
COMPONENT_SYMBOL
A symbol which identify components.
Type:
unique Symbol
constant
CONSTRUCTED_SYMBOL
A symbol which identify constructed components (properties can be assigned).
Type:
unique Symbol
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<K extends "object"|"link"|"small"|"sub"|"sup"|"track"|"progress"|"a"|"abbr"|"address"|"applet"|"area"|"article"|"aside"|"audio"|"b"|"base"|"basefont"|"bdi"|"bdo"|"blockquote"|"body"|"br"|"button"|"canvas"|"caption"|"cite"|"code"|"col"|"colgroup"|"data"|"datalist"|"dd"|"del"|"details"|"dfn"|"dialog"|"dir"|"div"|"dl"|"dt"|"em"|"embed"|"fieldset"|"figcaption"|"figure"|"font"|"footer"|"form"|"frame"|"frameset"|"h1"|"h2"|"h3"|"h4"|"h5"|"h6"|"head"|"header"|"hgroup"|"hr"|"html"|"i"|"iframe"|"img"|"input"|"ins"|"kbd"|"label"|"legend"|"li"|"main"|"map"|"mark"|"marquee"|"menu"|"meta"|"meter"|"nav"|"noscript"|"ol"|"optgroup"|"option"|"output"|"p"|"param"|"picture"|"pre"|"q"|"rp"|"rt"|"ruby"|"s"|"samp"|"script"|"section"|"select"|"slot"|"source"|"span"|"strong"|"style"|"summary"|"table"|"tbody"|"td"|"template"|"textarea"|"tfoot"|"th"|"thead"|"time"|"title"|"tr"|"u"|"ul"|"var"|"video"|"wbr">(tagName: K, options?: ElementCreationOptions|undefined): HTMLElementTagNameMap[K]; 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; }
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, slot?: boolean): 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
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): (targetOrClassElement: ComponentInterface<HTMLElement>|ClassElement, propertyKey: string, originalDescriptor?: ClassFieldDescriptor|undefined): any
constant
getProperty
Retrieve property descriptor.
Type:
(constructor: ComponentConstructorInterface<HTMLElement>, propertyKey: string): ClassFieldDescriptor
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: Promise<any>, template: Template): Promise<boolean>
enum
NamespaceURI
A list of namespaceURI bound with their tagName.
Member | Description | Value |
---|---|---|
svg | "http://www.w3.org/2000/svg" |
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; [COMPONENT_SYMBOL]: boolean; [CONSTRUCTED_SYMBOL]: boolean; slotChildNodes: IterableNodeList; adoptedStyleSheets?: CSSStyleSheet[]; constructor: ComponentConstructorInterface<T>; initialize(properties?: { [key: string]: any; }): void; 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
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: HyperProperties; children: TemplateItems; }
type
TemplateFunction
A function that returns a template.
(props: HyperProperties, state: Map<string, any>, update: (): boolean, live: (): boolean, context: Context): Template
type
HyperProperties
The properties of a HyperNode.
{ is?: string; slot?: string; key?: any; xlmns?: NamespaceURI; children?: TemplateItems; class?: HyperClasses; [key: string]: any; }
type
TemplateItems
A list of template items.
TemplateItem[]
type
HyperClasses
Classes dictionary.
string|{ [key: string]: boolean; }
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
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
ClassDescriptor
The class descriptor interface.
{ kind: 'class'; elements: ClassElement[]; finisher?: <T>(constructor: { constructor(): T; }): undefined|{ constructor(): T; }; }
type
ClassElement
Decorator class element descriptor.
type
TemplateFilter
A filter function signature for template items.
(item: Node): boolean
type
AsyncEvent
Event & { respondWith(callback: (): Promise<any>): void; }