@zubra/runtime 0.0.0-stage → 5.0.3

package/src/zag.js

@@ -0,0 +1,58 @@
+// @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/types/angular.d.ts

@@ -0,0 +1,20 @@
+import type { ControlValueAccessor } from '@angular/forms';
+import type * as i0 from '@angular/core';
+
+/**
+ * Makes a zubra element a form control (`ngModel`, `formControl`, `formControlName`) through its
+ * `<prop>` + `<prop>change` pair. `zubraModel` alone binds the `value` pair (or the only pair);
+ * `zubraModel="checked"` names one. A standalone directive: add it to the component's `imports`.
+ */
+export declare class ZubraModel implements ControlValueAccessor {
+  /** The prop to bind; empty for the `value` pair, or the only pair. */
+  zubraModel: string;
+  writeValue(value: unknown): void;
+  registerOnChange(fn: (value: unknown) => void): void;
+  registerOnTouched(fn: () => void): void;
+  setDisabledState(disabled: boolean): void;
+  // What Angular's ahead-of-time compiler reads to use the directive in a template (as in any
+  // Angular library's typings).
+  static ɵfac: i0.ɵɵFactoryDeclaration<ZubraModel, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<ZubraModel, '[zubraModel]', ['zubraModel'], { zubraModel: { alias: 'zubraModel'; required: false } }, {}, never, never, true, never>;
+}

package/types/effect.d.ts

@@ -0,0 +1,28 @@
+/** Something to run when an effect re-runs or is disposed. */
+export type Cleanup = () => void;
+
+/**
+ * Run `fn` now and again whenever a signal it read changes (batched: several writes in one task
+ * cause one re-run, in a microtask). `fn` may return a cleanup. Returns a function that disposes
+ * the effect. Effects created inside another effect or scope belong to it.
+ */
+export declare function effect(fn: () => void | Cleanup): () => void;
+
+/** An ownership root: disposing, pausing or resuming it applies to every effect inside. */
+export interface Scope {
+  run<T>(fn: () => T): T;
+  dispose(): void;
+  pause(): void;
+  resume(): void;
+  readonly disposed: boolean;
+  readonly paused: boolean;
+}
+
+/** Create a scope (owned by the current one) and run `fn` in it. */
+export declare function scope(fn?: () => void): Scope;
+
+/** Apply pending effect re-runs now, parents before children. */
+export declare function flush(): void;
+
+/** Resolves once pending effect re-runs have happened. */
+export declare function tick(): Promise<void>;

package/types/index.d.ts

