@zubra/runtime 5.7.0 → 5.8.0

package/src/testing.js

@@ -0,0 +1,153 @@
+// Testing helpers: mount a Zubra component the way each framework's consumers do, so a library
+// author can run one test through plain HTML, React and Vue, in any browser test runner (Vitest
+// browser mode, Web Test Runner, Playwright's own).
+//
+//   import { frameworks, mount } from '@zubra/runtime/testing';
+//   import StarRating from './star-rating.zb';
+//
+//   for (const framework of await frameworks()) {
+//     test(`${framework}: a click sets the value and fires valuechange`, async () => {
+//       const view = await mount(StarRating, { framework, props: { value: 2 } });
+//       view.element.querySelector('button:nth-of-type(4)').click();
+//       expect(view.events('valuechange')).toEqual([4]);
+//       await view.set({ value: 1 });                 // through the framework, as an app would
+//       expect(view.element.value).toBe(1);
+//       view.unmount();
+//     });
+//   }
+//
+// A `<prop>change` event updates the prop the framework passes, as an app binding it two-way
+// would (`v-model`, React's controlled pattern). React and Vue are imported only when asked for, through the same adapters apps use
+// (`@zubra/runtime/react`, `@zubra/runtime/vue`), so events reach the framework's own handlers,
+// props are set the framework's way, and slots are the framework's children.
+
+const ALL = ['html', 'react', 'vue'];
+
+/** The frameworks that can be mounted here: plain HTML always, React and Vue when installed. */
+export async function frameworks() {
+  const found = ['html'];
+  for (const name of ['react', 'vue']) {
+    try {
+      await load(name);
+      found.push(name);
+    } catch {
+      // not installed: skipped
+    }
+  }
+  return found;
+}
+
+const loaded = {};
+function load(framework) {
+  if (framework === 'react') {
+    loaded.react ??= Promise.all([import('react'), import('react-dom'), import('react-dom/client'), import('./react.js')])
+      .then(([React, ReactDOM, client, adapter]) => ({ React, flushSync: ReactDOM.flushSync, createRoot: client.createRoot, wrap: adapter.wrap }));
+    return loaded.react;
+  }
+  if (framework === 'vue') {
+    loaded.vue ??= Promise.all([import('vue'), import('./vue.js')]).then(([Vue, adapter]) => ({ Vue, wrap: adapter.wrap }));
+    return loaded.vue;
+  }
+  return Promise.resolve(null);
+}
+
+// What the element is doing once a change has landed: its own render, and the framework's.
+const settle = async (element) => {
+  await new Promise((resolve) => setTimeout(resolve));
+  await element?.updateComplete;
+};
+
+/**
+ * Mount `Element` (a compiled component's default export) through `framework` (`html`, `react` or
+ * `vue`), with `props` and `slots` (`{ default: 'text', title: 'Heading' }`: text for each slot).
+ * Resolves once it has rendered, to:
+ * - `element`: the component's host element;
+ * - `events(name)`: the `detail` of each `name` event so far, as the framework's handler got it
+ *   (`events()`: every event as `[name, detail]`);
+ * - `set(props)`: change props through the framework (merged with the current ones), and settle;
+ * - `unmount()`: remove it the framework's way.
+ */
+export async function mount(Element, { framework = 'html', props = {}, slots = {}, container } = {}) {
+  const meta = Element?.zubra;
+  if (!meta) throw new TypeError('zubra: mount() needs a compiled zubra element (the default export of a .zb module)');
+  if (!ALL.includes(framework)) throw new TypeError(`zubra: mount() knows ${ALL.join(', ')}, not "${framework}"`);
+  if (!customElements.get(meta.tag)) customElements.define(meta.tag, Element);
+  const host = container ?? document.body.appendChild(document.createElement('div'));
+  const log = [];
+  // Like an app that binds the component two-way (`v-model`, React's controlled pattern): a
+  // `<prop>change` event updates the prop the framework passes back, so its next render doesn't
+  // put the old value back.
+  const models = Object.fromEntries(Object.keys(meta.props).filter((name) => meta.events.includes(`${name.toLowerCase()}change`)).map((name) => [`${name.toLowerCase()}change`, name]));
+  let model = () => {};
+  const record = (name) => (event) => {
+    log.push([name, event.detail]);
+    if (models[name]) model(models[name], event.detail);
+  };
+  let current = { ...props };
+  let view;
+
+  if (framework === 'html') {
+    const element = document.createElement(meta.tag);
+    for (const [name, value] of Object.entries(current)) element[name] = value;
+    for (const name of meta.events) element.addEventListener(name, record(name));
+    for (const [name, text] of Object.entries(slots)) {
+      if (name === 'default') element.append(text);
+      else element.append(Object.assign(document.createElement('span'), { slot: name, textContent: text }));
+    }
+    host.append(element);
+    view = {
+      element,
+      set: async (next) => { Object.assign(current, next); for (const [name, value] of Object.entries(next)) element[name] = value; },
+      unmount: () => element.remove(),
+    };
+  } else if (framework === 'react') {
+    const { React, flushSync, createRoot, wrap } = await load('react');
+    const Component = wrap(Element);
+    const handlers = Object.fromEntries(meta.events.map((name) => [`on${name}`, record(name)]));
+    const children = Object.entries(slots).map(([name, text]) =>
+      name === 'default' ? text : React.createElement('span', { key: name, slot: name }, text));
+    let element = null;
+    const ref = (node) => { if (node) element = node; };
+    const root = createRoot(host);
+    const render = () => flushSync(() => root.render(React.createElement(Component, { ...current, ...handlers, ref }, ...children)));
+    model = (name, value) => { current[name] = value; queueMicrotask(render); };
+    render();
+    view = {
+      get element() { return element; },
+      set: async (next) => { Object.assign(current, next); render(); },
+      unmount: () => root.unmount(),
+    };
+  } else {
+    const { Vue, wrap } = await load('vue');
+    const Component = wrap(Element);
+    const state = Vue.reactive({ ...current });
+    model = (name, value) => { current[name] = value; state[name] = value; };
+    const handlers = Object.fromEntries(meta.events.map((name) => [`on${name[0].toUpperCase()}${name.slice(1)}`, record(name)]));
+    const slotFunctions = Object.fromEntries(Object.entries(slots).map(([name, text]) => [name, () => (name === 'default' ? text : Vue.h('span', text))]));
+    const component = Vue.ref(null);
+    const app = Vue.createApp({ render: () => Vue.h(Component, { ...state, ...handlers, ref: component }, slotFunctions) });
+    app.mount(host);
+    view = {
+      get element() { return component.value?.element ?? null; },
+      set: async (next) => { Object.assign(current, next); Object.assign(state, next); await Vue.nextTick(); },
+      unmount: () => app.unmount(),
+    };
+  }
+
+  await settle(view.element);
+  const element = () => view.element;
+  return {
+    framework,
+    host,
+    get element() { return element(); },
+    events: (name) => (name === undefined ? log.slice() : log.filter(([event]) => event === name).map(([, detail]) => detail)),
+    async set(next) {
+      await view.set(next);
+      await settle(element());
+    },
+    unmount() {
+      view.unmount();
+      if (!container) host.remove();
+    },
+  };
+}

