DNA

Progressive Web Components.

API Reference

Namespaces

Classes

Interfaces

AnchorHTMLAttributes, AreaHTMLAttributes, AriaAttributes, BaseHTMLAttributes, BlockquoteHTMLAttributes, ButtonHTMLAttributes, CanvasHTMLAttributes, ColHTMLAttributes, ColgroupHTMLAttributes, ComponentConstructor, DataHTMLAttributes, DelHTMLAttributes, DetailsHTMLAttributes, DialogHTMLAttributes, EmbedHTMLAttributes, FieldsetHTMLAttributes, FormHTMLAttributes, HTMLAttributes, HTMLTagNameMap, HtmlHTMLAttributes, IframeHTMLAttributes, ImgHTMLAttributes, InputHTMLAttributes, InsHTMLAttributes, KeygenHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, LinkHTMLAttributes, MapHTMLAttributes, MediaHTMLAttributes, MenuHTMLAttributes, MetaHTMLAttributes, MeterHTMLAttributes, ObjectHTMLAttributes, OlHTMLAttributes, OptgroupHTMLAttributes, OptionHTMLAttributes, OutputHTMLAttributes, ParamHTMLAttributes, ProgressHTMLAttributes, QuoteHTMLAttributes, SVGAttributes, SVGTagNameMap, ScriptHTMLAttributes, SelectHTMLAttributes, SlotHTMLAttributes, SourceHTMLAttributes, StyleHTMLAttributes, TableHTMLAttributes, TdHTMLAttributes, TextareaHTMLAttributes, ThHTMLAttributes, TimeHTMLAttributes, TrackHTMLAttributes, VideoHTMLAttributes

Types

AriaRole, AsyncEvent, AttributesMap, ComponentInstance, Context, DelegatedEventCallback, DelegatedEventDescriptor, FunctionComponent, GlobalNamespace, HTMLAttributeReferrerPolicy, Observable, PropertyDeclaration, PropertyObserver, Template, VAttrs, VComponent, VElement, VFragment, VFunction, VObject, VProperties, VProps, VSlot, VTag

Variables

Component, CustomEvent, DOM, Event, Fragment, HTMLElement, Node, customElements, document, window

Functions

compile, connect, css, customElement, customElementPrototype, defineListeners, defineProperties, defineProperty, delegateEventListener, disconnect, dispatchAsyncEvent, dispatchEvent, extend, getProperties, getProperty, h, html, isComponent, isComponentConstructor, listen, observe, parseDOM, property, render, state, undelegateEventListener, until

Namespace JSX

Class CustomElementRegistry

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

Propertie

Name	Type	Readonly	Description
native	`Property`	✓	Support native registry.
queue	`Property`	✓	Collect "whenDefined" promises.
registry	`Property`	✓	A global registry.
tagNames	`Property`	✓	A map of tag names.

Methods

Function constructor

Create registry instance.

new (): CustomElementRegistry

Returns: CustomElementRegistry

Function define

<T extends CustomElementConstructor>(name: string, constructor: T, options: ElementDefinitionOptions): void

Params

Name	Type	Optional	Description
name	`string`
constructor	`T`
options	`ElementDefinitionOptions`

Returns: void

Function get

<K extends string>(name: K): CustomElementConstructor

Params

Name	Type	Optional	Description
name	`K`

Returns: CustomElementConstructor The definition for the given tag.

Function upgrade

(root: HTMLElement): void

Params

Name	Type	Optional	Description
root	`HTMLElement`

Returns: void

Function whenDefined

<K extends string>(name: K): Promise

Params

Name	Type	Optional	Description
name	`K`

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

Interface AnchorHTMLAttributes

Interface AreaHTMLAttributes

Interface AriaAttributes

Interface BaseHTMLAttributes

Interface BlockquoteHTMLAttributes

Interface ButtonHTMLAttributes

Interface CanvasHTMLAttributes

Interface ColHTMLAttributes

Interface ColgroupHTMLAttributes

Interface ComponentConstructor

Interface DataHTMLAttributes

Interface DelHTMLAttributes

Interface DetailsHTMLAttributes

Interface DialogHTMLAttributes

Interface EmbedHTMLAttributes

Interface FieldsetHTMLAttributes

Interface FormHTMLAttributes

Interface HTMLAttributes

Interface HTMLTagNameMap

