ran
Español

DOM virtual (vnode)

Un DOM virtual ligero al estilo de Snabbdom. Representa tu interfaz con objetos JavaScript llanos (los VNode), compara un árbol viejo con uno nuevo y aplica al DOM real solo las diferencias.

  • init() arma el reconciliador y devuelve una función patch. Los módulos que vienen incluidos (class / props / attrs / style / events) se registran solos.
  • patch(oldVnode, newVnode) monta un árbol (cuando oldVnode es un elemento real del DOM) o compara dos árboles de vnodes y actualiza el DOM sobre la marcha.
  • h(sel, dataOrChildren?, children?) es la ayuda de hyperscript que construye los VNode.

Importar

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

Nota: en esta implementación init() no recibe argumentos: el juego de módulos es fijo y se registra por dentro, así que no hace falta pasarle a init cada *Module por separado. Se exportan para consultarlos e inspeccionarlos.

Ejemplo

Primeros pasos

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

// init() devuelve una función `patch`.
// Los módulos incluidos (class, props, attrs, style, events) se registran solos.
const patch = init();

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

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

// Primer dibujado: pasa un elemento real del DOM como vnode viejo para montar dentro de él
patch(container, vnode);

// Más tarde: construye el árbol actualizado y aplica sobre él el vnode anterior.
// Al DOM solo llegan las diferencias (texto, estilo, escuchadores).
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; // guarda el último árbol para el siguiente patch

Construir nodos con h

// solo la etiqueta
h('div');

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

// etiqueta + un único hijo de texto
h('span', 'hello');

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

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

// Los selectores al estilo CSS fijan el id y las clases
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// El espacio de nombres de SVG se aplica solo cuando el selector empieza por "svg"
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);

API

init()

Crea el reconciliador y devuelve una función patch. Los módulos incluidos se registran por dentro; no recibe argumentos.

Devuelve

Valor Descripción Tipo
patch Monta árboles de vnodes contra el DOM real, o los compara (oldVnode: VNode | Element, vnode: VNode) => VNode

patch(oldVnode, vnode)

La devuelve init(). En la primera llamada, pasa un Element real del DOM como oldVnode para montar el árbol dentro de él. En las siguientes, pasa el VNode anterior para comparar y actualizar sobre la marcha. Devuelve el nuevo VNode, que guardas como valor «viejo» para la llamada siguiente.

Parámetros

Parámetro Descripción Tipo
oldVnode El vnode anterior, o un elemento del DOM en el primer montaje VNode | Element
vnode El nuevo árbol de vnodes que se va a dibujar VNode

h(sel, dataOrChildren?, children?)

Ayuda de hyperscript que construye un VNode. Está sobrecargada:

Firma Descripción
h(sel) Elemento a partir de un selector, y nada más
h(sel, data) Elemento con VNodeData (data puede ser null)
h(sel, children) Elemento con hijos: un texto o número, un VNode, o un array
h(sel, data, children) Elemento con datos e hijos

Parámetros

Parámetro Descripción Tipo
sel Selector al estilo CSS: tag, tag#id, tag.class, o combinados (div#id.a.b). Con svg… se añade solo el espacio de nombres de SVG string
data Datos del nodo: class / props / attrs / style / escuchadores / key / hook. Puede ser null VNodeData | null
children Un texto o número (que pasa a ser un nodo de texto), un solo VNode, o un array de ellos VNodeChildren

Campos de VNodeData

Campo Descripción Tipo Lo aplica
props Propiedades del DOM asignadas con elm[key] = value Record<string, any> propsModule
attrs Atributos HTML puestos con setAttribute (true y false ponen y quitan el atributo) Record<string, string | number | boolean> attributesModule
class Clases condicionales: una correspondencia name → boolean Record<string, boolean> classModule
style Estilos en línea: una correspondencia name → value (las claves --var pasan a variables CSS) Record<string, any> styleModule
on Escuchadores de eventos: event → handler (o un array de manejadores) Record<string, Function | Function[]> eventListenersModule
key Identidad estable que usa el algoritmo de comparación para emparejar y reordenar los hijos string | number (el núcleo de la comparación)
ns URI del espacio de nombres (se pone sola en los subárboles SVG) string (el núcleo de la comparación)
hook Ganchos de ciclo de vida por vnode (Hooks) Hooks (solo como tipo: véase la nota)

Nota: hook y el tipo Hooks forman parte de la superficie pública de tipos. Esta implementación recortada mueve el DOM a través del ciclo de vida de los módulos (create / update / destroy); el bucle de patch actual no llama a los data.hook de cada vnode.

Módulos

Cada módulo se ocupa de una porción de VNodeData. init() los registra todos; además se exportan uno a uno.

Exportación Se ocupa de Descripción
classModule data.class Pone y quita clases a partir de una correspondencia name → boolean
propsModule data.props Asigna propiedades del DOM directamente (elm[key] = value)
attributesModule data.attrs Pone y quita atributos HTML con setAttribute (xml y xlink incluidos)
styleModule data.style Aplica estilos en línea y propiedades personalizadas de CSS
eventListenersModule data.on Engancha y desengancha escuchadores de eventos
modules — El objeto de registro por defecto, que asocia cada nombre de módulo con su módulo

Exportaciones de más bajo nivel

Exportación Tipo Descripción
vnode (sel, data, children, text, elm) => VNode Fábrica de VNode de bajo nivel que usa h por dentro. En el código de tu aplicación, mejor h.
addNS (data, children, sel) => void Aplica el espacio de nombres de SVG a todo un subárbol. h la llama sola con los selectores svg….
htmlDomApi DOMAPI El adaptador de DOM de navegador por defecto que patch usa por dentro (crear, insertar, quitar, nodos de texto, etc.).
is { array, isStr, primitive, isVnode } Pequeñas ayudas de comprobación de tipos usadas por todo el interior de vnode.
Chain class Chain Un constructor de DOM imperativo y encadenable (setAttribute, append, setTextContent, …). No tiene nada que ver con la comparación de vnodes.
create (tagName, options?) => Chain Fábrica de conveniencia que devuelve un Chain nuevo.

Tipos

Tipo Forma y significado
VNode { sel, data, children, elm, text, key, listener? }: un nodo virtual
VNodeData { props?, attrs?, class?, style?, on?, key?, ns?, hook? }: véanse los campos de arriba
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 Interfaz que describe las operaciones de DOM que usa patch (véase htmlDomApi)
Fragment Extensión de DocumentFragment para el manejo de fragmentos
Modules Record<string, Record<string, ModuleHook>>: la forma del registro de módulos
ModuleHook Una sola llamada del ciclo de vida de un módulo

Notas

  1. Solo navegador. ranuts/vnode toca document y las API del DOM; impórtalo en código de navegador, no en Node.
  2. Guarda el último vnode. patch devuelve el nuevo VNode. Guárdalo y pásalo como oldVnode en la siguiente actualización, para que las diferencias se calculen contra el árbol vigente.
  3. En un VNode, text y children se excluyen entre sí: un nodo es o bien un nodo de texto, o bien un elemento con hijos.
  4. Usa key en las listas. Al dibujar listas que cambian, dale a los hermanos valores de key estables, para que la comparación pueda emparejar y reordenar nodos en vez de rehacerlos.