package/src/vue.js

@@ -12,8 +12,11 @@
 //   `v-model:<prop>`, and `v-model` binds the `value` pair (or the only pair, if there's one).
 // - Other attributes and listeners (class, style, @click, …) go to the element; slots become its
 //   children, named slots with `slot="name"`.
-import { defineComponent, h, withDirectives, Text, Comment, Fragment } from 'vue';
+import { defineComponent, h, withDirectives, Text, Comment, Fragment, customRef, getCurrentScope, onScopeDispose } from 'vue';
 import { serverContent } from './server.js';
+import { routeLinks } from './navigation.js';
+import './context.js';
+import { subscribe, read, writable } from './bridge.js';
 
 const clone = (value) => (value && typeof value === 'object' ? structuredClone(value) : value);
 const pascal = (tag) => tag.split(/[-.]/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('');
@@ -123,3 +126,66 @@ export function wrap(Element) {
     },
   });
 }
+
+/**
+ * Route links inside Zubra components through Vue Router (or any `push`) until the current effect
+ * scope ends: `useRouteLinks((to) => router.push(to))` in a component's `setup`. Returns the
+ * function that stops it.
+ */
+export function useRouteLinks(navigate, options) {
+  const stop = routeLinks(navigate, options);
+  if (getCurrentScope()) onScopeDispose(stop);
+  return stop;
+}
+
+/**
+ * Provide a Context Protocol value to every element inside: an app's theme, locale or current user,
+ * read by components with `inject(context)` (or Lit's `@consume`).
+ *
+ *   <ZubraContext :context="theme" :value="dark ? 'dark' : 'light'">…</ZubraContext>
+ *
+ * `value` can also be a signal. It renders a `<zb-context>` element, which is `display: contents`.
+ */
+export const ZubraContext = defineComponent({
+  name: 'ZubraContext',
+  props: { context: { default: undefined }, value: { default: undefined } },
+  setup(given, { slots }) {
+    // Set as DOM properties when the element is created, before its children are inserted.
+    return () => h('zb-context', { '.context': given.context, '.value': given.value, style: 'display: contents' }, slots.default?.());
+  },
+});
+
+/**
+ * A Zubra signal (or a function of signals) as a Vue ref: reading `.value` tracks it in
+ * templates, computeds and watchers, and assigning `.value` writes the signal when it's writable
+ * (a `Signal.State`, `state()`, `from()`), so `v-model="cart"` works on one.
+ *
+ *   const items = useSignal(cart, { deep: true })
+ *
+ * The subscription ends with the effect scope it was created in (the component's `setup`); outside
+ * one, call `stop()` on the ref when done. With `deep: true` a mutation inside an array or object
+ * triggers too.
+ */
+export function useSignal(source, { deep = false } = {}) {
+  let stop = () => {};
+  const ref = customRef((track, trigger) => {
+    let first = true;
+    stop = subscribe(source, () => {
+      if (first) first = false;
+      else trigger();
+    }, { deep });
+    return {
+      get() {
+        track();
+        return read(source);
+      },
+      set(value) {
+        if (!writable(source)) throw new TypeError('zubra: useSignal(): this signal is read-only (a computed); write the state it reads');
+        source.set(value);
+      },
+    };
+  });
+  Object.defineProperty(ref, 'stop', { value: () => stop() });
+  if (getCurrentScope()) onScopeDispose(() => stop());
+  return ref;
+}

