ran
English

Virtual DOM (vnode)

A lightweight, Snabbdom-style virtual DOM. It represents your UI as plain JavaScript objects (VNodes), diffs an old tree against a new one, and applies only the differences to the real DOM.

  • init() builds the reconciler and returns a patch function. The bundled modules (class / props / attrs / style / events) are registered automatically.
  • patch(oldVnode, newVnode) mounts a tree (when oldVnode is a real DOM element) or diffs two vnode trees and updates the DOM in place.
  • h(sel, dataOrChildren?, children?) is the hyperscript helper that builds VNodes.

Import

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

Note: in this implementation init() takes no arguments: the module set is fixed and registered internally, so the individual *Module exports do not need to be passed to init. They are exported for reference and inspection.

Example

Quick start

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

// init() returns a `patch` function.
// The bundled modules (class, props, attrs, style, events) are registered automatically.
const patch = init();

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

// Build a vnode tree
let vnode = h('div#app.container', { style: { color: 'red' } }, [
  h('h1', 'Hello vnode'),
  h('button', { on: { click: () => console.log('clicked') } }, 'Click me'),
]);

// Initial render: pass a real DOM element as the old vnode to mount into it
patch(container, vnode);

// Later: build an updated tree and patch the previous vnode into it.
// Only the differences (text, style, listeners) are applied to the DOM.
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; // keep the latest tree for the next patch

Building nodes with h

// tag only
h('div');

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

// tag + a single text child
h('span', 'hello');

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

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

// CSS-style selectors set id and classes
h('div#main.card.large', 'content'); // <div id="main" class="card large">content</div>

// SVG namespaces are applied automatically when the selector starts with "svg"
h('svg', { attrs: { width: 100, height: 100 } }, [h('circle', { attrs: { cx: 50, cy: 50, r: 40 } })]);

API

init()

Creates the reconciler and returns a patch function. The bundled modules are registered internally; it takes no arguments.

Return

Value Description Type
patch Mounts / diffs vnode trees against the real DOM (oldVnode: VNode | Element, vnode: VNode) => VNode

patch(oldVnode, vnode)

Returned by init(). On the first call, pass a real DOM Element as oldVnode to mount the tree into it. On later calls, pass the previous VNode to diff-and-update in place. Returns the new VNode, which you keep as the "old" value for the next call.

Parameters

Parameter Description Type
oldVnode The previous vnode, or a DOM element on first mount VNode | Element
vnode The new vnode tree to render VNode

h(sel, dataOrChildren?, children?)

Hyperscript helper that builds a VNode. It is overloaded:

Signature Description
h(sel) Element from a selector only
h(sel, data) Element with VNodeData (data may be null)
h(sel, children) Element with children: a text/number, a VNode, or an array
h(sel, data, children) Element with data and children

Parameters

Parameter Description Type
sel CSS-style selector: tag, tag#id, tag.class, combined (div#id.a.b). svg… auto-adds the SVG namespace string
data Node data: class / props / attrs / style / listeners / key / hook. May be null VNodeData | null
children A text or number (becomes a text node), a single VNode, or an array of them VNodeChildren

VNodeData fields

Field Description Type Applied by
props DOM properties set via elm[key] = value Record<string, any> propsModule
attrs HTML attributes set via setAttribute (true/false toggle the attr) Record<string, string | number | boolean> attributesModule
class Conditional classes: a name → boolean map Record<string, boolean> classModule
style Inline styles: a name → value map (--var keys use CSS variables) Record<string, any> styleModule
on Event listeners: event → handler (or an array of handlers) Record<string, Function | Function[]> eventListenersModule
key Stable identity used by the diff algorithm to match/reorder children string | number (diff core)
ns Namespace URI (set automatically for SVG subtrees) string (diff core)
hook Per-vnode lifecycle hooks (Hooks) Hooks (type surface: see note)

Note: hook and the Hooks type are part of the public type surface. This trimmed implementation drives the DOM through the module lifecycle (create / update / destroy); per-vnode data.hook callbacks are not invoked by the current patch loop.

Modules

Each module handles one slice of VNodeData. init() registers all of them; they are also exported individually.

Export Handles Description
classModule data.class Adds/removes classes from a name → boolean map
propsModule data.props Assigns DOM properties directly (elm[key] = value)
attributesModule data.attrs Sets/removes HTML attributes via setAttribute (incl. xml/xlink)
styleModule data.style Sets inline styles and CSS custom properties
eventListenersModule data.on Attaches/detaches event listeners
modules — The default registry object mapping each module name to its module

Lower-level exports

Export Type Description
vnode (sel, data, children, text, elm) => VNode Low-level VNode factory used internally by h. Prefer h in application code.
addNS (data, children, sel) => void Recursively applies the SVG namespace to a subtree. Called automatically by h for svg… selectors.
htmlDomApi DOMAPI The default browser DOM adapter used internally by patch (create/insert/remove/text nodes, etc.).
is { array, isStr, primitive, isVnode } Small type-guard helpers used across the vnode internals.
Chain class Chain A chainable imperative DOM builder (setAttribute, append, setTextContent, …). Independent of the vnode diff.
create (tagName, options?) => Chain Convenience factory returning a new Chain.

Types

Type Shape / meaning
VNode { sel, data, children, elm, text, key, listener? }: a virtual node
VNodeData { props?, attrs?, class?, style?, on?, key?, ns?, hook? }: see fields above
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 describing the DOM operations patch uses (see htmlDomApi)
Fragment DocumentFragment extension used for fragment handling
Modules Record<string, Record<string, ModuleHook>>: the module registry shape
ModuleHook A single module lifecycle callback

Notes

  1. Browser only. ranuts/vnode touches document and DOM APIs; import it in browser code, not in Node.
  2. Keep the last vnode. patch returns the new VNode. Store it and pass it as oldVnode on the next update so diffs are computed against the current tree.
  3. text and children are mutually exclusive on a VNode: a node is either a text node or an element with children.
  4. Use key for lists. When rendering dynamic lists, give siblings stable key values so the diff can match and reorder nodes instead of recreating them.