@zubra/runtime 5.7.0 → 5.9.0

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/effect.d.ts

@@ -1,15 +1,28 @@
+/**
+ * `[Symbol.dispose]()`, so `using` and `DisposableStack` accept it, when the project's `lib`
+ * has Explicit Resource Management (`esnext.disposable`, or `esnext`); nothing otherwise, so
+ * older `lib` settings still type-check.
+ */
+export type Disposal = SymbolConstructor extends { readonly dispose: infer K extends symbol }
+  ? { [P in K]: () => void }
+  : {};
+
 /** 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.
+ * the effect, and is also disposable (`using stop = effect(…)`). Effects created inside another
+ * effect or scope belong to it.
  */
-export declare function effect(fn: () => void | Cleanup): () => void;
+export declare function effect(fn: () => void | Cleanup): (() => void) & Disposal;
 
-/** An ownership root: disposing, pausing or resuming it applies to every effect inside. */
-export interface Scope {
+/**
+ * An ownership root: disposing, pausing or resuming it applies to every effect inside. It's
+ * disposable too (`using s = scope(…)`); pausing isn't disposal, and a paused scope resumes.
+ */
+export interface Scope extends Disposal {
   run<T>(fn: () => T): T;
   dispose(): void;
   pause(): void;

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/index.d.ts

@@ -2,7 +2,8 @@
 import type { Signal } from './signal.js';
 
 export { Signal, isNative } from './signal.js';
-export { effect, scope, flush, tick, type Cleanup, type Scope } from './effect.js';
+export { effect, scope, flush, tick, type Cleanup, type Disposal, type Scope } from './effect.js';
+import type { Disposal } 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>;
@@ -23,7 +24,7 @@ export declare function computed<T>(fn: () => T, options?: Signal.Options<T>): S
 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> {
+export interface Resource<T> extends PromiseLike<T>, Disposal {
   /** The latest run's value (or `initial`); kept while the next run is pending. */
   readonly value: T | undefined;
   readonly error: unknown;
@@ -31,6 +32,8 @@ export interface Resource<T> extends PromiseLike<T> {
   readonly loading: boolean;
   /** Run the fetcher again. */
   refresh(): void;
+  /** Stop: abort the run in flight and never run again. `using` does this through `Symbol.dispose`. */
+  dispose(): void;
 }
 /**
  * Run `fetcher` now and whenever a signal it read before its first `await` changes; a new run
@@ -55,7 +58,7 @@ export declare function host<E extends HTMLElement = HTMLElement>(): E;
  * 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;
+export declare function emit<Detail = unknown>(name: string, detail?: Detail): boolean;
 
 /**
  * The signal itself, where a script passes a signal `const` along: `watch(signal(count), …)`.

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/track.d.ts

@@ -0,0 +1,19 @@
+// @zubra/runtime/track: reads after an `await` in a resource's fetcher.
+
+/** What a fetcher wrapped by `tracked()` is given for each run. */
+export interface TrackedRun {
+  /** Aborted when a newer run starts or the resource is disposed. */
+  signal: AbortSignal;
+  /**
+   * Read signals and follow them, after an `await` too: when what `read` returns changes, the
+   * resource runs the fetcher again. A replaced run still reads, without subscribing.
+   */
+  track<V>(read: () => V): V;
+}
+
+/**
+ * Wraps a resource's fetcher so it is also given `track()`:
+ * `resource(tracked(async ({ signal, track }) => …))`. The compiler writes it for an async
+ * fetcher in a `.zb` script.
+ */
+export declare function tracked<T>(fetcher: (run: TrackedRun) => T | PromiseLike<T>): (context: { signal: AbortSignal }) => T | PromiseLike<T>;

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 };