The imperative escape
Some views are not worth describing declaratively. A body of text that has to be re-marked on every keystroke, a canvas, a widget somebody else wrote, a measurement that only the live element can answer — for these, the shortest correct program is imperative, and a framework that will not let you write it makes you write a worse one instead.
So this page is two halves: we give you the element, and here is a real imperative hot spot, done almost vanilla.
We give you the element
exoNodeDom(child) opens the lifecycle object behind a built child, and
.node is the element (packages/dom/src/dom/exoNodeDom.ts:10-15):
import { wireExoNode } from '@exodra/core';
import { exoNodeDom, exoOnTeardown } from '@exodra/dom';
const panel = c.createExoNode(Details);
wireExoNode(panel);
const element = exoNodeDom(panel).node; // the real Element, right now
exoOnTeardown(exoNodeDom(panel), () => socket.close()); // run this when it leaves
exoOnTeardown(child, off) pushes a teardown onto the child's own disposers
(packages/dom/src/dom/exoTeardownScope.ts:30-38); the child's default unmount
runs them. Assigning exoNodeDom(child).unmount = NOTHING is the other direction
— it is how a child says "keep my subscriptions, I am coming back", and it is
what the toggle-axis numbers on
the previous page
measure.
What the two hooks guarantee
onUnmountruns while the element is still attached.dropExoChildcallschild.unmount()first and removes the node afterwards (packages/dom/src/dom/dropExoChild.ts:12-17), andclearOwnedExoChildListcalls every one of them with the whole child list still in the document. A widget that has to tear itself down against a live tree can.onMountruns after the element has been put in its parent. The child list'sinsertcalls it after itsappendChild/insertBefore(packages/dom/src/dom/factories/createExoChildList.ts:53-67);attachis the one placement that skips it (createExoChildList.ts:160-171).- Both fire again on every re-entry and re-exit. A child that leaves a list and comes back is moved, not rebuilt, so its hooks run again.
The trap: the first onMount is not in the document
onMount promises a parent, not a connection. mountExoInstance clones the
prototype, arms the machine on it — which is when its children ports are filled and its
children are inserted and mounted — and inserts the whole clone into the page
afterwards:
// packages/dom/src/dom/mountExoInstance.ts:23-47, cut to the four lines that matter
const root = schema.acquireNode(schema);
createExoNodeRecord(schema, root, machine, ownerChild, record, context, params);
if (before === null) parent.appendChild(root);
else parent.insertBefore(root, before);
So on a first render a child's onMount fires inside a clone that nobody has
appended yet: element.parentNode is set and element.isConnected is false.
Put the same child back later, into a page that is already on screen, and the
same hook reports true. This is visible on the escape-hatches example page,
whose first log line reads in the document: false
(packages/examples/escape-hatches/README.md).
A hook that measures a box, focuses something, or hands the element to a library
that reads layout has to check isConnected rather than assume it. There is no
"connected" hook today.
The backend split
A wiring function that reaches for an element is a client-side wiring function. This is not a style rule; it is a throw.
The same machine runs on @exodra/string, where a TExoNode is a string of
markup. A node c.createExoNode makes there is not a DOM child, so exoNodeDom
refuses with "this node was not made by c.createExoNode(...)" — during the server render, before the
browser is anywhere near it. The type system says so first: a machine built with
createExoMachine<TExoDomNode> is not one ExoStrBackend.render accepts, and the
case that pins the runtime half casts past that on purpose
(packages/conformance/src/tests/an-element-wire-is-client-only.test.ts).
Two consequences:
- The declarative surface is the portable one —
attr,text,on,one,list,createExoNodewithwireExoNode, the port methods (appendChild,insertChild,moveChild,removeChild), and a reconciler fromcreateExoChildrenReconcilerover them (Children).exoNodeDomandexoForeignNodeare@exodra/dom's doors to a DOM node, and importing one pins the module that calls it to the browser —exoForeignNodetakes anElementin its signature (packages/dom/src/foreign/exoForeignNode.ts:21-25). - The portable way in is
c.foreign(t), a pack every backend composes (EXO_DOM_FOREIGN_VOCABULARY,EXO_STR_FOREIGN_VOCABULARY,EXO_TERM_FOREIGN_VOCABULARY).tcarries one half per backend —createDom,createStr,createTerm— and each backend calls its own, so the element is only ever touched by the browser half.exoBackendCompatible(BACKENDS, 'foreign', t)checks at compile time thatthas a half for every backend the application lists, and that every listed backend composed the door. There is still no capability query: nothing in a machine asks which backend it is on.
Everything below is therefore client-rendered. It is not written as something that server-renders, because it does not.
Search highlighting in rich text
The view: a long body of text, and a search box. Every hit of the query has to be
wrapped in a <mark>, live, as the user types.
Why a schema tree is the wrong shape here. The number of nodes is a function of the query, not of the data — one keystroke can take the text from one node to two hundred and back to one. Expressing that declaratively means turning a string into an array of segments on every keystroke, diffing that array, building a child per segment and reconciling them, to produce a result the browser can also get from clearing one element and appending text nodes into it. The reconciler would be doing careful work to avoid work that is cheaper than the care.
The right shape is the imperative one: one element you own, repainted.
The code
import { EXO_PORT_CHILDREN, EXO_PORT_EVENT, createExoMachine, createExoSchema, exoPorts, withExoHandlers } from '@exodra/core';
import type { TExoDomNode } from '@exodra/dom';
import { ExoDomBackend, exoForeignNode, withExoCompiler } from '@exodra/dom';
/** What the user typed: a tiny store of the application's own, nothing Exodra about it. */
function createTextStore(initial: string) {
let value = initial;
const listeners = new Set<() => void>();
return {
getValue: () => value,
setValue(next: string): void {
value = next;
listeners.forEach((listener) => listener());
},
onChange(listener: () => void): () => void {
listeners.add(listener);
return () => listeners.delete(listener);
},
};
}
const query = createTextStore('');
const ARTICLE =
'Exodra compiles a component once, at module load, into a prototype element ' +
'and a setter per port. A render is a clone plus one indirect call per port. …';
/**
* PAINT THE TEXT INTO A BOX, WITH EVERY HIT IN A <mark>.
*
* Not one line of this is Exodra — createElement, textContent, append. It is the
* program you would write if there were no framework on the page, and that is
* the point: the framework's job here is to place this box and tell it when it
* comes and goes, not to have an opinion about how the text is marked.
*/
function paintHighlights(box: Element, text: string, needle: string): void {
box.textContent = '';
if (needle === '') {
box.append(text);
return;
}
const hay = text.toLowerCase();
const q = needle.toLowerCase();
let at = 0;
for (;;) {
const hit = hay.indexOf(q, at);
if (hit === -1) break;
if (hit > at) box.append(text.slice(at, hit));
const mark = document.createElement('mark');
mark.textContent = text.slice(hit, hit + q.length);
box.append(mark);
at = hit + q.length;
}
if (at < text.length) box.append(text.slice(at));
}
/** The hot spot, as a child Exodra can place, move and dispose. */
function highlightedText(c: TExoDomNode, text: string) {
const box = document.createElement('div');
box.className = 'rich-text';
let off: (() => void) | null = null;
return exoForeignNode(c, box, {
// SUBSCRIBE HERE, NOT AT CREATION, and see the open questions below for
// why this is not the same as `exoOnTeardown`: `onMount` fires again every time
// this child re-enters, and `onUnmount` every time it leaves.
onMount() {
paintHighlights(box, text, query.getValue());
off = query.onChange(() => paintHighlights(box, text, query.getValue()));
},
// Runs while the element is STILL ATTACHED (drop-child.ts:34-39).
onUnmount() {
if (off !== null) {
off();
off = null;
}
},
});
}
const ReaderPorts = exoPorts({ field: EXO_PORT_EVENT, body: EXO_PORT_CHILDREN });
const readerSchema = createExoSchema(ReaderPorts, (b) => {
b.el('div', { class: 'reader' }, (div) => {
div.el('input', { class: 'reader-search', type: 'search' }, (input) => {
input.eventPort(ReaderPorts.field, 'input');
});
div.el('div', { class: 'reader-body' }, (host) => {
host.childrenPort(ReaderPorts.body);
});
});
});
const readerBaseMachine = createExoMachine(readerSchema, {
createInitialState: (c: TExoDomNode) => {
// ONE CHILD THAT NEVER CHANGES, built by the CALLER and placed through the
// port's own `appendChild` — there is no order to reconcile.
c.appendChild(ReaderPorts.body, highlightedText(c, ARTICLE));
},
});
const readerMachine = withExoHandlers(readerBaseMachine, (on) => {
on(ReaderPorts.field, (c, event) => {
query.setValue((event.currentTarget as HTMLInputElement).value);
});
});
const backend = withExoCompiler(new ExoDomBackend());
backend.render(readerMachine, document.getElementById('root') as Element);
This matches the idiom in packages/examples/escape-hatches/index.html, which
does the same thing for a canvas widget: a container the widget owns, an onMount
that starts it, an onUnmount that stops it, and a children port as the door —
c.appendChild(port, node) here, a reconciler from createExoChildrenReconciler there.
Where the boundary sits
- The box is the boundary, and it never moves. Hand in an element and render
inside it. Removal and placement both climb
parentNode, so a wrapper put around the box travels with it, but an element moved out of the parent is beyond the climb — it isexoForeignNode's one rule for the caller, stated in its own header (packages/dom/src/foreign/exoForeignNode.ts:14-19). Never let the imperative code move or replace the element you handed over. - The search input is ordinary Exodra. It has a port, its handler is a normal machine handler, and it writes into a plain store. Only the repaint is imperative.
- The query store is the seam. The foreign node subscribes to it and the input's handler writes it; neither knows anything about the other.
What you give up in that port
- Server rendering, unless you hand the server its own half.
c.foreign(t)— a pack, composed on each backend — callst.createDom(c)on the DOM backend andt.createStr()on the server (packages/string/src/foreign/constants/EXO_STR_FOREIGN_VOCABULARY.ts:7-9), so onetcarrying both serves both, andexoBackendCompatible(BACKENDS, 'foreign', t)refuses at compile time atthat misses a backend the application lists;exoForeignMarkup(markup)builds the server half, and it does not escape — the caller owns that string. - Nothing is adopted for the foreign node itself. While hydrating,
exoForeignNodetakes the server's row for that position off the adoption cursor and removes it, and builds a fresh element in its place; the rows around it are adopted as usual (packages/conformance/src/tests/a-foreign-node-in-a-hydrated-list.test.ts).exoForeignNodecalled directly, not throughc.foreign, takes its row the same way. - Ports and bindings inside it. A foreign node has no schema, so
c.attr,c.textandc.onhave nothing to address (packages/dom/src/foreign/exoForeignNode.ts). The two hooks are the whole interface. - Contexts. A foreign node is not a wiring, so it neither provides nor injects. A machine that wants the foreign renderer to see a context value injects it in its initial state and hands it over as data.
Open questions
This scheme is not finished, and these are the places where writing the page ran into the API rather than around it. They are stated as questions because none of them has been decided.
1. How should a machine ask which backend it is on? Today it cannot, and the consequence is that a component with one imperative hot spot cannot be server-rendered at all — it throws during SSR. Three shapes have been named and none chosen:
- A capability test (
c.isDom, or a kind tag on the connector). Cheapest to add; it also puts a branch into wiring functions and invitesifladders that each backend has to keep true. - A second, client-only initial state on the component. Keeps every machine honest about its backend and makes the split visible at the component boundary; it is a new member on the component value and a second thing hydration has to reason about.
- A backend-tagged escape that no-ops on the server —
exoForeignNodereturning an empty string on@exodra/string. Least disruptive to write against; it also makes a page that silently renders a hole on the server look like a page that worked.
2. Which channel ends an imperative subscription — the hook or exoOnTeardown? Both
exist and they have different lifetimes. exoOnTeardown pushes onto disposers, and
the shared default unmount — disposeExoChildSelf — runs them and then
clears the array
(packages/dom/src/dom/factories/createExoDomChildFactory.ts:22-36), so an exoOnTeardown teardown is
one-shot: a child that leaves and re-enters has none. The onMount/onUnmount pair
fires on every entry and exit, which is why the example above subscribes in
onMount. Nothing in the API says which to reach for, and the wrong choice is
silent — a hot spot that stops updating after its first round trip through a
list.
3. Is the child list the right and only door? createExoChildrenReconciler takes a
build function in place of a machine and places whatever it returns
(packages/list-reconcile/src/createExoChildrenReconciler.ts), so a foreign node travels
through it only as an item of an order of nodes, with (c, node) => node as the function.
Underneath is the imperative door the example above uses directly — the port
methods, c.appendChild(port, node) and its siblings, over the same child list a
reconciler drives
(packages/dom/src/dom/constants/EXO_DOM_CHILD_LIST_VOCABULARY.ts). An imperative hot spot
inside a reconciled row of data therefore means that row's own children are a second,
node-valued order. Whether the reconciler should accept a "this one is already built"
entry beside data items is open.
4. Should a foreign node be able to declare what it depends on? In the example
the box reaches query itself, from module scope. The machine cannot see that
dependency, so nothing in the component describes what makes this subtree change — which is exactly the information the rest of the framework is built to make explicit. A port that carried a source into a hook, without giving the foreign node a schema, would close that; it does not exist and it is not obviously worth its weight.
5. Is there a "connected" hook? No. onMount guarantees a parent, and the first
one is not in the document. Anything that measures has to test isConnected and
decide for itself what to do when it is false.