package/types/bridge.d.ts

@@ -0,0 +1,44 @@
+import type { Signal } from './signal.js';
+
+/** A signal, or a function that reads signals (tracked like a computed). */
+export type SignalSource<T> = Signal.State<T> | Signal.Computed<T> | (() => T);
+
+export interface BridgeOptions {
+  /** Also notify when something inside an array or plain object changes (`items.push(x)`). */
+  deep?: boolean;
+}
+
+/** An unsubscribe function that is also an RxJS-style `Unsubscribable`. */
+export interface Unsubscribe {
+  (): void;
+  unsubscribe(): void;
+}
+
+/**
+ * The Svelte store contract and an RxJS-style Subscribable at once: Svelte's `$store`, Solid's
+ * `from`, Angular's `toSignal` and RxJS's `from` take it as it is.
+ */
+export interface SignalStore<T> {
+  /** The current value. */
+  get(): T;
+  /** Call `run` now and on each change. */
+  subscribe(run: ((value: T) => void) | { next?(value: T): void }): Unsubscribe;
+}
+
+/** A store over a writable signal: also a Svelte writable store. */
+export interface WritableSignalStore<T> extends SignalStore<T> {
+  set(value: T): void;
+  update(fn: (value: T) => T): void;
+}
+
+/** Call `callback(value)` now and on each change (batched per microtask) until unsubscribed. */
+export declare function subscribe<T>(source: SignalSource<T>, callback: (value: T) => void, options?: BridgeOptions): () => void;
+
+/** The source as a store. Writable (`set`, `update`) when the source is a `Signal.State` or has `set`. */
+export declare function toStore<T>(source: Signal.State<T>, options?: BridgeOptions): WritableSignalStore<T>;
+export declare function toStore<T>(source: SignalSource<T>, options?: BridgeOptions): SignalStore<T>;
+
+/** The source's current value. */
+export declare function read<T>(source: SignalSource<T>): T;
+/** Whether the source can be written. */
+export declare function writable(source: unknown): boolean;

