ran
Português

DOM virtual (vnode)

Um DOM virtual leve ao estilo do Snabbdom. Ele representa sua interface com objetos JavaScript comuns (os VNode), compara uma árvore velha com uma nova e aplica ao DOM real só as diferenças.

  • init() monta o reconciliador e devolve uma função patch. Os módulos que vêm junto (class / props / attrs / style / events) se registram sozinhos.
  • patch(oldVnode, newVnode) monta uma árvore (quando oldVnode é um elemento real do DOM) ou compara duas árvores de vnodes e atualiza o DOM ali mesmo.
  • h(sel, dataOrChildren?, children?) é o auxiliar de hyperscript que constrói os VNode.

Importar

import { init, h, classModule, propsModule, styleModule, eventListenersModule } from 'ranuts/vnode';

Nota: nesta implementação o init() não recebe argumentos: o conjunto de módulos é fixo e se registra por dentro, então não é preciso passar cada *Module para o init. Eles são exportados para consulta e inspeção.

Exemplo

Primeiros passos

import { init, h } from 'ranuts/vnode';

// init() devolve uma função `patch`.
// Os módulos que vêm junto (class, props, attrs, style, events) se registram sozinhos.
const patch = init();

const container = document.getElementById('app');

// Monta uma árvore de vnodes
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// Primeiro desenho: passe um elemento real do DOM como vnode velho para montar dentro dele
patch(container, vnode);

// Depois: monte a árvore atualizada e aplique sobre ela o vnode anterior.
// Ao DOM chegam só as diferenças (texto, estilo, ouvintes).
const newVnode = h('div#app.container', { style: { color: 'green' } }, [
  h('h1', 'Hello again'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Updated'),
]);

patch(vnode, newVnode);
vnode = newVnode; // guarde a última árvore para o próximo patch

Construir nós com h

// só a tag
h('div');

// tag + data
h('div', { class: { active: true } });

// tag + um único filho de texto
h('span', 'hello');

// tag + array de filhos
h('ul', [h('li', 'one'), h('li', 'two')]);

// tag + data + filhos
h('a', { attrs: { href: '/home' } }, 'Home');

// Seletores ao estilo do CSS definem o id e as classes
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// O espaço de nomes do SVG entra sozinho quando o seletor começa com "svg"
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);

API

init()

Cria o reconciliador e devolve uma função patch. Os módulos que vêm junto são registrados por dentro; ele não recebe argumentos.

Retorna

Valor Descrição Tipo
patch Monta árvores de vnodes contra o DOM real, ou as compara (oldVnode: VNode | Element, vnode: VNode) => VNode

patch(oldVnode, vnode)

É o que o init() devolve. Na primeira chamada, passe um Element real do DOM como oldVnode para montar a árvore dentro dele. Nas seguintes, passe o VNode anterior para comparar e atualizar ali mesmo. Devolve o novo VNode, que você guarda como valor «velho» para a chamada seguinte.

Parâmetros

Parâmetro Descrição Tipo
oldVnode O vnode anterior, ou um elemento do DOM na primeira montagem VNode | Element
vnode A nova árvore de vnodes a desenhar VNode

h(sel, dataOrChildren?, children?)

Auxiliar de hyperscript que constrói um VNode. Ele é sobrecarregado:

Assinatura Descrição
h(sel) Elemento a partir de um seletor, e mais nada
h(sel, data) Elemento com VNodeData (o data pode ser null)
h(sel, children) Elemento com filhos: um texto ou número, um VNode, ou um array
h(sel, data, children) Elemento com dados e filhos

Parâmetros

Parâmetro Descrição Tipo
sel Seletor ao estilo do CSS: tag, tag#id, tag.class, ou combinados (div#id.a.b). Com svg… o espaço de nomes do SVG entra sozinho string
data Dados do nó: class / props / attrs / style / ouvintes / key / hook. Pode ser null VNodeData | null
children Um texto ou número (que vira um nó de texto), um único VNode, ou um array deles VNodeChildren

Campos de VNodeData

