@govela/runtime 0.4.7 → 0.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govela/runtime",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Runtime of components compiled by the Vela compiler. Generated from runtime/; do not edit.",
   "license": "MIT",
   "repository": {

package/runtime-blocks.js

@@ -3,7 +3,8 @@
  *
  * Structural template behaviour lives here once instead of being generated
  * into every component: compiled fragments build DOM through a cursor, and
- * blocks ($$if, $$each, $$key, $$await, $$component, $$slot, $$client) own
+ * blocks ($$if, $$each, $$key, $$await, $$component, $$dynamic, $$slot,
+ * $$client) own
  * their DOM ranges and child resources.
  *
  * Fragment contract (F-2.x): a fragment is `(cursor, scope) => handle`, where
@@ -12,7 +13,7 @@
  * generated by the compiler and forward `dirty` to their fragments.
  */
 
-import { $$runtimeContract1 } from './runtime.js';
+import { $$runtimeContract1, warn } from './runtime.js';
 void $$runtimeContract1;
 
 // ── Owners ───────────────────────────────────────────────────────────────
@@ -708,6 +709,146 @@ export function $$component(cursor, factory, props, slots, events, changed, scop
   });
 }
 
+// ── $$dynamic ────────────────────────────────────────────────────────────
+// <vela:component :this={…}>: select() returns the component factory to
+// render, or null, undefined or false for nothing. The block owns a range
+// like $$key; the current child is a $$component inside it. The same
+// factory after an update keeps the child and calls set(); another factory
+// destroys the child with its DOM and mounts the next one with a create
+// cursor (B-3.6). Slot content belongs to the parent and moves to the next
+// child (B-3.7).
+//
+// props() returns every prop the template passes; a child gets only the
+// ones its factory declares ($$props, name → bindable). bindings lists the
+// bind: props for the development warning about a child without that
+// $bindable prop; the binding is inert for that child. where is the source
+// position for errors. The range state is "" with a child and "x" without
+// one; hydration compares the factory's $$id with the "d" payload entry the
+// server wrote (S-6.12).
+
+// dynamicValue checks the value of :this: a factory, a lazy value
+// (lazy(), task 071), or null for nothing.
+function dynamicValue(value, where) {
+  if (value === null || value === undefined || value === false) return null;
+  if (typeof value === 'function' || (typeof value === 'object' && value.$$lazy === true)) return value;
+  throw new TypeError(`vela: <vela:component> at ${where}: :this is ${value === '' ? 'an empty string' : typeof value}, not a component`);
+}
+
+// factoryOf is the component of a selected value; null for a lazy value
+// that is not loaded yet.
+function factoryOf(value) {
+  if (!value) return null;
+  if (typeof value === 'function') return value;
+  return value.loaded ? value.component : null;
+}
+
+function dynamicProps(factory, props) {
+  const all = props();
+  const declared = factory.$$props;
+  if (!declared) return all;
+  const out = {};
+  for (const name of Object.keys(all)) {
+    if (name.startsWith('$$onChange_')) {
+      if (declared[name.slice(11)] === 1) out[name] = all[name];
+    } else if (Object.prototype.hasOwnProperty.call(declared, name)) {
+      out[name] = all[name];
+    }
+  }
+  return out;
+}
+
+function warnBindings(factory, bindings, where) {
+  const declared = factory.$$props;
+  if (!bindings || !declared) return;
+  for (const name of bindings) {
+    if (declared[name] !== 1) {
+      warn(`<vela:component> at ${where}: bind:${name} has no effect on ${factory.$$id || factory.name}, which does not declare export let ${name} = $bindable(…)`);
+    }
+  }
+}
+
+export function $$dynamic(cursor, select, props, slots, events, bindings, changed, scope, where) {
+  let anchor;
+  // selected is the value of :this, the identity compared after updates; a
+  // lazy value keeps its identity while it loads.
+  let selected = dynamicValue(select(), where);
+  let current = null;
+  const fragmentFor = (component) => {
+    warnBindings(component, bindings, where);
+    return (inner) => {
+      const child = inner.block($$component, component, () => dynamicProps(component, props), slots, events, null, scope);
+      return { p: (dirty) => child.p(dirty) };
+    };
+  };
+  // show mounts the selected component, or for a lazy value that is not
+  // loaded yet starts the load and mounts when it arrives, unless :this
+  // changed or the block was destroyed meanwhile (B-3.5).
+  const show = () => {
+    const factory = factoryOf(selected);
+    if (factory) {
+      current = mountFragment(fragmentFor(factory), undefined, anchor);
+      return;
+    }
+    if (!selected) return;
+    const lazyValue = selected;
+    lazyValue.load().then(
+      (component) => {
+        if (block.isDone() || selected !== lazyValue || current) return;
+        current = mountFragment(fragmentFor(component), undefined, anchor);
+      },
+      (error) => {
+        if (block.isDone() || selected !== lazyValue) return;
+        warn(`<vela:component> at ${where}: the lazy component ${lazyValue.id || '(unnamed)'} failed to load: ${error && error.message ? error.message : error}`);
+      },
+    );
+  };
+  const block = {
+    p(dirty) {
+      if (block.isDone()) return;
+      if (changed && !changed(dirty)) return;
+      const next = dynamicValue(select(), where);
+      if (next !== selected) {
+        unmount(current);
+        current = null;
+        selected = next;
+        show();
+        return;
+      }
+      updateMounted(current, dirty, false);
+    },
+    move(before) {
+      if (current) moveRange(current.range, before);
+      before.parentNode.insertBefore(anchor, before);
+    },
+  };
+  if (cursor.hydrating) {
+    const token = cursor.open();
+    const factory = factoryOf(selected);
+    if (selected && !factory) {
+      // The server rendered the component; its module is not here yet.
+      cursor.expect(false, `lazy-not-loaded: <vela:component> renders the lazy component ${selected.id || '(unnamed)'}, which is not loaded; await preloadHydration(container) before hydrate()`);
+    }
+    const id = factory ? factory.$$id || factory.name : null;
+    cursor.expect(token === (factory ? '' : 'x'),
+      factory ? `<vela:component> renders ${id}, the server rendered nothing` : `<vela:component> renders nothing, the server rendered a component`);
+    if (factory) {
+      const server = cursor.entry('d');
+      cursor.expect(server === null || server === id, `<vela:component> renders ${id}, the server rendered ${server}`);
+      current = cursor.mount(fragmentFor(factory));
+    }
+    anchor = cursor.close();
+  } else {
+    anchor = cursor.comment();
+  }
+  registerBlock(cursor, block, anchor, (removeDom) => {
+    if (!current) return;
+    if (removeDom) unmount(current);
+    else current.owner.release();
+  });
+  if (!cursor.hydrating) show();
+  return block;
+}
+
 // ── Slots ────────────────────────────────────────────────────────────────
 // Slots use the component protocol: a slot is a function returning a
 // DocumentFragment with the slot content. The parent

