html.*

import { html } from '@hullo/dom'

A dictionary of functions creating a specification for a HTML DOM element. Pick html.[lower case tag name] to access function that creates a specification for an element of that tag.

Function gets max two arguments:

  1. [optionally] element specification

  2. [optionally] children elements specifications in an array or a stream of such arrays.

Each element specification is an object with few fields

Field

Type

Purpose

attrs

{ [attr:string]: string | Observable<string | undefined> }

Attributes dictionary.

Internally using (get|set|remove)Attribute.

props

{

[prop:string]:

| any

| Observable<any>

}

Properties of an DOM element.

Internally using element[prop] to set a value.

events

{

[event:string]:

| (event:Event) => any

| Observer<Event>

}

Registers a listener for event event. An observer will also receive complete signal upon element removal from DOM.

style

{

[styleProp]:

| string

| Observable<string|undefined>

}

Sets up a style for an element or a subscription of style property values.

ref

(element: HTMLElement) => any

Function is called upon mounting an element to a DOM tree and is provided a reference to that element.

deref

(element: HTMLElement) => any

Function called after the element is removed from the DOM tree. As ref is provided with the element reference.

sync

"immediate" | "self" | "branch"

Should the component updates be confirmed asynchronously using requestAnimationFrame.

  • immediate - no

  • self - yes, but only this element

  • branch - yes, this element and all beneath until specified otherwise

The html.* functions return DOMElement structure that second argument of html.*, svg.* and mount can consist of. Second argument can be composed also from strings which will be responsible of creation Text nodes.

html.strong(
{ attrs: { class: "importante" } },
["strings can be children"]
);

However, for performance reasons, as props application is cheaper than structure reconciliation, in case of node that should have single Text node as a child, textContent is preferred.

html.strong({
attrs: { class: "importante" },
props: { textContent: "strings can be children" }
});

For the same reason it would be beneficial in case of dynamic text nodes mixed with some HTML elements should (if possible) be wrapped in spans with textContent pointed to a stream of these texts.