package/types/context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<zb-context>`: answers the Context Protocol for the elements inside it. Set `context` (a key
+ * from `createContext()`, or any protocol key) and `value` (a value or a signal).
+ */
+export declare class ZubraContextElement extends HTMLElement {
+  context: unknown;
+  value: unknown;
+}
+
+/** Define `<zb-context>` (done on import; a no-op without `customElements`). */
+export declare function defineContextElement(): void;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zb-context': ZubraContextElement;
+  }
+}

package/types/forms.d.ts

@@ -0,0 +1,37 @@
+/** The model prop of a Zubra control (`value` by default), with its `<prop>change` event. */
+export interface FieldOptions {
+  prop?: string;
+}
+
+/** React Hook Form's `register(name)` result (the parts used). */
+export interface Registration {
+  name: string;
+  ref: unknown;
+  onChange(event: { type: string; target: { name: string; value: unknown } }): unknown;
+  onBlur(event: { type: string; target: { name: string; value: unknown } }): unknown;
+  disabled?: boolean;
+}
+
+/** React Hook Form's `register(name)` as props for a wrapped Zubra control (model: `value`). */
+export declare function registerProps(registration: Registration): Record<string, unknown>;
+
+/** A React Hook Form `<Controller>` field, or a TanStack Form field API. */
+export type ReactField =
+  | { name: string; value: unknown; onChange(value: unknown): void; onBlur(): void; ref?: unknown }
+  | { name: string; state: { value: unknown }; handleChange(value: any): void; handleBlur(): void };
+
+/** A field's props for a wrapped Zubra control in React. */
+export declare function fieldProps(field: ReactField, options?: FieldOptions): Record<string, unknown>;
+
+/** A field's props for a wrapped Zubra control in Vue, from VeeValidate's `useField()` or a `<Field>` slot's `field`. */
+export declare function vueFieldProps(field: object, options?: FieldOptions): Record<string, unknown>;
+
+/** Felte's `createField(name)` result (the parts used). */
+export interface FelteField {
+  field(node: HTMLElement): { destroy?(): void } | void;
+  onInput(value: unknown): void;
+  onBlur(): void;
+}
+
+/** Connect a Zubra control to a Felte field: a Svelte action, or call it with the element. */
+export declare function felteControl(node: HTMLElement, field: FelteField, options?: FieldOptions): { destroy(): void };

package/types/navigation.d.ts

@@ -0,0 +1,22 @@
+/** What a router is told about a routed link. */
+export interface RoutedLink {
+  event: MouseEvent;
+  anchor: HTMLAnchorElement;
+  url: URL;
+}
+
+export interface RouteLinksOptions {
+  /** Which ancestors make a link routed (default: a Zubra component's host). */
+  within?(node: Element): boolean;
+  /** Where to listen (default: the document). */
+  root?: Document | Element;
+}
+
+/** Whether `node` is a Zubra component's host. */
+export declare function isComponent(node: unknown): boolean;
+
+/**
+ * Route clicks on links inside Zubra components through `navigate(to)`, where `to` is the path,
+ * query and hash. Returns a function that stops it.
+ */
+export declare function routeLinks(navigate: (to: string, link: RoutedLink) => unknown, options?: RouteLinksOptions): () => void;

package/types/outlet.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<zb-outlet name="…" item={…}>` (experimental): a place in a component where the app's framework
+ * renders its own content for `item`, through a portal. The React adapter fills it from a
+ * `render<Name>` prop.
+ */
+export declare class ZubraOutletElement extends HTMLElement {
+  readonly name: string;
+  item: unknown;
+  /** Who renders into this outlet, once claimed. */
+  owner: { change(outlet: ZubraOutletElement): void; disconnect(outlet: ZubraOutletElement): void } | null;
+}
+
+/** The unclaimed outlets inside `host` (light DOM and shadow root). */
+export declare function outletsOf(host: Element): ZubraOutletElement[];
+
+/** Define `<zb-outlet>` (done on import; a no-op without `customElements`). */
+export declare function defineOutletElement(): void;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zb-outlet': ZubraOutletElement;
+  }
+}