@@ -0,0 +1,205 @@
+// @zubra/runtime: what compiled components and their scripts use.
+import type { Signal } from './signal.js';
+
+export { Signal, isNative } from './signal.js';
+export { effect, scope, flush, tick, type Cleanup, type Scope } from './effect.js';
+
+/** A value, or a signal holding one: what templates and most hooks accept. */
+export type MaybeSignal<T> = T | Signal.State<T> | Signal.Computed<T>;
+
+// ---- state ----------------------------------------------------------------------------------
+
+/**
+ * A writable signal (`Signal.State`). An array or plain object is held as a reactive proxy, so
+ * mutating it (`push`, `splice`, a property write) updates what read that property; `raw()` gives
+ * the original back.
+ */
+export declare function state<T>(value: T, options?: Signal.Options<T>): Signal.State<T>;
+/** The original object behind reactive state's proxy, or the value itself. */
+export declare function raw<T>(value: T): T;
+/** A derived signal (`Signal.Computed`); what it reads is tracked automatically. */
+export declare function computed<T>(fn: () => T, options?: Signal.Options<T>): Signal.Computed<T>;
+/** Call `callback(next, previous)` when `source` changes (not on the first run). */
+export declare function watch<T>(source: (() => T) | MaybeSignal<T>, callback: (next: T, previous: T) => void): void;
+
+/** Async data as signals; see `resource()`. Awaitable: resolves to the current run's value. */
+export interface Resource<T> extends PromiseLike<T> {
+  /** The latest run's value (or `initial`); kept while the next run is pending. */
+  readonly value: T | undefined;
+  readonly error: unknown;
+  readonly status: 'pending' | 'ready' | 'error';
+  readonly loading: boolean;
+  /** Run the fetcher again. */
+  refresh(): void;
+}
+/**
+ * Run `fetcher` now and whenever a signal it read before its first `await` changes; a new run
+ * (or the element's removal) aborts the previous one through `signal`.
+ */
+export declare function resource<T>(fetcher: (context: { signal: AbortSignal }) => T | PromiseLike<T>, options?: { initial?: T }): Resource<T>;
+
+// ---- lifecycle and the element (call during setup) -----------------------------------------
+
+/** Run when the element is connected; may return a cleanup for when it is disconnected. */
+export declare function onMount(fn: () => void | (() => void)): void;
+/** Run when the element is disconnected. */
+export declare function onUnmount(fn: () => void): void;
+/** An id unique to this element and call, for `id`/`for`/`aria-*` attributes. */
+export declare function id(): string;
+/** The component's props: reading one tracks it; writing one updates the element. */
+export declare function props<P extends object = Record<string, unknown>>(): P;
+/** The element whose setup is running. */
+export declare function host<E extends HTMLElement = HTMLElement>(): E;
+/**
+ * Fire a DOM event from the component (a bubbling `CustomEvent` with `detail`). The compiler
+ * declares every event it sees. Returns false if a listener called `preventDefault()` on a
+ * cancelable (`before…`) event.
+ */
+export declare function emit(name: string, detail?: unknown): boolean;
+
+/**
+ * The signal itself, where a script passes a signal `const` along: `watch(signal(count), …)`.
+ * The identity function; since 3.0, where a signal `const` in a script means its value, it keeps
+ * meaning the signal.
+ */
+export declare function signal<T>(value: T): T;
+
+/**
+ * Whether content was given for a slot (`'default'` for the default slot), as a signal that
+ * follows the content. Read it like a value in the template: `<zb-if test={hasFooter}>`.
+ */
+export declare function hasSlot(name?: string): Signal.State<boolean>;
+/** False while the element's markup is the server's (and on the server); true once it has started. The host also gets `:state(hydrated)`. */
+export declare function hydrated(): Signal.State<boolean>;
+/**
+ * State that follows a prop until it's assigned, and starts over when the prop changes:
+ * `let left = from(seconds)` in a `.zb` script. With a second argument, it starts as that
+ * value instead: `let running = from(seconds, false)`. Elsewhere, pass functions or signals.
+ */
+export declare function from<T>(source: T | (() => T) | Signal.State<T> | Signal.Computed<T>): Signal.Computed<T> & { set(value: T): void };
+export declare function from<T>(source: unknown, start: T | (() => T) | Signal.State<T> | Signal.Computed<T>): Signal.Computed<T> & { set(value: T): void };
+
+/**
+ * In a JSX component's parameters, `value = model(0)` makes `value` two-way: assigning it fires
+ * `valuechange` (like `value:model={0}` in `.zb`). Returns its argument.
+ */
+export declare function model<T>(value: T): T;
+
+// ---- event helpers (the template's event modifiers, as functions) ---------------------------
+
+type Handler<E extends Event = Event> = (this: unknown, event: E) => unknown;
+/** A handler that calls `event.preventDefault()` first (`.prevent`). */
+export declare function prevent<E extends Event>(fn?: Handler<E>): Handler<E>;
+/** A handler that calls `event.stopPropagation()` first (`.stop`). */
+export declare function stop<E extends Event>(fn?: Handler<E>): Handler<E>;
+/** A handler that ignores events from inside the element (`.self`). */
+export declare function selfOnly<E extends Event>(fn?: Handler<E>): Handler<E>;
+/** A handler that submits the element's form after `fn` runs (`.submit`), with validation. */
+export declare function submit<E extends Event>(fn?: (event: E) => unknown): (event: E) => unknown;
+/**
+ * A keyboard handler for `'enter'`, `'shift+enter'`, `'ctrl+k'`, … (several: `'enter, space'`).
+ * The modifier keys named must be held, and the others not.
+ */
+export declare function keys(combinations: string, fn?: Handler<KeyboardEvent>): Handler<KeyboardEvent>;
+
+// ---- styles ---------------------------------------------------------------------------------
+
+/**
+ * Add stylesheets (CSS text or `CSSStyleSheet`s) to every zubra shadow root, now and later: for
+ * app-wide CSS such as Tailwind's output, which page styles can't carry into shadow DOM.
+ * Light-DOM components already get page CSS.
+ */
+export declare function adoptStyles(...styles: (string | CSSStyleSheet)[]): CSSStyleSheet[];
+
+// ---- context (the Web Components Community Group Context Protocol) -------------------------
+
+export interface Context<T> {
+  readonly defaultValue: T;
+}
+/** A context key, with the value consumers get when no provider answers. */
+export declare function createContext<T>(defaultValue: T): Context<T>;
+/** Provide `value` for `context` to every element inside this one. */
+export declare function provide<T>(context: Context<T> | unknown, value: MaybeSignal<T>): void;
+/** Read `context` from the nearest provider above this element, as a signal. */
+export declare function inject<T>(context: Context<T>, fallback?: T): Signal.Computed<T>;
+export declare function inject<T = unknown>(context: unknown, fallback?: T): Signal.Computed<T>;
+
+export declare class ContextRequestEvent<T = unknown> extends Event {
+  constructor(context: unknown, contextTarget: Element, callback: (value: T, unsubscribe?: () => void) => void, subscribe?: boolean);
+  readonly context: unknown;
+  readonly contextTarget: Element;
+  readonly callback: (value: T, unsubscribe?: () => void) => void;
+  readonly subscribe?: boolean;
+}
+export declare class ContextProviderEvent extends Event {
+  constructor(context: unknown, contextTarget: Element);
+  readonly context: unknown;
+  readonly contextTarget: Element;
+}
+
+// ---- form-associated components (`form-associated` on the host) ---------------------------
+
+/** What the form submits for this control: follows `source`. */
+export declare function formValue(source: MaybeSignal<string | number | File | FormData | null | undefined> | (() => unknown)): void;
+/** Validation: `check()` returns an error message, or '' / null when the value is valid. */
+export declare function validity(check: () => string | null | undefined | MaybeSignal<string | null | undefined>): void;
+export declare function onFormReset(fn: () => void): void;
+export declare function onFormRestore(fn: (state: string | File | FormData | null, mode: 'restore' | 'autocomplete') => void): void;
+export declare function onFormDisabled(fn: (disabled: boolean) => void): void;
+
+// ---- what compiled code uses ---------------------------------------------------------------
+
+export interface PropSpec {
+  attribute: string;
+  default: unknown;
+  required?: boolean;
+}
+
+/** What adapters and tools read from a compiled element class (`Element.zb`). */
+export interface ElementMeta {
+  readonly tag: string;
+  readonly props: Readonly<Record<string, Readonly<Required<PropSpec>>>>;
+  readonly events: readonly string[];
+  readonly slots: readonly string[];
+  readonly shadow: boolean;
+  readonly form: boolean;
+  /** The component has a `<style>` (light DOM: slotted content is marked `data-zb-slotted`). */
+  readonly styled: boolean;
+}
+
+export interface ZubraElementClass<E extends HTMLElement = HTMLElement> {
+  new (): E & { readonly updateComplete: Promise<void> };
+  readonly zubra: ElementMeta;
+  readonly formAssociated: boolean;
+  readonly observedAttributes: string[];
+}
+
+export interface Definition {
+  props?: Record<string, PropSpec>;
+  template?: string;
+  shadow?: boolean;
+  form?: boolean;
+  slots?: string[];
+  events?: string[];
+  /** The component has a `<style>`. */
+  styled?: boolean;
+  /** Its stylesheet, when the module carries it (otherwise the bundler adds it to the page). */
+  styles?: string | CSSStyleSheet | null;
+  /** Runs once per element; returns the template's parts. */
+  setup?: (props: Record<string, unknown>, emit: (name: string, detail?: unknown) => boolean) => unknown[];
+}
+
+/**
+ * @internal Register a compiled component: what the compiler's JavaScript output calls. Its
+ * arguments are the compiled-code interface, version `ABI`, not a public API.
+ */
+export declare function $define(tag: string, definition: Definition & { abi: number }): ZubraElementClass;
+/** The compiled-code interface version this runtime implements. */
+export declare const ABI: number;
+
+/** Whether a URL is safe for `href`/`src`: relative, or http(s), mailto or tel. */
+export declare function isSafeUrl(value: string): boolean;
+/** @internal Read a value that may be a signal. */
+export declare function $r<T>(value: MaybeSignal<T>): T;
+/** @internal A value as template text. */
+export declare function $t(value: unknown): string;