Interface HtmlHTMLAttributes

Interface IframeHTMLAttributes

Interface ImgHTMLAttributes

Interface InputHTMLAttributes

Interface InsHTMLAttributes

Interface KeygenHTMLAttributes

Interface LabelHTMLAttributes

Interface LiHTMLAttributes

Interface LinkHTMLAttributes

Interface MapHTMLAttributes

Interface MediaHTMLAttributes

Interface MenuHTMLAttributes

Interface MetaHTMLAttributes

Interface MeterHTMLAttributes

Interface ObjectHTMLAttributes

Interface OlHTMLAttributes

Interface OptgroupHTMLAttributes

Interface OptionHTMLAttributes

Interface OutputHTMLAttributes

Interface ParamHTMLAttributes

Interface ProgressHTMLAttributes

Interface QuoteHTMLAttributes

Interface SVGAttributes

Interface SVGTagNameMap

Interface ScriptHTMLAttributes

Interface SelectHTMLAttributes

Interface SlotHTMLAttributes

Interface SourceHTMLAttributes

Interface StyleHTMLAttributes

Interface TableHTMLAttributes

Interface TdHTMLAttributes

Interface TextareaHTMLAttributes

Interface ThHTMLAttributes

Interface TimeHTMLAttributes

Interface TrackHTMLAttributes

Interface VideoHTMLAttributes

Type AriaRole

alert | alertdialog | application | article | banner | button | cell | checkbox | columnheader | combobox | complementary | contentinfo | definition | dialog | directory | document | feed | figure | form | grid | gridcell | group | heading | img | link | list | listbox | listitem | log | main | marquee | math | menu | menubar | menuitem | menuitemcheckbox | menuitemradio | navigation | none | note | option | presentation | progressbar | radio | radiogroup | region | row | rowgroup | rowheader | scrollbar | search | searchbox | separator | slider | spinbutton | status | switch | tab | table | tablist | tabpanel | term | textbox | timer | toolbar | tooltip | tree | treegrid | treeitem | string & {
}

Type AsyncEvent

Async event interface.

Event & {
  respondWith(callback: () => Promise): void
}

Type AttributesMap

 & HTMLAttributes

Type ComponentInstance<T extends HTMLElement>

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

CustomElement & ComponentMixin

See also