package/runtime-hydrate.js

@@ -14,7 +14,7 @@
  * with one console.error and no value verification.
  */
 
-import { $$isDev } from './runtime.js';
+import { $$isDev, $$lazyById, warn } from './runtime.js';
 import { $$owner, $$setHydration, $$createCursor, $$listen } from './runtime-blocks.js';
 
 export const MISMATCH = 'VELA-HYDRATION-MISMATCH';
@@ -348,26 +348,68 @@ function createSession(entries, options, container) {
   return session;
 }
 
-// hydrate adopts the root range and payload script that a Go renderer
-// wrote into container (A-8.7) and returns the component instance, which
-// then behaves exactly like one created by the factory.
-//
-// options: policy ('repair' | 'fail' | 'off'; production builds use their
-// own policy), onMismatch(report) (X-7.5), slots.
-export function hydrate(Component, container, options = {}) {
-  let script = null;
+// payloadOf returns the payload of the root in container without
+// consuming it, or null.
+function payloadOf(container) {
   for (const node of container.childNodes) {
-    if (node.nodeType === 1 && node.localName === 'script' && node.hasAttribute('data-vela-root')) script = node;
+    if (node.nodeType === 1 && node.localName === 'script' && node.hasAttribute('data-vela-root')) {
+      try {
+        return JSON.parse(node.textContent);
+      } catch {
+        return null;
+      }
+    }
   }
-  if (!script) throw mismatch('the container has no payload script (data-vela-root)');
+  return null;
+}
+
+// preloadHydration loads the lazy components (lazy(), task 071) that the
+// server rendered in container, named by the "d" entries of its payload,
+// so that hydrate() can adopt them synchronously (S-6.14). A lazy module
+// can register further lazy components when it loads; the entries are
+// read again until nothing new loads. A failed load is reported with warn;
+// hydrate() then reports lazy-not-loaded and repairs.
+export async function preloadHydration(container) {
+  const payload = payloadOf(container);
+  if (!payload || !Array.isArray(payload.entries)) return;
+  const ids = [...new Set(payload.entries.filter((entry) => entry[0] === 'd').map((entry) => entry[2]))];
+  const done = new Set();
+  for (let progress = true; progress;) {
+    progress = false;
+    const pending = [];
+    for (const id of ids) {
+      const value = done.has(id) ? null : $$lazyById(id);
+      if (!value) continue;
+      done.add(id);
+      if (value.loaded) continue;
+      progress = true;
+      pending.push(value.load().catch((error) => {
+        warn(`preloadHydration: the lazy component ${id} failed to load: ${error && error.message ? error.message : error}`);
+      }));
+    }
+    await Promise.all(pending);
+  }
+}
+
+// readPayload parses a payload script (S-6.9) and checks its version.
+function readPayload(script) {
   const payload = JSON.parse(script.textContent);
-  if (payload.v !== 3) throw mismatch(`unsupported payload version ${payload.v}`);
-  const props = payload.props || {};
+  if (payload.v !== 4) throw mismatch(`unsupported payload version ${payload.v}`);
+  return payload;
+}
 
-  let first = container.firstChild;
-  while (first && first.nodeType === 3 && first.data.trim() === '') first = first.nextSibling;
-  const pos = { parent: container, next: first, stack: [], owners: [] };
-  const session = createSession(payload.entries || [], options, container);
+// adoptRoot runs a hydration session for Component over the root range
+// that starts at first (whitespace before it is skipped) and ends before
+// script, its payload, under parent: a container element for hydrate(), the
+// range a <vela:component> block mounts into for serverComponent().
+// observed is the node whose attribute writes the session verifies. It
+// returns { instance, failure, session } and the two ways to finish:
+// commit() removes the payload and runs the after-commit callbacks;
+// rollback() releases everything adopted without touching the DOM (X-7.4).
+function adoptRoot(Component, parent, first, script, payload, options, observed, target) {
+  while (first && first !== script && first.nodeType === 3 && first.data.trim() === '') first = first.nextSibling;
+  const pos = { parent, next: first, stack: [], owners: [] };
+  const session = createSession(payload.entries || [], options, observed);
   const owner = $$owner(null);
   pos.owners.push(owner);
   const cursor = hydrateCursor(pos, owner, session);
@@ -378,7 +420,7 @@ export function hydrate(Component, container, options = {}) {
     cursor.open();
     session.cursors.push(cursor);
     try {
-      instance = Component(container, props, options.slots || {});
+      instance = Component(target, payload.props || {}, options.slots || {});
     } finally {
       session.cursors.pop();
     }
@@ -391,25 +433,167 @@ export function hydrate(Component, container, options = {}) {
     $$setHydration(previous);
     if (session.observer) session.observer.disconnect();
   }
-  if (failure) {
-    // Rollback (X-7.4): release everything adopted without touching the
-    // DOM; the server DOM and payload stay for a retry.
-    if (instance && instance.abandon) instance.abandon();
-    for (let i = pos.owners.length - 1; i >= 0; i--) pos.owners[i].release();
-    if (!isMismatch(failure) || session.policy === 'fail') throw failure;
+  return {
+    instance,
+    failure,
+    session,
+    rollback() {
+      if (instance && instance.abandon) instance.abandon();
+      for (let i = pos.owners.length - 1; i >= 0; i--) pos.owners[i].release();
+    },
+    commit() {
+      script.remove();
+      for (const callback of session.after) callback();
+      // The root owner holds what the root cursor adopted; it goes with the
+      // instance (Q-10.2 item 5).
+      const destroy = instance.destroy;
+      instance.destroy = function () {
+        destroy.call(this);
+        owner.release();
+      };
+      // A parent block releases a child without removing its DOM through
+      // abandon (B-3.4), as <vela:component> does when its value changes.
+      const abandon = instance.abandon;
+      if (abandon) {
+        instance.abandon = function () {
+          abandon.call(this);
+          owner.release();
+        };
+      }
+      return instance;
+    },
+  };
+}
+
+// hydrate adopts the root range and payload script that a Go renderer
+// wrote into container (A-8.7) and returns the component instance, which
+// then behaves exactly like one created by the factory.
+//
+// options: policy ('repair' | 'fail' | 'off'; production builds use their
+// own policy), onMismatch(report) (X-7.5), slots.
+export function hydrate(Component, container, options = {}) {
+  let script = null;
+  for (const node of container.childNodes) {
+    if (node.nodeType === 1 && node.localName === 'script' && node.hasAttribute('data-vela-root')) script = node;
+  }
+  if (!script) throw mismatch('the container has no payload script (data-vela-root)');
+  const payload = readPayload(script);
+  const props = payload.props || {};
+  const result = adoptRoot(Component, container, container.firstChild, script, payload, options, container, container);
+  if (result.failure) {
+    result.rollback();
+    if (!isMismatch(result.failure) || result.session.policy === 'fail') throw result.failure;
     // A mismatch at the root range remounts the root (X-7.3).
-    session.report(failure);
+    result.session.report(result.failure);
     while (container.firstChild) container.firstChild.remove();
     return Component(container, props, options.slots || {});
   }
-  script.remove();
-  for (const callback of session.after) callback();
-  // The root owner holds what the root cursor adopted; it goes with the
-  // instance (Q-10.2 item 5).
-  const destroy = instance.destroy;
-  instance.destroy = function () {
-    destroy.call(this);
-    owner.release();
-  };
-  return instance;
+  return result.commit();
+}
+
+// ── Server-rendered fragments (task 072) ─────────────────────────────────
+// serverComponent and staticHTML turn HTML that arrives after the page
+// loaded into component values for <vela:component> (§8.3). The HTML is
+// parsed with a <template>, so its scripts never run; the payload script is
+// read as JSON only. HTML from the server is trusted like the document:
+// never pass HTML from another origin.
+
+function parseHTML(html) {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template.content;
+}
+
+// The target of a component factory: a comment anchor the nodes go before
+// (how <vela:component> mounts a child), or an element they are appended to.
+function placeOf(target, what) {
+  if (target && target.nodeType === 8 && target.parentNode) return [target.parentNode, target];
+  if (target && (target.nodeType === 1 || target.nodeType === 11)) return [target, null];
+  throw new TypeError(`vela: ${what} mounts only after the page hydrated, into <vela:component> or an element`);
+}
+
+// serverComponent(Component, html, options) is a component value whose
+// first mount adopts html: the root range and payload script that
+// RenderXContext of Component wrote. The nodes are inserted where the value
+// mounts and hydrated like hydrate() does, with the same options (policy,
+// onMismatch). Under repair a mismatch removes them and creates Component
+// with the props of the payload; under fail it throws. Props come from the
+// payload; the props the parent passes are applied with set() after the
+// commit. A later mount of the same value adopts a fresh copy of html.
+export function serverComponent(Component, html, options = {}) {
+  if (typeof Component !== 'function') throw new TypeError('vela: serverComponent() needs a component factory');
+  if (typeof html !== 'string') throw new TypeError('vela: serverComponent() needs the HTML as a string');
+  function Adopted(target, props, slots) {
+    const [parent, before] = placeOf(target, 'serverComponent()');
+    const content = parseHTML(html);
+    let script = null;
+    for (const node of content.childNodes) {
+      if (node.nodeType === 1 && node.localName === 'script' && node.hasAttribute('data-vela-root')) script = node;
+    }
+    if (!script) throw mismatch('serverComponent(): the HTML has no payload script (data-vela-root)');
+    const payload = readPayload(script);
+    const nodes = [...content.childNodes];
+    parent.insertBefore(content, before);
+    const own = Object.assign({}, options, slots && Object.keys(slots).length ? { slots } : {});
+    const result = adoptRoot(Component, parent, nodes[0], script, payload, own, parent, target);
+    if (result.failure) {
+      result.rollback();
+      for (const node of nodes) node.remove();
+      if (!isMismatch(result.failure) || result.session.policy === 'fail') throw result.failure;
+      result.session.report(result.failure);
+      const created = Component(target, payload.props || {}, slots || {});
+      if (props && created.set && Object.keys(props).length) created.set(props);
+      return created;
+    }
+    const instance = result.commit();
+    const destroy = instance.destroy;
+    instance.destroy = function () {
+      destroy.call(this);
+      // The root range markers and whitespace around it.
+      for (const node of nodes) if (node.parentNode) node.remove();
+    };
+    if (props && instance.set && Object.keys(props).length) instance.set(props);
+    return instance;
+  }
+  Adopted.$$props = Component.$$props;
+  Adopted.$$adopted = Component;
+  return Adopted;
+}
+
+// hasMarkers reports range markers or a payload script: the HTML of an
+// interactive root.
+function hasMarkers(content) {
+  const walker = document.createTreeWalker(content, 0x80 | 0x1);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    if (node.nodeType === 8 && (node.data.startsWith('[') || node.data === ']')) return true;
+    if (node.nodeType === 1 && node.localName === 'script' && node.hasAttribute('data-vela-root')) return true;
+  }
+  return false;
+}
+
+// staticHTML(html) is a component value that inserts html and creates no
+// instance: it has no state, set() and updates do nothing, and destroy
+// removes the nodes. HTML with range markers or a payload script is an
+// interactive root; development builds reject it.
+export function staticHTML(html) {
+  if (typeof html !== 'string') throw new TypeError('vela: staticHTML() needs the HTML as a string');
+  function Static(target) {
+    const [parent, before] = placeOf(target, 'staticHTML()');
+    const content = parseHTML(html);
+    if ($$isDev() && hasMarkers(content)) {
+      throw new TypeError('vela: staticHTML() got an interactive root (range markers or a payload script); use serverComponent()');
+    }
+    const nodes = [...content.childNodes];
+    parent.insertBefore(content, before);
+    const single = nodes.length === 1 && nodes[0].nodeType === 1 ? nodes[0] : null;
+    return {
+      el: single,
+      destroy() {
+        for (const node of nodes) if (node.parentNode) node.remove();
+      },
+      abandon() {},
+    };
+  }
+  Static.$$props = {};
+  return Static;
 }

package/runtime.js

@@ -332,6 +332,55 @@ export function mount(Component, { target, props = {}, slots = {} } = {}) {
  * tick() — returns a Promise that resolves after the current microtask queue
  * drains. Useful in tests or after imperative state changes.
  */
+// ── Lazy components (task 071) ─────────────────────────────────
+// lazy(() => import('./X.vela')) is a component value for <vela:component>
+// whose module loads on demand. The compiler adds the component ID as the
+// second argument and also registers every lazy component of a module when
+// the module is evaluated, so that preloadHydration() finds them by the IDs
+// of the payload's "d" entries. One ID has one lazy value: it is the
+// identity <vela:component> compares, before and after loading.
+const $$lazyRegistry = new Map();
+
+export function lazy(loader, id) {
+  if (id && $$lazyRegistry.has(id)) return $$lazyRegistry.get(id);
+  let pending = null;
+  const value = {
+    $$lazy: true,
+    id: id || '',
+    loaded: false,
+    component: null,
+    load() {
+      if (value.loaded) return Promise.resolve(value.component);
+      if (!pending) {
+        pending = Promise.resolve()
+          .then(loader)
+          .then((module) => {
+            const component = typeof module === 'function' ? module : module && module.default;
+            if (typeof component !== 'function') {
+              throw new TypeError(`vela: lazy component ${value.id || '(unnamed)'}: the module exports no component`);
+            }
+            value.component = component;
+            value.loaded = true;
+            return component;
+          })
+          .catch((error) => {
+            // A later load() tries again.
+            pending = null;
+            throw error;
+          });
+      }
+      return pending;
+    },
+  };
+  if (id) $$lazyRegistry.set(id, value);
+  return value;
+}
+
+// $$lazyById returns the registered lazy value of a component ID.
+export function $$lazyById(id) {
+  return $$lazyRegistry.get(id) || null;
+}
+
 export function tick() {
   return Promise.resolve();
 }