package/types/primitives.d.ts

@@ -0,0 +1,15 @@
+/**
+ * One tab stop for a group of items, with the arrow keys, Home and End moving focus among them
+ * (the roving tabindex). Returns a cleanup.
+ */
+export declare function rovingFocus(
+  container: Element,
+  options: { selector: string; orientation?: 'vertical' | 'horizontal' | 'both'; loop?: boolean; onMove?: (item: HTMLElement) => void },
+): () => void;
+/**
+ * Type to jump to the next item whose text starts with what was typed. Returns a cleanup.
+ */
+export declare function typeahead(
+  container: Element,
+  options: { selector: string; text?: (item: HTMLElement) => string; timeout?: number; onMatch?: (item: HTMLElement) => void },
+): () => void;

package/types/react.d.ts

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+import type { ZubraElementClass } from './index.js';
+
+/**
+ * A zubra element as a React component (React 18 and 19): props as properties, `on<Event>`
+ * handlers for its events, other props and children passed to the element. The build plugin's
+ * generated typings give exact prop types; this one is general.
+ */
+export declare function wrap<E extends HTMLElement>(
+  Element: ZubraElementClass<E>,
+): React.ForwardRefExoticComponent<
+  React.HTMLAttributes<E> & Record<string, unknown> & { children?: React.ReactNode } & React.RefAttributes<E>
+> & { readonly element: ZubraElementClass<E> };

