uhtml

The default export of the parser module is a factory function that allows you to inject custom implementations for standard DOM nodes and components. This is useful when working in environments where the standard DOM is not available or when using a custom virtual DOM/ISH implementation.

You can provide custom constructors for Comment, DocumentType, Text, Fragment, Element, and Component, as well as a custom update function to control how nodes are patched during template updates.

import parserFactory from 'uhtml/parser';

// Example of initializing the parser with custom implementations
const parser = parserFactory({
    Element: MyCustomElement,
    Component: MyCustomComponent,
    update: (node, type, path, name, hint) => {
        // Custom update logic
    }
});

// The returned function parses templates into [Node, holes]
const [node, holes] = parser(templateStrings, holesArray, true);

uhtml provides a reactive state management API through signals. It exports core primitives for creating reactive values, deriving state, and handling side effects. These primitives are powered by @webreflection/alien-signals.

• signal(initialValue): Creates a new reactive signal with an initial value.
• computed(fn): Creates a derived signal that automatically updates when its dependencies change.
• effect(fn): Runs a side effect that automatically tracks any signals read during its execution.
• untracked(fn): Runs a function without tracking any signals read inside it.
• batch(fn): Executes a function within a batch, preventing multiple intermediate updates and ensuring all signal changes are processed together at the end of the batch.

import { signal, computed, effect, batch } from './signals.js';

const count = signal(0);
const double = computed(() => count.value * 2);

effect(() => {
  console.log(`Count is: ${count.value}, Double is: ${double.value}`);
});

batch(() => {
  count.value = 1;
  count.value = 2;
});

Use the parser function to transform a template (either a TemplateStringsArray from a tagged template literal or an array of strings) into a traversable JS literal tree and a list of update instructions for the holes.

Parameters:

• template: A TemplateStringsArray or string[] representing the HTML structure. Holes are represented by the NUL character (\x00) in the internal processing.
• holes: An array of values to be interpolated into the template holes.
• xml: A boolean indicating if the parser should operate in XML mode (important for SVG and self-closing tags).

Returns: An array containing [Node, unknown[]]:

1. Node: The root Fragment containing the parsed tree.
2. unknown[]: A list of update records generated by the update function for every hole found in the template.

import createParser from './src/parser/index.js';
const parser = createParser();

// Using a tagged template literal style (simulated via array)
const template = ["<div>Hello, ", "!</div>"];
const holes = ["World"];

const [rootNode, updates] = parser(template, holes, false);

console.log(rootNode);
console.log(updates); // Contains metadata for the "World" hole

The parser is created by calling the default export of src/parser/index.js with an optional configuration object. This factory function returns the actual parsing function. You can provide custom implementations for DOM node types and an update function to customize how template holes (interpolations) are processed.

Available configuration options:

• Comment: Custom Comment class (defaults to DOMComment).
• DocumentType: Custom DocumentType class (defaults to DOMDocumentType).
• Text: Custom Text class (defaults to DOMText).
• Fragment: Custom Fragment class (defaults to DOMFragment).
• Element: Custom Element class (defaults to DOMElement).
• Component: Custom Component class (defaults to DOMComponent).
• update: A function used to generate update metadata for template holes. It receives (node, type, path, name, hint) and should return an unknown value (typically an array describing the update).

import createParser from './src/parser/index.js';

const parser = createParser({
  // Optional: override default DOM implementations
  Element: MyCustomElement,
  update: (node, type, path, name, hint) => [
    { type, path, name, hint }
  ]
});