@zubra/runtime 0.0.0-stage → 5.0.3

package/dist/production/zag.js

@@ -0,0 +1,59 @@
+// Generated by scripts/build-production.js from src/zag.js: the runtime without hot reloading. Do not edit.
+// @zubra/runtime/zag: Zag.js state machines driving zubra components.
+//
+// Zag (https://zagjs.com) is a framework-agnostic set of accessible widget behaviours (combobox,
+// date picker, colour picker, tree view, …) as state machines, each with a `connect()` that
+// returns prop getters. In a zubra script:
+//
+//   import * as combobox from '@zag-js/combobox'
+//   import { id, computed } from '@zubra/runtime'
+//   import { useMachine, normalizeProps } from '@zubra/runtime/zag'
+//
+//   const uid = id()                                   // once: Zag's ids must be stable
+//   const service = useMachine(combobox.machine, () => ({ id: uid, collection, onValueChange }))
+//   const api = computed(() => combobox.connect(service.current, normalizeProps))
+//
+//   <input {...api.getInputProps()}>
+//
+// `useMachine` runs Zag's own vanilla machine and turns its notifications into a signal, so the
+// `api` computed re-derives when the machine changes, and also when the props function reads zubra
+// state or props that change. A Zag machine can't be restarted once stopped (stopping drops its
+// subscriptions), so each connection of the element gets a fresh one: an element that is moved,
+// or removed and put back, keeps working. (`plan/evidence/2026-11-07-zag-spike.md`.)
+//
+// Zag is an optional peer dependency: install `@zag-js/vanilla` and the machines you use.
+import { VanillaMachine } from '@zag-js/vanilla';
+import { state, onMount } from './element.js';
+
+export { normalizeProps } from '@zag-js/vanilla';
+
+/**
+ * Run a Zag machine for this element: started when it connects, stopped when it disconnects.
+ * `props` is Zag's props, or a function returning them (read again whenever Zag asks, so it can
+ * read zubra state and props). Returns `{ current }`: the machine's service, read reactively.
+ */
+export function useMachine(machine, props = {}) {
+  const make = () => new VanillaMachine(machine, props);
+  // Before the element connects, a machine that hasn't started: connect() can read it, so the
+  // first render has the right attributes.
+  const current = state(make(), { equals: () => false });
+  const version = state(0);
+  let first = true;
+  onMount(() => {
+    const running = first ? current.get() : make();
+    first = false;
+    const unsubscribe = running.subscribe(() => version.set(version.get() + 1));
+    running.start();
+    current.set(running);
+    return () => {
+      unsubscribe();
+      running.stop();
+    };
+  });
+  return {
+    get current() {
+      version.get();
+      return current.get().service;
+    },
+  };
+}

package/fesm2022/zubra-runtime-angular.mjs