Campo Descrição Tipo Quem aplica
props Propriedades do DOM atribuídas com elm[key] = value Record<string, any> propsModule
attrs Atributos HTML postos com setAttribute (true e false põem e tiram o atributo) Record<string, string | number | boolean> attributesModule
class Classes condicionais: uma correspondência name → boolean Record<string, boolean> classModule
style Estilos em linha: uma correspondência name → value (chaves --var viram variáveis CSS) Record<string, any> styleModule
on Ouvintes de evento: event → handler (ou um array de manipuladores) Record<string, Function | Function[]> eventListenersModule
key Identidade estável que o algoritmo de comparação usa para casar e reordenar os filhos string | number (o núcleo da comparação)
ns URI do espaço de nomes (posta sozinha nas subárvores SVG) string (o núcleo da comparação)
hook Ganchos de ciclo de vida por vnode (Hooks) Hooks (só como tipo: veja a nota)

Nota: o hook e o tipo Hooks fazem parte da superfície pública de tipos. Esta implementação enxuta move o DOM pelo ciclo de vida dos módulos (create / update / destroy); o laço atual do patch não chama os data.hook de cada vnode.

Módulos

Cada módulo cuida de uma fatia do VNodeData. O init() registra todos eles; além disso, são exportados um a um.

Exportação Cuida de Descrição
classModule data.class Põe e tira classes a partir de uma correspondência name → boolean
propsModule data.props Atribui propriedades do DOM diretamente (elm[key] = value)
attributesModule data.attrs Põe e tira atributos HTML com setAttribute (inclusive xml e xlink)
styleModule data.style Aplica estilos em linha e propriedades personalizadas do CSS
eventListenersModule data.on Prende e solta ouvintes de evento
modules — O objeto de registro padrão, que liga cada nome de módulo ao seu módulo

Exportações de nível mais baixo

Exportação Tipo Descrição
vnode (sel, data, children, text, elm) => VNode Fábrica de VNode de baixo nível que o h usa por dentro. No código da aplicação, prefira o h.
addNS (data, children, sel) => void Aplica o espaço de nomes do SVG a uma subárvore inteira. O h a chama sozinho para seletores svg….
htmlDomApi DOMAPI O adaptador de DOM de navegador padrão que o patch usa por dentro (criar, inserir, remover, nós de texto etc.).
is { array, isStr, primitive, isVnode } Pequenos auxiliares de verificação de tipo usados por todo o interior do vnode.
Chain class Chain Um construtor de DOM imperativo e encadeável (setAttribute, append, setTextContent, …). Nada tem a ver com a comparação de vnodes.
create (tagName, options?) => Chain Fábrica de conveniência que devolve um Chain novo.

Tipos

Tipo Formato e sentido
VNode { sel, data, children, elm, text, key, listener? }: um nó virtual
VNodeData { props?, attrs?, class?, style?, on?, key?, ns?, hook? }: veja os campos acima
VNodes VNode[]
VNodeChildElement VNode | string | number
VNodeChildren VNodeChildElement | VNodeChildElement[]
ArrayOrElement<T> T | T[]
Key string | number
Hooks { pre?, init?, create?, insert?, prepatch?, update?, postpatch?, destroy?, remove?, post? }
DOMAPI Interface que descreve as operações de DOM que o patch usa (veja htmlDomApi)
Fragment Extensão de DocumentFragment usada no trato com fragmentos
Modules Record<string, Record<string, ModuleHook>>: o formato do registro de módulos
ModuleHook Uma única chamada do ciclo de vida de um módulo

Notas

  1. Só navegador. O ranuts/vnode mexe com document e com as APIs do DOM; importe-o em código de navegador, não no Node.
  2. Guarde o último vnode. O patch devolve o novo VNode. Guarde-o e passe-o como oldVnode na atualização seguinte, para que as diferenças sejam calculadas contra a árvore vigente.
  3. Num VNode, text e children se excluem: um nó é ou um nó de texto, ou um elemento com filhos.
  4. Use key nas listas. Ao desenhar listas que mudam, dê aos irmãos valores de key estáveis, para que a comparação possa casar e reordenar os nós em vez de refazê-los.