package/types/react.d.ts

@@ -3,7 +3,8 @@ 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
+ * handlers for its events, other props and children passed to the element, and `render<Name>`
+ * props that fill the element's `<zb-outlet name>`s (experimental). The build plugin's
  * generated typings give exact prop types; this one is general.
  */
 export declare function wrap<E extends HTMLElement>(
@@ -11,3 +12,18 @@ export declare function wrap<E extends HTMLElement>(
 ): React.ForwardRefExoticComponent<
   React.HTMLAttributes<E> & Record<string, unknown> & { children?: React.ReactNode } & React.RefAttributes<E>
 > & { readonly element: ZubraElementClass<E> };
+
+/** Route links inside Zubra components through the app's router while mounted. */
+export declare function useRouteLinks(
+  navigate: (to: string, link: import('./navigation.js').RoutedLink) => unknown,
+  options?: import('./navigation.js').RouteLinksOptions,
+): void;
+
+/** Provide a Context Protocol value (or a signal) to every element inside; renders `<zb-context>`. */
+export declare function ZubraContext(props: { context: unknown; value: unknown; children?: React.ReactNode }): React.ReactElement;
+
+/**
+ * Read a Zubra signal (or a function of signals) in a React component, re-rendering when it
+ * changes. `deep: true` re-renders on mutations inside an array or object too.
+ */
+export declare function useSignal<T>(source: import('./bridge.js').SignalSource<T>, options?: import('./bridge.js').BridgeOptions): T;

package/types/testing.d.ts

@@ -0,0 +1,32 @@
+import type { ZubraElementClass } from './index.js';
+
+export type Framework = 'html' | 'react' | 'vue';
+
+/** The frameworks that can be mounted here: `html` always, `react` and `vue` when installed. */
+export declare function frameworks(): Promise<Framework[]>;
+
+export interface MountOptions {
+  framework?: Framework;
+  props?: Record<string, unknown>;
+  /** Text for each slot: `{ default: 'Body', title: 'Heading' }`. */
+  slots?: Record<string, string>;
+  /** Where to mount (default: a new <div> in <body>, removed on unmount). */
+  container?: HTMLElement;
+}
+
+export interface Mounted<E extends HTMLElement = HTMLElement> {
+  readonly framework: Framework;
+  readonly host: HTMLElement;
+  /** The component's host element. */
+  readonly element: E;
+  /** The `detail` of each `name` event so far, as the framework's handler got it; with no name, every event as `[name, detail]`. */
+  events(name: string): unknown[];
+  events(): [string, unknown][];
+  /** Change props through the framework (merged with the current ones), and settle. */
+  set(props: Record<string, unknown>): Promise<void>;
+  /** Remove it the framework's way. */
+  unmount(): void;
+}
+
+/** Mount a compiled component through plain HTML, the React adapter or the Vue adapter. */
+export declare function mount<E extends HTMLElement>(Element: ZubraElementClass<E>, options?: MountOptions): Promise<Mounted<E>>;

package/types/vue.d.ts

@@ -6,3 +6,18 @@ export declare function wrap(Element: ZubraElementClass): DefineComponent<Record
 
 /** The component's two-way bindings: `<prop>` + `<prop>change` pairs. */
 export declare function models(meta: Pick<ElementMeta, 'props' | 'events'>): { prop: string; event: string }[];
+
+/** Route links inside Zubra components through Vue Router (or any push) until the scope ends. */
+export declare function useRouteLinks(
+  navigate: (to: string, link: import('./navigation.js').RoutedLink) => unknown,
+  options?: import('./navigation.js').RouteLinksOptions,
+): () => void;
+
+/** Provide a Context Protocol value (or a signal) to every element inside; renders `<zb-context>`. */
+export declare const ZubraContext: DefineComponent<{ context: unknown; value: unknown }>;
+
+/**
+ * A Zubra signal (or a function of signals) as a Vue ref; assigning `.value` writes a writable
+ * signal. Stops with the current effect scope, or with `stop()`.
+ */
+export declare function useSignal<T>(source: import('./bridge.js').SignalSource<T>, options?: import('./bridge.js').BridgeOptions): import('vue').Ref<T> & { stop(): void };