package/types/server.d.ts

@@ -0,0 +1,27 @@
+import type { ZubraElementClass } from './index.js';
+
+export interface RenderOptions {
+  /** The element's prop values (JSON). */
+  props?: Record<string, unknown>;
+  /** Other attributes for the host (`class`, `id`, …). `true` writes a boolean attribute; `false` and nullish are left out. */
+  attributes?: Record<string, string | number | boolean | null | undefined>;
+  /** Supplied content by slot name (`default` for unnamed content), as HTML. */
+  slots?: Record<string, string>;
+}
+
+/** Register how to server-render `tag`. Called by the build plugin's server output. */
+export declare function registerRenderer(tag: string, render: (props: Record<string, unknown>, slots: Record<string, string>) => string): void;
+/** Whether `Element` is a zubra element that can be rendered here. */
+export declare function canRender(Element: unknown): Element is ZubraElementClass;
+/** The element's server-rendered HTML, which it hydrates in the browser. */
+export declare function renderToString(Element: ZubraElementClass, options?: RenderOptions): string;
+/**
+ * An element's server-rendered content for a host a framework renders bare: a shadow-DOM
+ * element's declarative shadow root, or a light-DOM element's rendered children, plus a form
+ * control's hidden fallback input when `name` is given. Empty when it can't be rendered here.
+ * The React and Vue wrappers use it; a framework must leave the host's content alone while
+ * hydrating (`dangerouslySetInnerHTML`, `innerHTML`).
+ */
+export declare function serverContent(Element: ZubraElementClass, options?: { props?: Record<string, unknown>; name?: string }): string;
+/** `serverContent` for a shadow-DOM element only (the 2.11 name). */
+export declare function shadowContent(Element: ZubraElementClass, options?: { props?: Record<string, unknown>; name?: string }): string;

