@zubra/runtime 5.7.0 → 5.9.0

package/README.md

@@ -13,9 +13,14 @@ ships one, this package deletes code instead of components being rewritten.
 | `src/element.js` hooks | Plain functions (see the project's hooks decision) | `state`, `from`, `computed`, `watch`, `onMount`, `onUnmount`, `id`, `props`, `host`, `emit`, `hydrated` |
 | `src/element.js` slots | Light-DOM slotting with the host's child methods routed to the slots, so frameworks can keep managing the children; native `<slot>` in shadow DOM | Done |
 | `src/react.js`, `src/vue.js` | Adapters: an element as a React (18, 19) or Vue 3 component | Done |
+| `src/testing.js` | `mount(Element, { framework })`: a component through plain HTML, the React adapter or the Vue adapter, for one test per framework in any browser test runner | Done |
+| `src/navigation.js` | Links inside components through the app's router: `routeLinks(navigate)`; `useRouteLinks` in the React and Vue adapters. Not a router | Done |
+| `src/forms.js` | A control as a form library's field: React Hook Form (`registerProps`, `fieldProps`), TanStack Form (`fieldProps`), VeeValidate (`vueFieldProps`), Felte (`felteControl`) | Done |
+| `src/bridge.js` | Signals read from framework code: `subscribe`, and `toStore` (the Svelte store contract and an RxJS-style Subscribable); React and Vue `useSignal` | Done |
 | `types/` | TypeScript declarations for every entry point | Done |
 | `src/element.js` forms | Form-associated custom elements (`ElementInternals`) | `formValue`, `validity`, `onFormReset`, `onFormRestore`, `onFormDisabled`; native control API on the element |
 | `src/element.js` context | [Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md) (`context-request` / `context-provider` events) | `createContext`, `provide`, `inject`; interoperates with any protocol implementation |
+| `src/context.js` | The same protocol, provided from the app: `<zb-context>` with `context` and `value` properties; `ZubraContext` in the React and Vue adapters | Done |
 
 ## The production build
 
@@ -82,6 +87,25 @@ await tick();
 A write to a signal an effect has already read in the same run does not re-run it (same as a
 computed in the reference). Derive the value instead of writing it back.
 
+## Signals in framework code
+
+A signal elements read can be read by the app too, so state is shared rather than copied in by
+props and back out by events (`@zubra/runtime/bridge`):
+
+```js
+import { state } from '@zubra/runtime';
+export const cart = state([]);                       // cart-state.js, imported by elements too
+
+// React                                             // Vue
+const items = useSignal(cart, { deep: true });       const items = useSignal(cart, { deep: true }); // a ref
+// Svelte: const items = toStore(cart, { deep: true }), then {$items.length}
+// Solid: from(toStore(cart))     Angular: toSignal(toStore(cart), { requireSync: true })
+```
+
+`subscribe` and the stores are effects owned by nothing: they last until unsubscribed (Vue's ref
+stops with the scope it was made in; React's hook with the component). `deep: true` reads through
+an array or plain object, so a mutation inside it notifies.
+
 ## Tests
 
 ```sh

package/dist/production/bridge.js

@@ -0,0 +1,97 @@
+// Generated by scripts/build-production.js from src/bridge.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// Signal bridges: read (and write) a Zubra signal from a framework's own code.
+//
+//   import { shared } from './cart-state.js'               // export const shared = state([])
+//   import { toStore } from '@zubra/runtime/bridge'
+//   const cart = toStore(shared, { deep: true })
+//
+//   Svelte:   {$cart.length}                               (the store contract)
+//   Solid:    const items = from(cart)                     (solid-js `from`)
+//   Angular:  items = toSignal(cart, { requireSync: true })  (a Subscribable)
+//   RxJS:     from(cart)                                   (Symbol.observable)
+//   React:    useSignal(shared) from '@zubra/runtime/react'
+//   Vue:      useSignal(shared) from '@zubra/runtime/vue'
+//
+// The adapters carry props, events and two-way bindings across the element boundary; this
+// carries state: a signal that elements and the app's code both read, without copying it into
+// the framework's state and back. Any `Signal.State` or `Signal.Computed` works (`state()`,
+// `computed()`, `from()`, a `@zubra/sync` field, a native `Signal` once browsers ship one), as
+// does a function that reads signals (it's tracked like a computed).
+//
+// `deep: true` also tracks what's inside an array or plain object, so `items.push(x)` notifies
+// as `items = [...items, x]` does. Without it a mutation inside the value isn't a change.
+import { Signal } from './signal.js';
+import { effect, root } from './effect.js';
+
+const isSignal = (value) => value instanceof Signal.State || value instanceof Signal.Computed;
+
+function check(source, name) {
+  if (typeof source !== 'function' && !isSignal(source)) {
+    throw new TypeError(`zubra: ${name}() needs a signal (state(), computed(), a Signal.State or Signal.Computed) or a function that reads signals`);
+  }
+}
+
+/** The source's current value: a signal's `get()`, or the function's result. */
+export const read = (source) => (typeof source === 'function' ? source() : source.get());
+
+/** Whether the source can be written: a `Signal.State`, or a signal with its own `set` (`from()`). */
+export const writable = (source) => typeof source?.set === 'function';
+
+// Read every property of an array or plain object (through state's proxy, each read is tracked),
+// so a change anywhere inside notifies.
+function touch(value, seen = new Set()) {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return;
+  if (!Array.isArray(value)) {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) for (let index = 0; index < value.length; index++) touch(value[index], seen);
+  else for (const key of Object.keys(value)) touch(value[key], seen);
+}
+
+/**
+ * Call `callback(value)` now and whenever `source` changes, until the returned function is
+ * called. Changes are batched like the runtime's own effects: one call per microtask, with the
+ * latest value. Not owned by any component, so it lives until it's unsubscribed.
+ */
+export function subscribe(source, callback, { deep = false } = {}) {
+  check(source, 'subscribe');
+  const owner = root(() => {
+    effect(() => {
+      const value = read(source);
+      if (deep) touch(value);
+      Signal.subtle.untrack(() => callback(value));
+    });
+  });
+  return () => owner.dispose();
+}
+
+/**
+ * The source as a store: the Svelte store contract (`subscribe(run)` calls `run` now and on each
+ * change, returning the unsubscribe function), which is also an RxJS-style Subscribable
+ * (`subscribe({ next })` returns something with `unsubscribe()`), so Angular's `toSignal`, Solid's
+ * `from` and RxJS's `from` take it as it is. `set` and `update` are there when the source is
+ * writable (a Svelte writable store, so `bind:value={$store}` works).
+ */
+export function toStore(source, options = {}) {
+  check(source, 'toStore');
+  const store = {
+    get: () => read(source),
+    subscribe(run) {
+      const next = typeof run === 'function' ? run : (value) => run?.next?.(value);
+      const stop = subscribe(source, next, options);
+      const unsubscribe = () => stop();
+      unsubscribe.unsubscribe = unsubscribe;
+      return unsubscribe;
+    },
+    [Symbol.observable ?? '@@observable']() {
+      return this;
+    },
+  };
+  if (writable(source)) {
+    store.set = (value) => source.set(value);
+    store.update = (fn) => source.set(fn(Signal.subtle.untrack(() => read(source))));
+  }
+  return store;
+}

package/dist/production/context.js

@@ -0,0 +1,101 @@
+// Generated by scripts/build-production.js from src/context.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// Context from the app: a `<zb-context>` element that answers the Context Protocol for the
+// elements inside it, so an app's theme, locale or current user reaches every component without
+// being passed down as props.
+//
+//   <zb-context .context=${theme} .value=${'dark'}>   …elements that inject(theme)…   </zb-context>
+//
+// It's a plain custom element with two properties, so every framework can use it as it is:
+// Svelte `<zb-context {context} {value}>`, Solid `prop:context`, Angular `[context]`, Lit
+// `.context`, plain HTML `el.value = …`. React and Vue have `ZubraContext` components
+// (`@zubra/runtime/react`, `@zubra/runtime/vue`) that wrap it. The element is `display:
+// contents`, so it adds no box to the layout.
+//
+// The value can be a plain value or a signal; subscribers hear each change either way. Any
+// Context Protocol consumer is answered: Zubra's `inject()`, Lit's `@consume`, and so on. A
+// consumer that asked before the element was given its context asks again when the element
+// announces it with a `context-provider` event (children connect after their parent, so one
+// given its context before it's in the document is there when they first ask).
+import { Signal } from './signal.js';
+import { effect, root } from './effect.js';
+import { ContextProviderEvent } from './element.js';
+
+const isSignal = (value) => value instanceof Signal.State || value instanceof Signal.Computed;
+const unwrap = (value) => (isSignal(value) ? value.get() : value);
+
+const Base = globalThis.HTMLElement ?? class {};
+
+export class ZubraContextElement extends Base {
+  #context = undefined;
+  #value = undefined;
+  #subscribers = new Set();
+  #watching = null; // the effect following a signal value
+
+  constructor() {
+    super();
+    this.addEventListener('context-request', (event) => {
+      if (this.#context === undefined || event.context !== this.#context || event.contextTarget === this) return;
+      event.stopPropagation();
+      const current = Signal.subtle.untrack(() => unwrap(this.#value));
+      if (!event.subscribe) return event.callback(current);
+      const subscriber = { callback: event.callback };
+      subscriber.unsubscribe = () => this.#subscribers.delete(subscriber);
+      this.#subscribers.add(subscriber);
+      event.callback(current, subscriber.unsubscribe);
+    });
+  }
+
+  /** The context key this element provides (from `createContext()`, or any protocol key). */
+  get context() {
+    return this.#context;
+  }
+
+  set context(key) {
+    if (key === this.#context) return;
+    // Consumers of the old key keep what they have, but stop hearing from this element.
+    this.#subscribers.clear();
+    this.#context = key;
+    this.#announce();
+  }
+
+  /** The value, or a signal holding it. */
+  get value() {
+    return this.#value;
+  }
+
+  set value(next) {
+    if (Object.is(next, this.#value)) return;
+    this.#value = next;
+    this.#watching?.dispose();
+    this.#watching = null;
+    if (isSignal(next)) {
+      let first = true;
+      this.#watching = root(() => effect(() => {
+        const value = next.get();
+        if (first) first = false;
+        else Signal.subtle.untrack(() => this.#notify(value));
+      }));
+    }
+    this.#notify(Signal.subtle.untrack(() => unwrap(next)));
+  }
+
+  connectedCallback() {
+    if (!this.style.display) this.style.display = 'contents';
+  }
+
+  #notify(value) {
+    for (const subscriber of [...this.#subscribers]) subscriber.callback(value, subscriber.unsubscribe);
+  }
+
+  #announce() {
+    if (this.#context !== undefined && this.isConnected) this.dispatchEvent(new ContextProviderEvent(this.#context, this));
+  }
+}
+
+/** Define `<zb-context>` (once; a no-op where there's no `customElements`, as on a server). */
+export function defineContextElement() {
+  const registry = globalThis.customElements;
+  if (registry && !registry.get('zb-context')) registry.define('zb-context', ZubraContextElement);
+}
+
+defineContextElement();

package/dist/production/effect.js

@@ -9,6 +9,11 @@
 //   scope(fn)         an ownership root: effects created inside belong to it
 //   flush() / tick()  apply pending re-runs now / await them
 //
+// Disposal: effect()'s dispose function and every scope are also disposables
+// (`[Symbol.dispose]`), so `using` and `DisposableStack` can own them where the browser has
+// Explicit Resource Management. Nothing here depends on it. Pausing is not disposal: a paused
+// scope resumes; only dispose() (or Symbol.dispose) ends one.
+//
 // Ownership: an effect created while another effect (or a scope) is running belongs to it. When
 // the owner re-runs or is disposed, everything it owns is disposed first, so nothing outlives
 // the code that created it.
@@ -29,6 +34,12 @@ let scheduled = null;      // promise for the pending microtask flush
 let flushing = false;
 const effectOf = new WeakMap();
 
+/**
+ * `Symbol.dispose`, or, where the engine doesn't have it yet, the symbol TypeScript's downlevel
+ * `using` and the polyfills look up (`Symbol.for('Symbol.dispose')`).
+ */
+export const DISPOSE = Symbol.dispose ?? Symbol.for('Symbol.dispose');
+
 
 const watcher = new Signal.subtle.Watcher(() => {
   scheduled ??= new Promise((resolve) => queueMicrotask(() => {
@@ -93,6 +104,10 @@ class Owner {
     this.parent?.children.delete(this);
   }
 
+  [DISPOSE]() {
+    this.dispose();
+  }
+
   pause() {
     if (this.paused || this.disposed) return;
     this.paused = true;
@@ -183,7 +198,9 @@ class Scope extends Owner {
 export function effect(fn) {
   const e = new Effect(fn, owner);
   e.run(); // if this throws, the effect stays registered and re-runs when its dependencies change
-  return () => e.dispose();
+  const dispose = () => e.dispose();
+  dispose[DISPOSE] = dispose;
+  return dispose;
 }
 
 /**

package/dist/production/element.js

@@ -60,6 +60,15 @@ const clone = (value) => (value && typeof value === 'object' ? structuredClone(v
 /** Attribute text → prop value, typed by the prop's default (JSON for arrays and objects). */
 function parseAttribute(spec, raw) {
   const fallback = spec.default;
+  // An enum prop (`<script lang="ts">`): the member whose value the text is, or the member it names.
+  if (spec.enum) {
+    if (raw === null) return clone(fallback);
+    const found = Object.values(spec.enum).find((value) => String(value) === raw);
+    if (found !== undefined) return found;
+    if (Object.hasOwn(spec.enum, raw)) return spec.enum[raw];
+    console.warn(`zubra: attribute "${spec.attribute}" is "${raw}", not one of ${Object.keys(spec.enum).join(', ')}`);
+    return clone(fallback);
+  }
   if (typeof fallback === 'boolean') return fallback ? raw !== 'false' : raw !== null;
   if (raw === null) return clone(fallback);
   if (typeof fallback === 'number') return Number(raw);
@@ -187,12 +196,13 @@ export function emit(name) {
 
 /**
  * An id unique to this element and call, for `id`/`for`/`aria-*` attributes. Stable for the
- * element's life; based on the host's own `id` when it has one, so it can be made to match
- * server-rendered markup.
+ * element's life. Based on the host's own `id` when it has one, else on the base the server
+ * rendered it with (`data-zb-id`), so the ids in server-rendered markup stay as they are.
  */
 export function id() {
   const component = hooks('id');
-  const base = component.host.id || `${component.host.localName}-${component.instance}`;
+  const host = component.host;
+  const base = host.id || host.getAttribute('data-zb-id') || `${host.localName}-${component.instance}`;
   return `${base}-${++component.ids}`;
 }
 
@@ -326,7 +336,18 @@ export function provide(context, value) {
  * key as `context`.
  */
 export function inject(context, fallback = context?.defaultValue) {
-  const host = hooks('inject').host;
+  const component = hooks('inject');
+  const host = component.host;
+  // The value the server rendered with (`data-zb-inject`, by call number) is where it starts,
+  // so hydrating doesn't show the default until the provider answers.
+  const number = (component.injects = (component.injects ?? 0) + 1);
+  const rendered = host.getAttribute('data-zb-inject');
+  if (rendered) {
+    try {
+      const values = JSON.parse(rendered);
+      if (Object.hasOwn(values, number)) fallback = values[number];
+    } catch { /* not ours: keep the default */ }
+  }
   const value = new Signal.State(fallback);
   let unsubscribe = null;
   let answered = false;
@@ -537,8 +558,27 @@ function departBetween(open, close, motion) {
 }
 
 /** Remove everything between `open` and `close` in one operation. */
+const nativeTextContent = typeof Node !== 'undefined' ? Object.getOwnPropertyDescriptor(Node.prototype, 'textContent').set : undefined;
 function deleteBetween(open, close) {
   if (open.nextSibling === close) return;
+  // The region is everything its parent holds but blank text (a list's own <tbody> or <ul>):
+  // emptying the parent and putting the markers and that text back is several times cheaper than
+  // deleting a range's contents.
+  const parent = open.parentNode;
+  const before = [];
+  const after = [];
+  const blank = (node) => node.nodeType === TEXT && node.data.trim() === '';
+  let edge = open.previousSibling;
+  while (edge && blank(edge) && before.length < 4) { before.unshift(edge); edge = edge.previousSibling; }
+  if (parent && !edge) {
+    edge = close.nextSibling;
+    while (edge && blank(edge) && after.length < 4) { after.push(edge); edge = edge.nextSibling; }
+    if (!edge) {
+      nativeTextContent.call(parent, '');
+      for (const node of [...before, open, close, ...after]) Node.prototype.insertBefore.call(parent, node, null);
+      return;
+    }
+  }
   const range = document.createRange();
   range.setStartAfter(open);
   range.setEndBefore(close);
@@ -1365,6 +1405,7 @@ function bindEach(part, open, hydrating, context) {
       }
       // `animate`: the rows that stay glide from where they were (@zubra/runtime/motion).
       const reorder = () => {
+        const was = new Map(rows.map((row, index) => [row, index]));
         const next = list.map((value, index) => {
           const row = byKey.get(keys[index]);
           if (!row) return createRow(value, index, keys[index]);
@@ -1374,17 +1415,14 @@ function bindEach(part, open, hydrating, context) {
           return row;
         });
         batch(() => { for (const row of byKey.values()) removeRow(row); });
-        // Text between rows, and rows on their way out, aren't rows to place against.
-        const skip = (node) => node && (node.nodeType === TEXT || part.animate?.isLeaving(node));
-        let at = open.nextSibling;
-        while (skip(at)) at = at.nextSibling;
-        for (const row of next) {
-          if (row.open === at) {
-            at = row.close.nextSibling;
-            while (skip(at)) at = at.nextSibling;
-            continue;
-          }
-          placeRow(row, at ?? close);
+        // The longest run of rows still in their old order stays put; every other row (and every
+        // new one) goes before the row after it, from the end. A swap moves two rows, not the
+        // rows between them.
+        const stay = inOrder(next.map((row) => was.get(row) ?? -1));
+        let before = close;
+        for (let index = next.length - 1; index >= 0; index--) {
+          if (!stay.has(index)) placeRow(next[index], before);
+          before = next[index].open;
         }
         rows = next;
       };
@@ -1394,6 +1432,31 @@ function bindEach(part, open, hydrating, context) {
   });
 }
 
+/**
+ * The indexes of a longest strictly increasing run in `sequence` (negative entries never count):
+ * for a keyed list, which rows are already in order and needn't move. O(n log n).
+ */
+function inOrder(sequence) {
+  const tails = []; // tails[length - 1]: the index ending the best run of that length so far
+  const previous = new Array(sequence.length);
+  for (let index = 0; index < sequence.length; index++) {
+    const value = sequence[index];
+    if (value < 0) continue;
+    let low = 0;
+    let high = tails.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if (sequence[tails[middle]] < value) low = middle + 1;
+      else high = middle;
+    }
+    previous[index] = low > 0 ? tails[low - 1] : -1;
+    tails[low] = index;
+  }
+  const kept = new Set();
+  for (let index = tails.length ? tails[tails.length - 1] : -1; index >= 0; index = previous[index]) kept.add(index);
+  return kept;
+}
+
 const hasContent = (root) =>
   [...root.childNodes].some((node) => node.nodeType !== TEXT || node.data.trim() !== '');
 
@@ -1523,6 +1586,18 @@ function defineElement(tag, definition) {
   let templateSignature = signature(childRange(componentTemplate.content));
   let instances = 0;
   const byAttribute = Object.fromEntries(Object.entries(props).map(([name, spec]) => [spec.attribute, name]));
+  // HTML lowercases attribute names, so `maxValue` in a page arrives as `maxvalue`, which isn't
+  // the prop's attribute (`max-value`): the element would ignore it without a word.
+  const lowercased = Object.entries(props)
+    .filter(([name, spec]) => name !== name.toLowerCase() && spec.attribute !== name.toLowerCase())
+    .map(([name, spec]) => [name.toLowerCase(), name, spec.attribute]);
+  const checkAttributeCase = (element) => {
+    for (const [lower, name, attribute] of lowercased) {
+      if (element.hasAttribute(lower) && !element.hasAttribute(attribute)) {
+        console.warn(`zubra: <${tag}> ignores the attribute "${lower}": HTML lowercases attribute names, and the prop ${name} is the attribute "${attribute}"${see('writing-a-component')}`);
+      }
+    }
+  };
 
   let internals; // (element) => its ElementInternals; set in the static block below
   class ZubraElement extends HTMLElement {
@@ -1597,7 +1672,10 @@ function defineElement(tag, definition) {
         // Server markup without its comments: start once the code that puts them back is here.
         loadRemark().then(() => { if (this.isConnected && !this.#scope) this.connectedCallback(); });
         return;
-      } else this.#boot();
+      } else {
+        if (lowercased.length) checkAttributeCase(this);
+        this.#boot();
+      }
       this.#cleanups = this.#hooks.mount.map((fn) => fn()).filter((cleanup) => typeof cleanup === 'function');
       this.#started();
     }

package/dist/production/forms.js

@@ -0,0 +1,126 @@
+// Generated by scripts/build-production.js from src/forms.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// Form libraries: a Zubra control as a field of React Hook Form, TanStack Form, VeeValidate or
+// Felte. Each helper turns what the library hands you for a field into the props (or the Svelte
+// action) a Zubra control takes, through its two-way binding: a `<prop>` and its `<prop>change`
+// event (`value` and `valuechange` by default).
+//
+//   React Hook Form   <Stepper {...registerProps(register('seats'))} />
+//                     <Controller name="seats" render={({ field }) => <Stepper {...fieldProps(field)} />} />
+//   TanStack Form     <form.Field name="seats">{(field) => <Stepper {...fieldProps(field)} />}</form.Field>
+//   VeeValidate       <Stepper v-bind="vueFieldProps(useField('seats'))" />
+//   Felte             <zb-stepper use:felteControl={createField('seats')}>
+//
+// Nothing here imports a library: each helper reads the shape the library documents. Native
+// form submission needs none of this; a Zubra control with `form-associated` is already a form
+// control (FormData, `<form method=post>`, server actions).
+
+const handler = (prop) => `on${prop.toLowerCase()}change`; // the React wrapper takes any casing
+const unref = (value) => (value && typeof value === 'object' && value.__v_isRef ? value.value : value);
+
+/**
+ * React Hook Form's `register(name)` as props for a wrapped Zubra control: the control's
+ * `value`, its `valuechange` reported as a change, blur reported as a blur, and the element as
+ * the ref (so `reset()` and `setValue()` write its `value`, and `setFocus()` focuses it). For a
+ * control whose model isn't `value`, use `fieldProps` with a `<Controller>`.
+ */
+export function registerProps(registration) {
+  const { name, ref, onChange, onBlur, disabled } = registration;
+  return {
+    name,
+    ref,
+    ...(disabled === undefined ? {} : { disabled }),
+    onvaluechange: (event) => onChange({ type: 'change', target: { name, value: event.detail } }),
+    onBlur: (event) => onBlur({ type: 'blur', target: { name, value: event.currentTarget?.value } }),
+  };
+}
+
+/**
+ * A field's props for a wrapped Zubra control in React, from React Hook Form's `<Controller>`
+ * (`{ value, onChange, onBlur, name, ref }`) or TanStack Form's field API
+ * (`{ state: { value }, handleChange, handleBlur, name }`). `prop` names the control's model
+ * (`value` by default).
+ */
+export function fieldProps(field, { prop = 'value' } = {}) {
+  const tanstack = typeof field.handleChange === 'function';
+  const value = tanstack ? field.state.value : field.value;
+  const change = tanstack ? field.handleChange : field.onChange;
+  const blur = tanstack ? field.handleBlur : field.onBlur;
+  return {
+    name: field.name,
+    [prop]: value,
+    [handler(prop)]: (event) => change(event.detail),
+    onBlur: () => blur(),
+    ...(field.ref ? { ref: field.ref } : {}),
+  };
+}
+
+/**
+ * A field's props for a wrapped Zubra control in Vue, from VeeValidate's `useField()` (whose
+ * `value` is a ref) or the `field` a `<Field v-slot="{ field }">` gives. `prop` names the
+ * control's model (`value` by default).
+ */
+export function vueFieldProps(field, { prop = 'value' } = {}) {
+  const change = field.handleChange ?? field.onChange;
+  const blur = field.handleBlur ?? field.onBlur;
+  const value = 'value' in field ? unref(field.value) : field.modelValue;
+  return {
+    name: unref(field.name),
+    [prop]: value,
+    [`onUpdate:${prop}`]: (next) => (Array.isArray(change) ? change.forEach((fn) => fn(next)) : change(next)),
+    // The control's own focus leaves it: `blur` doesn't bubble out of its inner input, `focusout` does.
+    onFocusout: (event) => (Array.isArray(blur) ? blur.forEach((fn) => fn(event)) : blur?.(event)),
+  };
+}
+
+/**
+ * Felte: a Svelte action (or a plain function for `@felte/vanilla`) that connects a Zubra control
+ * to a field from Felte's `createField(name)`. Felte reads native inputs, so the field keeps a
+ * hidden one in step with the control: each `<prop>change` is reported as input, focus leaving
+ * the control as a blur, and Felte's own writes (`reset()`, `setFields()`) reach the control. Returns `{ destroy }`.
+ *
+ *   <zb-stepper use:felteControl={createField('seats')}></zb-stepper>
+ */
+export function felteControl(node, created, { prop = 'value' } = {}) {
+  const field = created?.field ? created : null;
+  if (!field) throw new TypeError("zubra: felteControl() needs the result of Felte's createField(name)");
+  const action = field.field(node) ?? {};
+  // Felte puts its hidden input in place, after the control, on the next task. Start it at the
+  // control's value; keep a number a number (Felte reads `type="number"` inputs as numbers, and this
+  // one stays hidden); and pass Felte's own writes to it (`reset()`, `setFields()`) to the control.
+  let writing = false;
+  const start = setTimeout(() => {
+    const input = node.nextElementSibling;
+    if (input?.localName === 'input' && input.type === 'hidden') {
+      if (typeof node[prop] === 'number') {
+        input.type = 'number';
+        input.hidden = true;
+      }
+      const own = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value');
+      Object.defineProperty(input, 'value', {
+        configurable: true,
+        get: () => own.get.call(input),
+        set: (value) => {
+          own.set.call(input, value);
+          if (!writing) node[prop] = input.type === 'number' && value !== '' ? Number(value) : value;
+        },
+      });
+    }
+    report(node[prop]);
+  });
+  const report = (value) => {
+    writing = true;
+    try { field.onInput(value); } finally { writing = false; }
+  };
+  const change = (event) => report(event.detail);
+  const blur = () => field.onBlur();
+  node.addEventListener(prop.toLowerCase() + 'change', change);
+  node.addEventListener('focusout', blur);
+  return {
+    destroy() {
+      clearTimeout(start);
+      node.removeEventListener(prop.toLowerCase() + 'change', change);
+      node.removeEventListener('focusout', blur);
+      action.destroy?.();
+    },
+  };
+}

package/dist/production/navigation.js

@@ -0,0 +1,53 @@
+// Generated by scripts/build-production.js from src/navigation.js: the runtime without hot reloading or the DevTools hook. Do not edit.
+// Links inside components, through the app's router: a plain `<a href>` in a Zubra component
+// navigates with the router the app already has (React Router, Next.js, Vue Router, SvelteKit,
+// Angular Router…) instead of reloading the page. Not a router: one listener that hands the
+// app's router the URL, and otherwise leaves the link alone.
+//
+//   routeLinks((to) => router.push(to))          // Vue Router; returns a function that stops it
+//   useRouteLinks(useNavigate())                  // React Router (`@zubra/runtime/react`)
+//   useRouteLinks(useRouter().push)               // Next.js
+//   routeLinks((to) => goto(to))                  // SvelteKit, in onMount
+//   routeLinks((to) => router.navigateByUrl(to))  // Angular
+//
+// Without JavaScript, or for a link it leaves alone, the link is a link. It leaves alone: a click
+// something already handled (`preventDefault()`), a modified or non-primary click (new tab,
+// window, download), a `target` other than `_self`, `download`, `rel="external"`, another
+// origin, and a link to a place on the current page (`#…`). Only links inside a Zubra component
+// are routed by default (the app's own links are its router's business); `within` changes that.
+//
+// If the app's router already intercepts the Navigation API's `navigate` event (Baseline since
+// January 2026), links in components already go through it, and none of this is needed.
+
+/** A Zubra component's host: its class carries the compiled `zubra` metadata. */
+export const isComponent = (node) => Boolean(node?.constructor?.zubra);
+
+/**
+ * Route clicks on links inside Zubra components through `navigate(to, { event, anchor, url })`,
+ * where `to` is the path, query and hash (`/seats?row=b#top`). Returns a function that stops it.
+ * `within(node)` decides which ancestors count (by default, a Zubra component's host); `root` is
+ * where to listen (by default, the document).
+ */
+export function routeLinks(navigate, { within = isComponent, root = globalThis.document } = {}) {
+  if (typeof navigate !== 'function') throw new TypeError('zubra: routeLinks() needs a function that navigates, such as (to) => router.push(to)');
+  if (!root) return () => {};
+  const click = (event) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const path = event.composedPath();
+    const at = path.findIndex((node) => node.localName === 'a' && node.hasAttribute?.('href'));
+    if (at < 0) return;
+    const anchor = path[at];
+    if (!path.slice(at + 1).some((node) => node.nodeType === 1 && within(node))) return;
+    const target = anchor.getAttribute('target');
+    if ((target && target !== '_self') || anchor.hasAttribute('download')) return;
+    if ((anchor.getAttribute('rel') ?? '').split(/\s+/).includes('external')) return;
+    const url = new URL(anchor.href, anchor.baseURI);
+    const here = new URL(globalThis.location.href);
+    if (url.origin !== here.origin) return;
+    if (url.hash && url.pathname === here.pathname && url.search === here.search) return;
+    event.preventDefault();
+    navigate(url.pathname + url.search + url.hash, { event, anchor, url });
+  };
+  root.addEventListener('click', click);
+  return () => root.removeEventListener('click', click);
+}