@@ -0,0 +1,118 @@
+// Angular adapter: zubra elements in Angular forms.
+//
+//   import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+//   import { FormsModule } from '@angular/forms';
+//   import { ZubraModel } from '@zubra/runtime/angular';
+//   import './rating.zb';
+//
+//   @Component({
+//     imports: [FormsModule, ZubraModel],
+//     schemas: [CUSTOM_ELEMENTS_SCHEMA],
+//     template: `<zb-rating zubraModel [(ngModel)]="stars" (change)="saved()"></zb-rating>`,
+//   })
+//
+// Angular needs nothing else for a zubra element: `[heading]="x"` sets the property,
+// `(valuechange)="…"` listens for the event, and children are the element's slot content.
+// What it can't do on its own is two-way binding, because `[(value)]` listens for
+// `valueChange` and the element fires `valuechange`. `zubraModel` makes the element a form control
+// instead (ngModel, formControl, formControlName), using the `<prop>` + `<prop>change` pair:
+// `zubraModel` alone picks the `value` pair (or the only pair), `zubraModel="checked"` names one.
+//
+// The class is published the way Angular libraries are (partial declarations, in a `fesm2022/`
+// file as the Angular Package Format lays out), so the linker of the Angular CLI and of
+// Vite-based builds (Analog) compiles it in AOT builds, and JIT compiles it at runtime.
+import * as i0 from '@angular/core';
+import { ChangeDetectorRef, DestroyRef, ElementRef, forwardRef, inject } from '@angular/core';
+import { NG_VALUE_ACCESSOR } from '@angular/forms';
+import { models } from '../src/vue.js';
+
+const clone = (value) => (value && typeof value === 'object' ? structuredClone(value) : value);
+
+function metaOf(element) {
+  const meta = element.constructor?.zubra ?? customElements.get(element.localName)?.zubra;
+  if (!meta) throw new TypeError(`zubra: zubraModel is on <${element.localName}>, which isn't a defined zubra element (import its .zb module first)`);
+  return meta;
+}
+
+export class ZubraModel {
+  /** The prop to bind; empty for the `value` pair, or the only pair. */
+  zubraModel = '';
+  #element = inject(ElementRef).nativeElement;
+  #changes = inject(ChangeDetectorRef);
+  #pair = null;
+  #onChange = () => {};
+  #onTouched = () => {};
+
+  constructor() {
+    const listener = (event) => {
+      if (event.target !== this.#element) return;
+      const pair = this.#resolve();
+      if (event.type !== pair.event) return;
+      this.#onChange(event.detail);
+      this.#changes.markForCheck();
+    };
+    const touched = () => this.#onTouched();
+    // Every `…change` event is caught here, so the pair can be settled lazily (the element may be
+    // defined after the directive is created).
+    const types = new Set();
+    const listen = () => {
+      for (const { event } of models(metaOf(this.#element))) {
+        if (types.has(event)) continue;
+        types.add(event);
+        this.#element.addEventListener(event, listener);
+      }
+    };
+    customElements.whenDefined(this.#element.localName).then(listen);
+    this.#element.addEventListener('focusout', touched);
+    inject(DestroyRef).onDestroy(() => {
+      for (const type of types) this.#element.removeEventListener(type, listener);
+      this.#element.removeEventListener('focusout', touched);
+    });
+  }
+
+  #resolve() {
+    if (this.#pair) return this.#pair;
+    const meta = metaOf(this.#element);
+    const pairs = models(meta);
+    const pair = this.zubraModel
+      ? pairs.find((candidate) => candidate.prop === this.zubraModel)
+      : pairs.find((candidate) => candidate.prop === 'value') ?? (pairs.length === 1 ? pairs[0] : undefined);
+    if (!pair) {
+      const named = pairs.map((candidate) => `\`${candidate.prop}\``).join(', ') || 'none';
+      throw new TypeError(this.zubraModel
+        ? `zubra: <${meta.tag}> has no \`${this.zubraModel}\` + \`${this.zubraModel.toLowerCase()}change\` pair for zubraModel (pairs: ${named})`
+        : `zubra: zubraModel on <${meta.tag}> needs a name, e.g. zubraModel="${pairs[0]?.prop ?? 'value'}" (pairs: ${named})`);
+    }
+    return (this.#pair = pair);
+  }
+
+  writeValue(value) {
+    const set = () => {
+      const { prop } = this.#resolve();
+      // Forms reset to null: that's the component's default.
+      this.#element[prop] = value ?? clone(metaOf(this.#element).props[prop].default);
+    };
+    if (customElements.get(this.#element.localName)) set();
+    else customElements.whenDefined(this.#element.localName).then(set);
+  }
+
+  registerOnChange(fn) { this.#onChange = fn; }
+  registerOnTouched(fn) { this.#onTouched = fn; }
+
+  setDisabledState(disabled) {
+    const { props } = metaOf(this.#element);
+    if ('disabled' in props) this.#element.disabled = disabled;
+    else this.#element.toggleAttribute('disabled', disabled);
+  }
+
+  static ɵfac = i0.ɵɵngDeclareFactory({
+    minVersion: '12.0.0', version: '17.0.0', ngImport: i0, type: ZubraModel, deps: [], target: i0.ɵɵFactoryTarget.Directive,
+  });
+  static ɵdir = i0.ɵɵngDeclareDirective({
+    minVersion: '14.0.0', version: '17.0.0', type: ZubraModel, isStandalone: true, selector: '[zubraModel]',
+    inputs: { zubraModel: 'zubraModel' },
+    providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => ZubraModel), multi: true }],
+    exportAs: ['zubraModel'],
+    ngImport: i0,
+  });
+}

package/package.json

@@ -1,6 +1,128 @@
 {
   "name": "@zubra/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.0.3",
+  "description": "Browser runtime for Zubra compiled components, built on the TC39 Signals API",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "runtime"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "production": "./dist/production/index.js",
+      "default": "./src/index.js"
+    },
+    "./signal": {
+      "types": "./types/signal.d.ts",
+      "production": "./dist/production/signal.js",
+      "default": "./src/signal.js"
+    },
+    "./effect": {
+      "types": "./types/effect.d.ts",
+      "production": "./dist/production/effect.js",
+      "default": "./src/effect.js"
+    },
+    "./spread": {
+      "types": "./types/spread.d.ts",
+      "production": "./dist/production/spread.js",
+      "default": "./src/spread.js"
+    },
+    "./zag": {
+      "types": "./types/zag.d.ts",
+      "production": "./dist/production/zag.js",
+      "default": "./src/zag.js"
+    },
+    "./primitives": {
+      "types": "./types/primitives.d.ts",
+      "production": "./dist/production/primitives.js",
+      "default": "./src/primitives.js"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "production": "./dist/production/react.js",
+      "default": "./src/react.js"
+    },
+    "./vue": {
+      "types": "./types/vue.d.ts",
+      "production": "./dist/production/vue.js",
+      "default": "./src/vue.js"
+    },
+    "./angular": {
+      "types": "./types/angular.d.ts",
+      "default": "./fesm2022/zubra-runtime-angular.mjs"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "production": "./dist/production/server.js",
+      "default": "./src/server.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "test:browser": "node --test \"test/browser/*.test.js\"",
+    "test:tools": "node --test \"test/tools/*.test.js\"",
+    "build:production": "node scripts/build-production.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=16",
+    "@angular/forms": ">=16",
+    "@zag-js/vanilla": ">=1.47",
+    "react": ">=18",
+    "vue": "^3.3"
+  },
+  "peerDependenciesMeta": {
+    "@angular/core": {
+      "optional": true
+    },
+    "@angular/forms": {
+      "optional": true
+    },
+    "@zag-js/vanilla": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/common": "22.2.5",
+    "@angular/compiler": "22.2.5",
+    "@angular/compiler-cli": "22.2.5",
+    "@angular/core": "22.2.5",
+    "@angular/forms": "22.2.5",
+    "@angular/platform-browser": "22.2.5",
+    "@babel/core": "8.1.0",
+    "@types/react": "19.3.0",
+    "@zag-js/combobox": "1.47.0",
+    "@zag-js/vanilla": "1.47.0",
+    "ajv": "^8.20.0",
+    "custom-elements-manifest": "^2.1.0",
+    "esbuild": "0.28.2",
+    "playwright": "1.63.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-dom18": "npm:react-dom@18.3.1",
+    "react18": "npm:react@18.3.1",
+    "rxjs": "7.8.2",
+    "signal-polyfill": "0.2.2",
+    "typescript": "^7.0.2",
+    "vscode-html-languageservice": "5.6.2",
+    "vscode-languageserver-textdocument": "1.0.16",
+    "vue": "3.5.45"
+  },
+  "files": [
+    "src",
+    "dist",
+    "fesm2022",
+    "types"
+  ]
+}

package/src/deep.js

@@ -0,0 +1,87 @@
+// Deep reactivity for state: `let items = []` followed by `items.push(x)` updates the DOM.
+//
+// A `state()` holding an array or a plain object holds a proxy of it instead. Each property the
+// template (or a computed) reads through the proxy is tracked by its own `Signal.State`, created
+// on first read, and each write through the proxy bumps that property's signal, so only what
+// read the property re-runs. Nested arrays and objects are wrapped lazily, on read. Nothing here
+// is a new runtime concept: it's `Signal.State` per property, over the standard API.
+//
+// What's wrapped: arrays and plain objects (prototype `Object.prototype` or `null`). Class
+// instances, `Map`/`Set`, dates, DOM nodes, functions and promises are left as they are, since a
+// proxy would break their internals. `raw(value)` gives the original object back.
+// (`plan/decisions/deep-reactivity.md`.)
+
+import { Signal } from './signal.js';
+
+const RAW = Symbol('zubra.raw');
+const ITERATE = Symbol('zubra.iterate'); // "the set of keys" (ownKeys, `in`, array length)
+const proxies = new WeakMap(); // raw → proxy
+const signals = new WeakMap(); // raw → Map<key, Signal.State<number>>
+
+const isPlain = (value) => {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/** The object behind a reactive proxy, or the value itself. */
+export const raw = (value) => (value && typeof value === 'object' && value[RAW]) || value;
+
+function track(target, key) {
+  let map = signals.get(target);
+  if (!map) signals.set(target, (map = new Map()));
+  let signal = map.get(key);
+  if (!signal) map.set(key, (signal = new Signal.State(0)));
+  signal.get();
+}
+
+function trigger(target, key) {
+  const signal = signals.get(target)?.get(key);
+  if (signal) signal.set(signal.get() + 1);
+}
+
+const handler = {
+  get(target, key, receiver) {
+    if (key === RAW) return target;
+    if (typeof key !== 'symbol') track(target, key);
+    return wrap(Reflect.get(target, key, receiver));
+  },
+  has(target, key) {
+    if (typeof key !== 'symbol') track(target, key);
+    return Reflect.has(target, key);
+  },
+  ownKeys(target) {
+    track(target, ITERATE);
+    return Reflect.ownKeys(target);
+  },
+  set(target, key, value, receiver) {
+    value = raw(value);
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    const before = target[key];
+    const length = Array.isArray(target) ? target.length : -1;
+    const ok = Reflect.set(target, key, value, receiver);
+    if (!had) trigger(target, ITERATE);
+    if (!had || !Object.is(before, value)) trigger(target, key);
+    // Setting an index past the end grows the array without a `length` write.
+    if (length >= 0 && target.length !== length && key !== 'length') trigger(target, 'length');
+    return ok;
+  },
+  deleteProperty(target, key) {
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    const ok = Reflect.deleteProperty(target, key);
+    if (had) {
+      trigger(target, ITERATE);
+      trigger(target, key);
+    }
+    return ok;
+  },
+};
+
+/** `value` as a reactive proxy, if it's an array or a plain object; otherwise `value`. */
+export function wrap(value) {
+  if (!isPlain(value) || value[RAW]) return value;
+  let proxy = proxies.get(value);
+  if (!proxy) proxies.set(value, (proxy = new Proxy(value, handler)));
+  return proxy;
+}

package/src/effect.js

@@ -0,0 +1,233 @@
+// Effects and ownership, built only on the Signals API.
+//
+// The Signals proposal intentionally leaves effects and scheduling to libraries; this is ours.
+// It follows the pattern from the proposal's README (one Watcher, flushed in a microtask) and
+// adds what components need:
+//
+//   effect(fn)        run fn now, re-run it (batched) when what it read changes; returns dispose
+//   scope(fn)         an ownership root: effects created inside belong to it
+//   flush() / tick()  apply pending re-runs now / await them
+//
+// 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.
+//
+// Pausing: a scope can be paused (an element left the DOM) and resumed (it came back). Paused
+// effects are unwatched, so long-lived signals hold no reference to them, but each keeps its
+// cached result and the versions it last saw. On resume it is re-validated and re-runs only if
+// something it depends on changed while it was away — the version check in Signal.Computed does
+// exactly that, so no extra bookkeeping is needed here.
+import { Signal } from './signal.js';
+
+const { untrack } = Signal.subtle;
+const MAX_ROUNDS = 100;
+
+let owner = null;          // the Effect or Scope currently running
+let nextId = 0;
+let scheduled = null;      // promise for the pending microtask flush
+let flushing = false;
+const effectOf = new WeakMap();
+
+const watcher = new Signal.subtle.Watcher(() => {
+  scheduled ??= new Promise((resolve) => queueMicrotask(() => {
+    try { flush(); } finally { scheduled = null; resolve(); }
+  }));
+});
+
+// Unwatching is batched: disposing or pausing a subtree (removing a list of 1,000 rows), or
+// anything inside `batch()`, unwatches everything in one pass over the watcher's signals,
+// instead of one pass per effect. Outside a batch it happens at once.
+const unwatching = new Set();
+let batching = 0;
+
+function unwatchLater(computed) {
+  if (batching) unwatching.add(computed);
+  else watcher.unwatch(computed);
+}
+
+/** Run `fn`, unwatching what it disposes or pauses in one pass at the end. */
+export function batch(fn) {
+  batching++;
+  try {
+    return fn();
+  } finally {
+    if (--batching === 0 && unwatching.size) {
+      const all = [...unwatching];
+      unwatching.clear();
+      for (let i = 0; i < all.length; i += 10000) watcher.unwatch(...all.slice(i, i + 10000));
+    }
+  }
+}
+
+/** Watch again (a resumed effect): if its unwatch is still pending, just cancel that. */
+function watchAgain(computed) {
+  if (!unwatching.delete(computed)) watcher.watch(computed);
+}
+
+function report(error) {
+  if (typeof globalThis.reportError === 'function') globalThis.reportError(error);
+  else console.error(error);
+}
+
+class Owner {
+  constructor(parent) {
+    this.parent = parent;
+    this.children = new Set();
+    this.disposed = false;
+    this.paused = false;
+    parent?.children.add(this);
+  }
+
+  disposeChildren() {
+    batch(() => {
+      for (const child of [...this.children]) child.dispose();
+    });
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.disposeChildren();
+    this.parent?.children.delete(this);
+  }
+
+  pause() {
+    if (this.paused || this.disposed) return;
+    this.paused = true;
+    batch(() => {
+      for (const child of [...this.children]) child.pause();
+    });
+  }
+
+  resume() {
+    if (!this.paused || this.disposed) return;
+    this.paused = false;
+    // Children may be replaced while their parent resumes, so iterate a snapshot and skip
+    // anything that was disposed along the way.
+    for (const child of [...this.children]) if (!child.disposed) child.resume();
+  }
+}
+
+class Effect extends Owner {
+  constructor(fn, parent) {
+    super(parent);
+    this.id = ++nextId;
+    this.cleanup = undefined;
+    this.computed = new Signal.Computed(() => {
+      this.disposeChildren();
+      this.runCleanup();
+      const previous = owner;
+      owner = this;
+      try {
+        const result = fn();
+        this.cleanup = typeof result === 'function' ? result : undefined;
+      } finally {
+        owner = previous;
+      }
+    });
+    effectOf.set(this.computed, this);
+    watcher.watch(this.computed);
+  }
+
+  /** Re-validate: re-runs fn only if a dependency changed since the last run. */
+  run() {
+    // untrack: if this effect was created inside another effect, the parent must not end up
+    // depending on whatever the child reads.
+    untrack(() => this.computed.get());
+  }
+
+  runCleanup() {
+    const cleanup = this.cleanup;
+    this.cleanup = undefined;
+    if (cleanup) untrack(cleanup);
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    super.dispose();
+    unwatchLater(this.computed);
+    try { this.runCleanup(); } catch (error) { report(error); }
+  }
+
+  pause() {
+    if (this.paused || this.disposed) return;
+    super.pause();
+    unwatchLater(this.computed);
+  }
+
+  resume() {
+    if (!this.paused || this.disposed) return;
+    this.paused = false;
+    watchAgain(this.computed);
+    try { this.run(); } catch (error) { report(error); }
+    for (const child of [...this.children]) if (!child.disposed) child.resume();
+  }
+}
+
+class Scope extends Owner {
+  run(fn) {
+    const previous = owner;
+    owner = this;
+    try { return fn(); } finally { owner = previous; }
+  }
+}
+
+/**
+ * Run `fn` now and again whenever a signal it read changes. Re-runs are batched: any number of
+ * writes in one task cause one re-run, in a microtask. `fn` may return a cleanup function, which
+ * runs before the next run and on dispose. Errors thrown by re-runs are reported, not thrown, so
+ * one failing effect doesn't stop the others; an error in the first run is thrown to the caller.
+ */
+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();
+}
+
+/**
+ * Create an ownership root and run `fn` inside it. Returns the scope, whose `dispose()`,
+ * `pause()` and `resume()` apply to every effect created within (now or by later `run()` calls).
+ */
+export function scope(fn) {
+  const s = new Scope(owner);
+  if (fn) s.run(fn);
+  return s;
+}
+
+/**
+ * Like `scope`, but owned by nothing and untracked: for something whose life isn't the running
+ * effect's (an element, which lives as long as it's in the document, even when an effect's run
+ * inserted it).
+ */
+export function root(fn) {
+  const s = new Scope(null);
+  if (fn) untrack(() => s.run(fn));
+  return s;
+}
+
+/** Apply all pending re-runs synchronously, parents before children. */
+export function flush() {
+  if (flushing) return;
+  flushing = true;
+  try {
+    for (let round = 0; ; round++) {
+      const pending = watcher.getPending();
+      watcher.watch(); // re-arm before running, so writes made by effects schedule another round
+      if (pending.length === 0) return;
+      if (round >= MAX_ROUNDS) {
+        report(new Error('zubra: effects keep re-triggering each other; stopped after 100 rounds'));
+        return;
+      }
+      const effects = pending.map((computed) => effectOf.get(computed)).sort((a, b) => a.id - b.id);
+      for (const e of effects) {
+        if (e.disposed || e.paused) continue;
+        try { e.run(); } catch (error) { report(error); }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+
+/** Resolves once pending re-runs have been applied. */
+export const tick = () => scheduled ?? Promise.resolve();