@xmachines/play-dom 2.0.0 → 2.1.0

package/dist/create-play-ui.d.ts

@@ -1,16 +1,17 @@
 /**
- * createPlayUI — batteries-included DOM factory.
+ * createPlayUI — the complete DOM factory.
  *
- * Takes a `DefineRegistryResult` (the caller is responsible for calling
- * `defineRegistry`) and returns a `MountFn`. Calling `mount(actor, container)`
- * starts the renderer and returns a `disconnect` cleanup function.
+ * It takes a `DefineRegistryResult`, and the caller calls `defineRegistry` itself.
+ * It returns a `MountFn`. A `mount(actor, container)` call starts the renderer, and
+ * it returns a `disconnect` cleanup function.
  *
- * Factory-level options (`functions`, `validationFunctions`, `navigate`,
- * `onRenderError`, `fallback`) are closed over at creation time and applied on
- * every `mount()` call. Per-mount options (`store`, `loading`) can be passed
- * to the `mount()` call itself via `MountOptions`.
+ * The factory holds the factory options (`functions`, `validationFunctions`,
+ * `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and
+ * it applies them on every `mount()` call. Give the mount options (`store` and
+ * `loading`) to the `mount()` call itself, through `MountOptions`.
  *
- * Parallel to `<PlayUIProvider registryResult={...}>` in the framework renderers.
+ * This factory is parallel to `<PlayUIProvider registryResult={...}>` in the
+ * framework renderers.
  *
  * @example
  * ```typescript
@@ -36,50 +37,51 @@ import type { StateStore } from "@xmachines/json-render-core";
 import type { DefineRegistryResult } from "@xmachines/json-render-dom";
 import type { CreatePlayUIOptions } from "./types.js";
 /**
- * Per-mount options passed to the `MountFn` returned by `createPlayUI`.
+ * The mount options of the `MountFn` that `createPlayUI` returns.
  *
- * These override or supplement the factory-level options on a per-actor/container
- * basis. Factory-level options (`functions`, `validationFunctions`, `navigate`,
- * `onRenderError`, `fallback`) are set once when calling `createPlayUI`.
+ * They replace or complete the factory options, for one actor and one container.
+ * The `createPlayUI` call sets the factory options (`functions`,
+ * `validationFunctions`, `navigate`, `onRenderError`, and `fallback`) one time.
  */
 export interface MountOptions {
     /**
-     * Optional external `StateStore` (controlled mode).
-     * When omitted, a fresh `@xstate/store` atom is created per view transition
-     * seeded from `spec.state`.
+     * The optional external `StateStore`, which is the controlled mode.
+     * Without it, the renderer makes a new `@xstate/store` atom for each view
+     * transition, with the values of `spec.state`.
      */
     store?: StateStore;
     /**
-     * When `true`, suppresses missing-child warnings during streaming spec ingestion
-     * and exposes `ctx.ctx.loading` to component implementations.
+     * With the value `true`, the renderer stops each warning about an absent child
+     * during the ingestion of a streaming spec. It also gives `ctx.ctx.loading` to each
+     * component implementation.
      */
     loading?: boolean;
 }
 /**
- * The mount function returned by `createPlayUI`.
+ * The mount function that `createPlayUI` returns.
  *
- * Call with `(actor, container, mountOptions?)` to start the renderer.
- * Returns a `disconnect` cleanup function that stops rendering and clears
- * the container.
+ * Call it with `(actor, container, mountOptions?)` to start the renderer.
+ * It returns a `disconnect` cleanup function. That function stops the render and
+ * clears the container.
  */
 export type MountFn = (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: MountOptions) => () => void;
 /**
- * Create a batteries-included DOM renderer mount function.
+ * Creates the mount function of the complete DOM renderer.
  *
- * The caller is responsible for producing `registryResult` via `defineRegistry`.
- * `createPlayUI` closes over it and returns a `MountFn` that can be invoked
- * once per actor/container pair.
+ * The caller makes `registryResult` with `defineRegistry`. `createPlayUI` holds it,
+ * and it returns a `MountFn`. Call that function one time for each pair of an actor
+ * and a container.
  *
- * @param registryResult - Result from `defineRegistry()` — provides the registry
- *   and the lazy handlers factory.
- * @param options - Factory-level configuration (see {@link CreatePlayUIOptions}):
- *   - `functions`           — named compute functions for `$computed` prop expressions.
- *   - `directives`          — custom `$`-prefixed dynamic values resolved during prop resolution.
- *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
- *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
- *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections.
- *   - `fallback`            — element shown when the actor's initial view is `null`.
- * @returns `MountFn`: `(actor, container, mountOptions?) → disconnect`
+ * @param registryResult - The result of `defineRegistry()`. It gives the registry
+ *   and the factory of the handlers, which it builds late.
+ * @param options - The factory configuration. See {@link CreatePlayUIOptions}:
+ *   - `functions`           — the named compute functions of a `$computed` prop expression.
+ *   - `directives`          — your own dynamic values with a `$` prefix. The renderer resolves them with the props.
+ *   - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`.
+ *   - `navigate`            — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`.
+ *   - `onRenderError`       — the `(error, name)` handler of a component render error and of an action handler rejection.
+ *   - `fallback`            — the element to show when the first view of the actor is `null`.
+ * @returns The `MountFn`: `(actor, container, mountOptions?) → disconnect`
  */
 export declare function createPlayUI(registryResult: DefineRegistryResult, options?: CreatePlayUIOptions): MountFn;
 //# sourceMappingURL=create-play-ui.d.ts.map