[W3C specification]{@link https://w3c.github.io/webcomponents/spec/custom/}.

Type Context

The node context interface.

{
  Function?: FunctionComponent;
  children: Node[];
  currentIndex?: number;
  end?: Node;
  fragment?: Context;
  host?: string;
  keys?: Map;
  namespace?: string;
  oldKeyed?: Set;
  oldKeys?: Map;
  properties: WeakMap;
  requestUpdate?: UpdateRequest;
  root?: Node;
  start?: Node;
  store?: Store
}

Type DelegatedEventCallback

(event: Event, target?: Node) => unknown

Type DelegatedEventDescriptor

A descriptor for an event delegation.

AddEventListenerOptions & {
  callback: DelegatedEventCallback;
  target?: EventTarget
}

Type FunctionComponent<P>

(props: P & {
  children?: Template[];
  key?: unknown
}, context: Context & {
  requestUpdate: UpdateRequest;
  store: Store
}, requestUpdate: UpdateRequest, isAttached: () => boolean, sameContext: Context) => Template

Type GlobalNamespace

Window & globalThis & {
  _jsdom?: jsdom.JSDOM
}

Type HTMLAttributeReferrerPolicy

 | no-referrer | no-referrer-when-downgrade | origin | origin-when-cross-origin | same-origin | strict-origin | strict-origin-when-cross-origin | unsafe-url

Type Observable<T>

Observable-like minimal interface.

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

Type PropertyDeclaration<TypeConstructorHint extends Constructor>

A state property declaration.

PropertyDescriptor & {
  attribute?: boolean | string;
  defaultValue?: ConvertConstructorTypes;
  event?: true | string;
  get?: ;
  initializer?: Function;
  observe?: PropertyObserver;
  observers?: PropertyObserver[];
  set?: ;
  state?: boolean;
  symbol?: symbol;
  type?: TypeConstructorHint | TypeConstructorHint[];
  update?: boolean;
  fromAttribute(value: null | string): undefined | ConvertConstructorTypes;
  getter(value?: ConvertConstructorTypes): any;
  setter(newValue?: any): ConvertConstructorTypes;
  toAttribute(value: ConvertConstructorTypes): undefined | null | string;
  validate(value: unknown): boolean
}

Type PropertyObserver<TypeHint>

(oldValue: TypeHint | undefined, newValue: TypeHint, propertyKey: string) => void

Type Template

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

Element | Text | Node | VFragment | VFunction | VComponent | VElement | VSlot | VTag | Promise | Observable | string | number | boolean | undefined | null | Template[]

Type VAttrs<T, E>

Get a list of html attributes that can be assigned to the node.

Omit

Type VComponent<T extends CustomElementConstructor>

The interface of a Component constructor used as JSX tag.

{
  [V_SYM]: true;
  children: Template[];
  key?: unknown;
  namespace?: string;
  properties: VProperties;
  type: T
}

Type VElement<T extends Element>

The interface of an HTML node used as JSX tag.

{
  [V_SYM]: true;
  children: Template[];
  key: unknown;
  namespace: string;
  properties: VProperties;
  type: T
}

Type VFragment

The interface of a JSX fragment node.

{
  [V_SYM]: true;
  children: Template[];
  key: unknown;
  properties: {
};
type: Fragment
}

Type VFunction<T extends FunctionComponent>

The interface of a functional component.

{
  [V_SYM]: true;
  children: Template[];
  key: unknown;
  namespace: string;
  properties: VProperties;
  type: T
}

Type VObject

Generic virtual dom object.

VFunction | VComponent | VElement | VSlot | VTag | VFragment

Type VProperties<TagOrFunctionOrProps, Extends extends string | null>

Properties that can be assigned to a node through the render engine.

Type VProps<T>

Get prototype properties that can be assigned to the node.

Omit &

Type VSlot

The interface of slot element.

{
  [V_SYM]: true;
  children: Template[];
  key: unknown;
  properties: VProperties;
  type: slot
}

Type VTag<T extends string>

The interface of a generic JSX tag.

{
  [V_SYM]: true;
  children: Template[];
  key: unknown;
  namespace: string;
  properties: VProperties;
  type: T
}

Variable 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.

ComponentConstructor

Variable CustomEvent

{
  prototype: CustomEvent
}

Variable 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.

{
  createDocumentFragment: () => DocumentFragment;
  createTextNode: (data: string) => Text;
  appendChild<T extends Node>(parent: Node, newChild: T, slot: boolean): T;
  createComment(data: string): Comment;
  createElement<K extends >(qualifiedName: K, options?: ElementCreationOptions): ;
  createElementNS(namespaceURI: null | string, qualifiedName: string): Element;
  createEvent(typeArg: string, eventInitDict: CustomEventInit): CustomEvent;
  getAttribute(element: Element, qualifiedName: string): null | string;
  hasAttribute(element: Element, qualifiedName: string): boolean;
  insertAdjacentElement(parent: Element, position: InsertPosition, insertedElement: Element, slot: boolean): null | Element;
  insertBefore<T extends Node>(parent: Node, newChild: T, refChild: null | Node, slot: boolean): T;
  removeAttribute(element: Element, qualifiedName: string): void;
  removeChild<T extends Node>(parent: Node, oldChild: T, slot: boolean): T;
  replaceChild<T extends Node>(parent: Node, newChild: Node, oldChild: T, slot: boolean): T;
  setAttribute(element: Element, qualifiedName: string, value: string): void
}

Variable Event

{
  AT_TARGET: number;
  BUBBLING_PHASE: number;
  CAPTURING_PHASE: number;
  NONE: number;
  prototype: Event
}

Variable Fragment

A constructor alias used for JSX fragments </>.

Variable HTMLElement

{
  prototype: HTMLElement
}

Variable Node

{
  ATTRIBUTE_NODE: number;
  CDATA_SECTION_NODE: number;
  COMMENT_NODE: number;
  DOCUMENT_FRAGMENT_NODE: number;
  DOCUMENT_NODE: number;
  DOCUMENT_POSITION_CONTAINED_BY: number;
  DOCUMENT_POSITION_CONTAINS: number;
  DOCUMENT_POSITION_DISCONNECTED: number;
  DOCUMENT_POSITION_FOLLOWING: number;
  DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: number;
  DOCUMENT_POSITION_PRECEDING: number;
  DOCUMENT_TYPE_NODE: number;
  ELEMENT_NODE: number;
  ENTITY_NODE: number;
  ENTITY_REFERENCE_NODE: number;
  NOTATION_NODE: number;
  PROCESSING_INSTRUCTION_NODE: number;
  TEXT_NODE: number;
  prototype: Node
}

Variable customElements

The global DNA registry instance.

CustomElementRegistry

Variable document

Document

Variable window

GlobalNamespace

Function compile

(string: string): Template

Params

Name	Type	Optional	Description
string	`string`

Returns: Template The virtual DOM template.

Function connect

(node: Node): void

Params

Name	Type	Optional	Description
node	`Node`

Returns: void

Function css

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

Params

Name	Type	Optional
name	`string`
cssText	`string`
extend	`string`	✓

Returns: string A scoped CSS string.

Function customElement

(name: string, options?: ElementDefinitionOptions): <T extends ComponentConstructor>(classOrDescriptor: ClassDescriptor | T) => any

Params

Name	Type	Optional	Description
name	`string`
options	`ElementDefinitionOptions`	✓

Returns: <T extends ComponentConstructor>(classOrDescriptor: ClassDescriptor | T) => any The decorated component class.

Function customElementPrototype

<T extends ComponentConstructor>(classOrDescriptor: ClassDescriptor | T): any

Params

Name	Type	Optional	Description
classOrDescriptor	`ClassDescriptor \| T`

Returns: any The decorated component class.

Function defineListeners

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin>(prototype: T): void

Params

Name	Type	Optional	Description
prototype	`T`

Returns: void

Function defineProperties

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin>(prototype: T): void

Params

Name	Type	Optional	Description
prototype	`T`

Returns: void

Function defineProperty

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin, P extends string | number | symbol>(prototype: WithProperties, propertyKey: P, declaration: PropertyDeclaration, symbolKey: symbol, isStatic: boolean): PropertyDescriptor

Params

Name	Type	Optional	Description
prototype	`WithProperties`
propertyKey	`P`
declaration	`PropertyDeclaration`
symbolKey	`symbol`
isStatic	`boolean`

Returns: PropertyDescriptor The final descriptor.

Function delegateEventListener

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

Params

Name	Type	Optional
element	`Element`
eventName	`string`
selector	`null \| string`
callback	`DelegatedEventCallback`
options	`AddEventListenerOptions`	✓

Returns: void

Function disconnect

(node: Node): void

Params

Name	Type	Optional	Description
node	`Node`

Returns: void

Function dispatchAsyncEvent

(element: Element, event: string | Event, detail?: any, bubbles: boolean, cancelable: boolean, composed: boolean): Promise

Params

Name	Type	Optional
element	`Element`
event	`string \| Event`
detail	`any`	✓
bubbles	`boolean`
cancelable	`boolean`
composed	`boolean`

Returns: Promise

Function dispatchEvent

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

Params

Name	Type	Optional
element	`Element`
event	`string \| Event`
detail	`any`	✓
bubbles	`boolean`
cancelable	`boolean`
composed	`boolean`

Returns: boolean True if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

Function extend

<T extends HTMLElement>(constructor: Constructor): ComponentConstructor

Params

Name	Type	Optional	Description
constructor	`Constructor`

Returns: ComponentConstructor A proxy that extends the native constructor.

Function getProperties

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin>(prototype: WithProperties): PropertiesOf

Params

Name	Type	Optional	Description
prototype	`WithProperties`

Returns: PropertiesOf A list of property descriptors.

Function getProperty

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin, P extends string | number | symbol>(prototype: T, propertyKey: P, failIfMissing: boolean):

Params

Name	Type	Optional	Description
prototype	`T`
propertyKey	`P`
failIfMissing	`boolean`

Returns: The property declaration.

Function h

(tagOrComponent: Fragment): VFragment

Params

Name	Type	Optional	Description
tagOrComponent	`Fragment`

Returns: VFragment

(tagOrComponent: Fragment, properties: null, children: Template[]): VFragment

Params

Name	Type	Optional	Description
tagOrComponent	`Fragment`
properties	`null`
children	`Template[]`

Returns: VFragment

<T extends FunctionComponent>(tagOrComponent: T, properties?: VProperties | null, children: Template[]): VFunction

Params

Name	Type	Optional
tagOrComponent	`T`
properties	`VProperties \| null`	✓
children	`Template[]`

Returns: VFunction

<T extends CustomElementConstructor>(tagOrComponent: T, properties?: VProperties | null, children: Template[]): VComponent

Params

Name	Type	Optional
tagOrComponent	`T`
properties	`VProperties \| null`	✓
children	`Template[]`

Returns: VComponent

<T extends Element>(tagOrComponent: T, properties?: VProperties | null, children: Template[]): VElement

Params

Name	Type	Optional
tagOrComponent	`T`
properties	`VProperties \| null`	✓
children	`Template[]`

Returns: VElement

(tagOrComponent: slot, properties?: VProperties | null, children: Template[]): VSlot

Params

Name	Type	Optional
tagOrComponent	`slot`
properties	`VProperties \| null`	✓
children	`Template[]`

Returns: VSlot

<T extends string>(tagOrComponent: T, properties?: VProperties | null, children: Template[]): VTag

Params

Name	Type	Optional
tagOrComponent	`T`
properties	`VProperties \| null`	✓
children	`Template[]`

Returns: VTag

Function html

(string: TemplateStringsArray, values: unknown[]): Template

Params

Name	Type	Optional	Description
string	`TemplateStringsArray`
values	`unknown[]`

Returns: Template

(string: string): Template

Params

Name	Type	Optional	Description
string	`string`

Returns: Template

Function isComponent

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin>(node: Node | T): node is T

Params

Name	Type	Optional	Description
node	`Node \| T`

Returns: node is T True if element is a custom element.

Function isComponentConstructor

<T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin, C extends ComponentConstructor>(constructor: Function | C): constructor is C

Params

Name	Type	Optional	Description
constructor	`Function \| C`

Returns: constructor is C True if the constructor is a component class.

Function listen

(eventName: string, options?: AddEventListenerOptions): Function

Params

Name	Type	Optional	Description
eventName	`string`
options	`AddEventListenerOptions`	✓

Returns: Function

(eventName: string, selector: string, options?: AddEventListenerOptions): Function

Params

Name	Type	Optional
eventName	`string`
selector	`string`
options	`AddEventListenerOptions`	✓

Returns: Function

(eventName: string, target: EventTarget, options?: AddEventListenerOptions): Function

Params

Name	Type	Optional
eventName	`string`
target	`EventTarget`
options	`AddEventListenerOptions`	✓

Returns: Function

Function observe

(propertyKey: string): Function

Params

Name	Type	Optional	Description
propertyKey	`string`

Returns: Function The decorator initializer.

Function parseDOM

(string: string): Template

Params

Name	Type	Optional	Description
string	`string`

Returns: Template The virtual DOM template function.

Function property

<TypeConstructorHint extends Constructor>(declaration: PropertyDeclaration): <T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin, P extends string | number | symbol>(targetOrClassElement: T, propertyKey?: P, descriptor?: PropertyDeclaration) => any

Params

Name	Type	Optional	Description
declaration	`PropertyDeclaration`

Returns: <T extends HTMLElement & { is: string; attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void; connectedCallback(): void; disconnectedCallback(): void } & ComponentMixin, P extends string | number | symbol>(targetOrClassElement: T, propertyKey?: P, descriptor?: PropertyDeclaration) => any The decorator initializer.

Function render

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

Params

Name	Type	Optional	Description
input	`Template`
root	`Node`
slot	`boolean`

Returns: void | Node | Node[] The resulting child Nodes.

Function state

<TypeConstructorHint extends Constructor>(declaration: PropertyDeclaration): <T extends HTMLElement & {
  is: string;
  attributeChangedCallback(attrName: string, oldValue: null | string, newValue: null | string): void;
  connectedCallback(): void;
  disconnectedCallback(): void
} & ComponentMixin, P extends string | number | symbol>(targetOrClassElement: T, propertyKey?: P, descriptor?: PropertyDeclaration) => any

Params

Name	Type	Optional	Description
declaration	`PropertyDeclaration`

Function undelegateEventListener

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

Params

Name	Type	Optional	Description
element	`Element`
eventName	`string`
selector	`null \| string`
callback	`DelegatedEventCallback`

Returns: void

Function until

(thenable: Promise, template: Template): Promise

Params

Name	Type	Optional	Description
thenable	`Promise`
template	`Template`

Returns: Promise A promise which resolves the template while the Thenable is in pending status.