package/types/signal.d.ts

@@ -0,0 +1,46 @@
+// The TC39 Signals API (https://github.com/tc39/proposal-signals): the platform's own when the
+// browser has it, otherwise zubra's implementation.
+
+export declare namespace Signal {
+  interface Options<T> {
+    /** When two values count as the same (no change): `Object.is` by default. */
+    equals?: (this: AnySignal<T>, a: T, b: T) => boolean;
+    [Signal.subtle.watched]?: (this: AnySignal<T>) => void;
+    [Signal.subtle.unwatched]?: (this: AnySignal<T>) => void;
+  }
+
+  type AnySignal<T = any> = State<T> | Computed<T>;
+  type AnySink = Computed<any> | subtle.Watcher;
+
+  class State<T> {
+    constructor(initialValue: T, options?: Options<T>);
+    get(): T;
+    set(value: T): void;
+  }
+
+  class Computed<T> {
+    constructor(computation: (this: Computed<T>) => T, options?: Options<T>);
+    get(): T;
+  }
+
+  namespace subtle {
+    function untrack<T>(fn: () => T): T;
+    function currentComputed(): Computed<any> | undefined;
+    function introspectSources(sink: AnySink): AnySignal[];
+    function introspectSinks(signal: AnySignal): AnySink[];
+    function hasSinks(signal: AnySignal): boolean;
+    function hasSources(signal: AnySink): boolean;
+    const watched: unique symbol;
+    const unwatched: unique symbol;
+
+    class Watcher {
+      constructor(notify: (this: Watcher) => void);
+      watch(...signals: AnySignal[]): void;
+      unwatch(...signals: AnySignal[]): void;
+      getPending(): AnySignal[];
+    }
+  }
+}
+
+/** True when the browser provides `Signal` natively. */
+export declare const isNative: boolean;

package/types/spread.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The binder for `{...spread}` in compiled components (imported by the compiler's output when a
+ * template spreads an object). Not called by hand.
+ */
+export declare function spread(part: { spread: () => unknown; own?: string[] }, node: Element): void;

package/types/vue.d.ts

@@ -0,0 +1,8 @@
+import type { DefineComponent } from 'vue';
+import type { ElementMeta, ZubraElementClass } from './index.js';
+
+/** A zubra element as a Vue 3 component: props, events, `v-model` from `<prop>change` pairs. */
+export declare function wrap(Element: ZubraElementClass): DefineComponent<Record<string, unknown>>;
+
+/** The component's two-way bindings: `<prop>` + `<prop>change` pairs. */
+export declare function models(meta: Pick<ElementMeta, 'props' | 'events'>): { prop: string; event: string }[];

package/types/zag.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Run a Zag.js machine for this element: started when it connects, stopped when it disconnects
+ * (a fresh machine each time it connects). `props` is the machine's props, or a function returning
+ * them. `current` is the machine's service, read reactively: pass it to the machine's `connect()`
+ * inside a `computed`.
+ */
+export declare function useMachine<Service = any>(machine: unknown, props?: Record<string, unknown> | (() => Record<string, unknown>)): { readonly current: Service };
+/** Zag's prop normalizer for the DOM (attribute names, lowercased listeners): pass it to `connect()`. */
+export { normalizeProps } from '@zag-js/vanilla';