package/dist/create-play-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-play-ui.d.ts","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CACrB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,YAAY,KAClB,MAAM,IAAI,CAAC;AAEhB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC3B,cAAc,EAAE,oBAAoB,EACpC,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CA6CT"}
+{"version":3,"file":"create-play-ui.d.ts","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CACrB,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,YAAY,KAClB,MAAM,IAAI,CAAC;AAEhB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC3B,cAAc,EAAE,oBAAoB,EACpC,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CA8CT"}

package/dist/create-play-ui.js

@@ -1,16 +1,17 @@
 /**
- * createPlayUI — batteries-included DOM factory.
+ * createPlayUI — the complete DOM factory.
  *
- * Takes a `DefineRegistryResult` (the caller is responsible for calling
- * `defineRegistry`) and returns a `MountFn`. Calling `mount(actor, container)`
- * starts the renderer and returns a `disconnect` cleanup function.
+ * It takes a `DefineRegistryResult`, and the caller calls `defineRegistry` itself.
+ * It returns a `MountFn`. A `mount(actor, container)` call starts the renderer, and
+ * it returns a `disconnect` cleanup function.
  *
- * Factory-level options (`functions`, `validationFunctions`, `navigate`,
- * `onRenderError`, `fallback`) are closed over at creation time and applied on
- * every `mount()` call. Per-mount options (`store`, `loading`) can be passed
- * to the `mount()` call itself via `MountOptions`.
+ * The factory holds the factory options (`functions`, `validationFunctions`,
+ * `navigate`, `onRenderError`, and `fallback`) from the moment of its creation, and
+ * it applies them on every `mount()` call. Give the mount options (`store` and
+ * `loading`) to the `mount()` call itself, through `MountOptions`.
  *
- * Parallel to `<PlayUIProvider registryResult={...}>` in the framework renderers.
+ * This factory is parallel to `<PlayUIProvider registryResult={...}>` in the
+ * framework renderers.
  *
  * @example
  * ```typescript
@@ -32,28 +33,29 @@
  */
 import { PlayRenderer } from "./PlayRenderer.js";
 /**
- * Create a batteries-included DOM renderer mount function.
+ * Creates the mount function of the complete DOM renderer.
  *
- * The caller is responsible for producing `registryResult` via `defineRegistry`.
- * `createPlayUI` closes over it and returns a `MountFn` that can be invoked
- * once per actor/container pair.
+ * The caller makes `registryResult` with `defineRegistry`. `createPlayUI` holds it,
+ * and it returns a `MountFn`. Call that function one time for each pair of an actor
+ * and a container.
  *
- * @param registryResult - Result from `defineRegistry()` — provides the registry
- *   and the lazy handlers factory.
- * @param options - Factory-level configuration (see {@link CreatePlayUIOptions}):
- *   - `functions`           — named compute functions for `$computed` prop expressions.
- *   - `directives`          — custom `$`-prefixed dynamic values resolved during prop resolution.
- *   - `validationFunctions` — custom validation functions; available at `ctx.ctx.validationFunctions`.
- *   - `navigate`            — navigation callback; invoked on `onSuccess: { navigate: "..." }`.
- *   - `onRenderError`       — `(error, name)` handler for component render errors and action handler rejections.
- *   - `fallback`            — element shown when the actor's initial view is `null`.
- * @returns `MountFn`: `(actor, container, mountOptions?) → disconnect`
+ * @param registryResult - The result of `defineRegistry()`. It gives the registry
+ *   and the factory of the handlers, which it builds late.
+ * @param options - The factory configuration. See {@link CreatePlayUIOptions}:
+ *   - `functions`           — the named compute functions of a `$computed` prop expression.
+ *   - `directives`          — your own dynamic values with a `$` prefix. The renderer resolves them with the props.
+ *   - `validationFunctions` — your own check functions. They are available at `ctx.ctx.validationFunctions`.
+ *   - `navigate`            — the navigation callback. The renderer calls it for `onSuccess: { navigate: "..." }`.
+ *   - `onRenderError`       — the `(error, name)` handler of a component render error and of an action handler rejection.
+ *   - `fallback`            — the element to show when the first view of the actor is `null`.
+ * @returns The `MountFn`: `(actor, container, mountOptions?) → disconnect`
  */
 export function createPlayUI(registryResult, options = {}) {
     const { onRenderError, fallback, functions, directives, validationFunctions, navigate, onConfirm, } = options;
     return function mount(actor, container, mountOptions) {
-        // All UIProviderOptions (onRenderError, functions, validationFunctions, navigate) are
-        // forwarded directly through PlayDomOptions → PlayRenderer → renderSpec → DomRenderContext.
+        // Each option of UIProviderOptions (onRenderError, functions, validationFunctions,
+        // and navigate) goes directly through PlayDomOptions, then PlayRenderer, then
+        // renderSpec, then DomRenderContext.
         const rendererOptions = {
             registryResult,
             ...(mountOptions?.store !== undefined && { store: mountOptions.store }),
@@ -67,9 +69,9 @@ export function createPlayUI(registryResult, options = {}) {
         };
         const renderer = new PlayRenderer(container, actor, registryResult.registry, rendererOptions);
         renderer.connect();
-        // Handle fallback for null view on initial mount.
-        // connect() calls _render() synchronously so the container is already populated
-        // at this point if actor.currentView is non-null.
+        // Handle the fallback of a null view on the first mount.
+        // connect() calls _render() synchronously. Therefore the container holds the view
+        // already at this point, when actor.currentView is not null.
         if (fallback != null && container.childNodes.length === 0) {
             container.appendChild(fallback);
         }

package/dist/create-play-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAsCjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,SAAS,GACT,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,sFAAsF;QACtF,4FAA4F;QAC5F,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,mBAAmB,EAAE,CAAC;YACjE,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC;SACrD,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAChC,SAAS,EACT,KAAK,EACL,cAAc,CAAC,QAAQ,EACvB,eAAe,CACf,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,kDAAkD;QAClD,gFAAgF;QAChF,kDAAkD;QAClD,IAAI,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,SAAS,UAAU;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-play-ui.js","sourceRoot":"","sources":["../src/create-play-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAuCjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC3B,cAAoC,EACpC,UAA+B,EAAE;IAEjC,MAAM,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,QAAQ,EACR,SAAS,GACT,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY;QACnD,mFAAmF;QACnF,8EAA8E;QAC9E,qCAAqC;QACrC,MAAM,eAAe,GAAG;YACvB,cAAc;YACd,GAAG,CAAC,YAAY,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC;YACvE,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7E,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;YAC/C,GAAG,CAAC,mBAAmB,KAAK,SAAS,IAAI,EAAE,mBAAmB,EAAE,CAAC;YACjE,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,CAAC;SACrD,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,YAAY,CAChC,SAAS,EACT,KAAK,EACL,cAAc,CAAC,QAAQ,EACvB,eAAe,CACf,CAAC;QACF,QAAQ,CAAC,OAAO,EAAE,CAAC;QAEnB,yDAAyD;QACzD,kFAAkF;QAClF,6DAA6D;QAC7D,IAAI,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,SAAS,UAAU;YACzB,QAAQ,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC,CAAC;IACH,CAAC,CAAC;AACH,CAAC"}

package/dist/create-renderer.d.ts

@@ -1,12 +1,12 @@
 /**
- * create-renderer.ts — createRenderer convenience factory for @xmachines/play-dom.
+ * create-renderer.ts — the createRenderer factory of @xmachines/play-dom.
  *
- * Mirrors the `createRenderer` export from @xmachines/json-render-react, /vue, /solid, /svelte.
- * Calls `defineRegistry` once at factory creation time and returns a
- * `mount(actor, container, options?)` function that wires up PlayRenderer and
- * returns a `disconnect` cleanup function.
+ * It matches the `createRenderer` export of @xmachines/json-render-react, of /vue,
+ * of /solid, and of /svelte. It calls `defineRegistry` one time, at the creation of
+ * the factory. It then returns a `mount(actor, container, options?)` function. That
+ * function connects a PlayRenderer, and it returns a `disconnect` cleanup function.
  *
- * Reduces consumer boilerplate from 3–4 steps to one call.
+ * The consumer therefore writes one call, and not three or four steps.
  *
  * @example
  * ```ts
@@ -40,13 +40,13 @@
  *   return el;
  * };
  *
- * // Build the factory once (at module scope)
+ * // Build the factory one time, at module scope
  * const mount = createRenderer(catalog, { Home, Login });
  *
- * // Mount when actor + container are ready
+ * // Mount when the actor and the container are ready
  * const disconnect = mount(actor, document.getElementById("app")!);
  *
- * // Cleanup:
+ * // Clean up:
  * disconnect();
  * ```
  *
@@ -58,24 +58,28 @@ import type { Catalog } from "@xmachines/json-render-core";
 import type { ComponentRegistry } from "@xmachines/json-render-dom";
 import type { PlayDomOptions } from "./types.js";
 /**
- * Create a reusable DOM renderer factory from a catalog and component map.
+ * Creates a DOM renderer factory from a catalog and a component map. You can use
+ * the factory more than one time.
  *
- * Returns a `mount(actor, container, options?)` function that wires up the
- * PlayRenderer in one call and returns a `disconnect` cleanup function.
+ * It returns a `mount(actor, container, options?)` function. That function connects
+ * the PlayRenderer in one call, and it returns a `disconnect` cleanup function.
  *
- * @param catalog      - The json-render Catalog describing component and action schemas.
- * @param componentMap - Component implementations keyed by catalog component name.
- * @returns A `mount` function that accepts `(actor, container, options?)` and returns `disconnect`.
+ * @param catalog      - The json-render Catalog. It describes the schema of each component and of each action.
+ * @param componentMap - The component implementations, with the catalog component name as the key.
+ * @returns A `mount` function. It accepts `(actor, container, options?)`, and it returns `disconnect`.
  *
  * @remarks
- * `createRenderer` manages `registryResult` internally — it calls `defineRegistry` once and
- * reuses the result across all `mount()` calls. The `mount` options type therefore excludes
- * `registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
+ * `createRenderer` manages `registryResult` internally. It calls `defineRegistry`
+ * one time, and it uses that result in every `mount()` call. Therefore the options
+ * type of `mount` holds no `registryResult`: `createRenderer` always gives it, and
+ * you cannot replace it.
  *
- * If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
- * flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
- * use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
- * `PlayRenderer` directly rather than `createRenderer`.
+ * Two situations need a different function. In the first, your code calls
+ * `registryResult.executeAction()` itself, outside the emit and on flow. In the
+ * second, you give more provider options, such as `navigate`, `onRenderError`, or
+ * `functions`. Use `createPlayUI`, which accepts the complete
+ * `CreatePlayUIOptions`. You can also use `defineRegistry` with `PlayRenderer`
+ * directly.
  */
 export declare function createRenderer<C extends Catalog>(catalog: C, componentMap: ComponentRegistry<C>): (actor: AbstractActor<AnyActorLogic> & Viewable, container: HTMLElement, options?: Omit<PlayDomOptions, "registryResult">) => () => void;
 //# sourceMappingURL=create-renderer.d.ts.map

package/dist/create-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,MAAM,IAAI,CAWd"}
+{"version":3,"file":"create-renderer.d.ts","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAC/C,OAAO,EAAE,CAAC,EACV,YAAY,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,CACF,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,QAAQ,EAC9C,SAAS,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,KAC5C,MAAM,IAAI,CAWd"}

package/dist/create-renderer.js

@@ -1,12 +1,12 @@
 /**
- * create-renderer.ts — createRenderer convenience factory for @xmachines/play-dom.
+ * create-renderer.ts — the createRenderer factory of @xmachines/play-dom.
  *
- * Mirrors the `createRenderer` export from @xmachines/json-render-react, /vue, /solid, /svelte.
- * Calls `defineRegistry` once at factory creation time and returns a
- * `mount(actor, container, options?)` function that wires up PlayRenderer and
- * returns a `disconnect` cleanup function.
+ * It matches the `createRenderer` export of @xmachines/json-render-react, of /vue,
+ * of /solid, and of /svelte. It calls `defineRegistry` one time, at the creation of
+ * the factory. It then returns a `mount(actor, container, options?)` function. That
+ * function connects a PlayRenderer, and it returns a `disconnect` cleanup function.
  *
- * Reduces consumer boilerplate from 3–4 steps to one call.
+ * The consumer therefore writes one call, and not three or four steps.
  *
  * @example
  * ```ts
@@ -40,13 +40,13 @@
  *   return el;
  * };
  *
- * // Build the factory once (at module scope)
+ * // Build the factory one time, at module scope
  * const mount = createRenderer(catalog, { Home, Login });
  *
- * // Mount when actor + container are ready
+ * // Mount when the actor and the container are ready
  * const disconnect = mount(actor, document.getElementById("app")!);
  *
- * // Cleanup:
+ * // Clean up:
  * disconnect();
  * ```
  *
@@ -55,24 +55,28 @@
 import { PlayRenderer } from "./PlayRenderer.js";
 import { defineRegistry } from "@xmachines/json-render-dom";
 /**
- * Create a reusable DOM renderer factory from a catalog and component map.
+ * Creates a DOM renderer factory from a catalog and a component map. You can use
+ * the factory more than one time.
  *
- * Returns a `mount(actor, container, options?)` function that wires up the
- * PlayRenderer in one call and returns a `disconnect` cleanup function.
+ * It returns a `mount(actor, container, options?)` function. That function connects
+ * the PlayRenderer in one call, and it returns a `disconnect` cleanup function.
  *
- * @param catalog      - The json-render Catalog describing component and action schemas.
- * @param componentMap - Component implementations keyed by catalog component name.
- * @returns A `mount` function that accepts `(actor, container, options?)` and returns `disconnect`.
+ * @param catalog      - The json-render Catalog. It describes the schema of each component and of each action.
+ * @param componentMap - The component implementations, with the catalog component name as the key.
+ * @returns A `mount` function. It accepts `(actor, container, options?)`, and it returns `disconnect`.
  *
  * @remarks
- * `createRenderer` manages `registryResult` internally — it calls `defineRegistry` once and
- * reuses the result across all `mount()` calls. The `mount` options type therefore excludes
- * `registryResult` (it is always provided by `createRenderer` itself and cannot be overridden).
+ * `createRenderer` manages `registryResult` internally. It calls `defineRegistry`
+ * one time, and it uses that result in every `mount()` call. Therefore the options
+ * type of `mount` holds no `registryResult`: `createRenderer` always gives it, and
+ * you cannot replace it.
  *
- * If you need to call `registryResult.executeAction()` programmatically (outside the emit/on
- * flow), or pass additional provider options (`navigate`, `onRenderError`, `functions`, etc.),
- * use `createPlayUI` (which accepts the full `CreatePlayUIOptions`) or `defineRegistry` with
- * `PlayRenderer` directly rather than `createRenderer`.
+ * Two situations need a different function. In the first, your code calls
+ * `registryResult.executeAction()` itself, outside the emit and on flow. In the
+ * second, you give more provider options, such as `navigate`, `onRenderError`, or
+ * `functions`. Use `createPlayUI`, which accepts the complete
+ * `CreatePlayUIOptions`. You can also use `defineRegistry` with `PlayRenderer`
+ * directly.
  */
 export function createRenderer(catalog, componentMap) {
     const registryResult = defineRegistry(catalog, { components: componentMap });

package/dist/create-renderer.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-renderer.js","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAU,EACV,YAAkC;IAMlC,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE7E,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAG,EAAE;QACnD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAC5E,GAAG,OAAO;YACV,cAAc;SACd,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACpC,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-renderer.js","sourceRoot":"","sources":["../src/create-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAU,EACV,YAAkC;IAMlC,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC;IAE7E,OAAO,SAAS,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAG,EAAE;QACnD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;YAC5E,GAAG,OAAO;YACV,cAAc;SACd,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACpC,CAAC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,27 +1,27 @@
 /**
- * @xmachines/play-dom — Vanilla DOM renderer for XMachines Play architecture.
+ * @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
  *
- * Public API split into two layers:
+ * The public API has two layers:
  *
- * **XMachines layer** (this package):
- * - `createRenderer()`  — one-call factory: returns `mount(actor, container, options?) → disconnect`
- * - `createPlayUI()`    — batteries-included factory with full options: returns `MountFn`
- * - `PlayRenderer`      — class-based renderer with `connect()` / `disconnect()` lifecycle
+ * **The XMachines layer**, in this package:
+ * - `createRenderer()`  — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
+ * - `createPlayUI()`    — the complete factory, with every option. It returns a `MountFn`
+ * - `PlayRenderer`      — the renderer class, with a `connect()` and `disconnect()` lifecycle
  * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
  *
- * **json-render layer** (re-exported from @xmachines/json-render-dom):
- * - `defineRegistry`    — build a catalog-typed DomRegistry
- * - `renderSpec`        — pure Spec → DOM renderer (uses resolveElementProps from core)
- * - `ComponentFn`       — catalog-typed component function type
- * - `ComponentContext`  — catalog-typed render context (props, emit, on, children, bindings)
- * - `ComponentRegistry` — catalog-typed registry input type
- * - `DomComponentRenderer` — raw element-level renderer type
- * - `DomRegistry`       — raw registry type
- * - `DomRenderContext`  — raw render context
- * - `EventHandle`       — event handle returned by on()
- * - `SetState`          — state updater function passed to ActionFn
- * - `CatalogHasActions` — conditional type: true when catalog declares actions
- * - `BaseComponentProps` — base props type for catalog component definitions
+ * **The json-render layer**, re-exported from @xmachines/json-render-dom:
+ * - `defineRegistry`    — it builds a catalog-typed DomRegistry
+ * - `renderSpec`        — the pure Spec → DOM renderer. It uses resolveElementProps of the core
+ * - `ComponentFn`       — the catalog-typed type of a component function
+ * - `ComponentContext`  — the catalog-typed render context: props, emit, on, children, bindings
+ * - `ComponentRegistry` — the catalog-typed input type of the registry
+ * - `DomComponentRenderer` — the raw renderer type of one element
+ * - `DomRegistry`       — the raw registry type
+ * - `DomRenderContext`  — the raw render context
+ * - `EventHandle`       — the event handle that on() returns
+ * - `SetState`          — the state updater function of an ActionFn
+ * - `CatalogHasActions` — the conditional type. It is true when the catalog declares an action
+ * - `BaseComponentProps` — the base props type of a catalog component definition
  *
  * @packageDocumentation
  */

package/dist/index.js

@@ -1,34 +1,34 @@
 /**
- * @xmachines/play-dom — Vanilla DOM renderer for XMachines Play architecture.
+ * @xmachines/play-dom — the vanilla DOM renderer of the XMachines Play architecture.
  *
- * Public API split into two layers:
+ * The public API has two layers:
  *
- * **XMachines layer** (this package):
- * - `createRenderer()`  — one-call factory: returns `mount(actor, container, options?) → disconnect`
- * - `createPlayUI()`    — batteries-included factory with full options: returns `MountFn`
- * - `PlayRenderer`      — class-based renderer with `connect()` / `disconnect()` lifecycle
+ * **The XMachines layer**, in this package:
+ * - `createRenderer()`  — the one-call factory. It returns `mount(actor, container, options?) → disconnect`
+ * - `createPlayUI()`    — the complete factory, with every option. It returns a `MountFn`
+ * - `PlayRenderer`      — the renderer class, with a `connect()` and `disconnect()` lifecycle
  * - `PlayDomOptions`, `CreatePlayUIOptions`, `MountFn`, `MountOptions`
  *
- * **json-render layer** (re-exported from @xmachines/json-render-dom):
- * - `defineRegistry`    — build a catalog-typed DomRegistry
- * - `renderSpec`        — pure Spec → DOM renderer (uses resolveElementProps from core)
- * - `ComponentFn`       — catalog-typed component function type
- * - `ComponentContext`  — catalog-typed render context (props, emit, on, children, bindings)
- * - `ComponentRegistry` — catalog-typed registry input type
- * - `DomComponentRenderer` — raw element-level renderer type
- * - `DomRegistry`       — raw registry type
- * - `DomRenderContext`  — raw render context
- * - `EventHandle`       — event handle returned by on()
- * - `SetState`          — state updater function passed to ActionFn
- * - `CatalogHasActions` — conditional type: true when catalog declares actions
- * - `BaseComponentProps` — base props type for catalog component definitions
+ * **The json-render layer**, re-exported from @xmachines/json-render-dom:
+ * - `defineRegistry`    — it builds a catalog-typed DomRegistry
+ * - `renderSpec`        — the pure Spec → DOM renderer. It uses resolveElementProps of the core
+ * - `ComponentFn`       — the catalog-typed type of a component function
+ * - `ComponentContext`  — the catalog-typed render context: props, emit, on, children, bindings
+ * - `ComponentRegistry` — the catalog-typed input type of the registry
+ * - `DomComponentRenderer` — the raw renderer type of one element
+ * - `DomRegistry`       — the raw registry type
+ * - `DomRenderContext`  — the raw render context
+ * - `EventHandle`       — the event handle that on() returns
+ * - `SetState`          — the state updater function of an ActionFn
+ * - `CatalogHasActions` — the conditional type. It is true when the catalog declares an action
+ * - `BaseComponentProps` — the base props type of a catalog component definition
  *
  * @packageDocumentation
  */
-// XMachines integration layer
+// The integration layer of XMachines
 export { PlayRenderer } from "./PlayRenderer.js";
 export { createRenderer } from "./create-renderer.js";
 export { createPlayUI } from "./create-play-ui.js";
-// @xmachines/json-render-dom (re-exported for consumer convenience)
+// @xmachines/json-render-dom. This package re-exports it, for the convenience of a consumer
 export { defineRegistry, renderSpec, schema, createValidationRegistry, } from "@xmachines/json-render-dom";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8BAA8B;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,oEAAoE;AACpE,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD,4FAA4F;AAC5F,OAAO,EACN,cAAc,EACd,UAAU,EACV,MAAM,EACN,wBAAwB,GACxB,MAAM,4BAA4B,CAAC"}