@xmachines/play-dom 2.0.0 → 2.1.0

package/dist/types.d.ts

@@ -1,8 +1,8 @@
 /**
- * types.ts — XMachines-specific type definitions for play-dom.
+ * types.ts — the type definitions of play-dom that belong to XMachines.
  *
- * These types depend on @xmachines/play-actor and stay in play-dom.
- * Pure json-render types live in @xmachines/json-render-dom.
+ * These types depend on @xmachines/play-actor, and they stay in play-dom.
+ * Each pure json-render type is in @xmachines/json-render-dom.
  *
  * @packageDocumentation
  */
@@ -10,65 +10,68 @@ import type { StateStore } from "@xmachines/json-render-core";
 import type { DefineRegistryResult, UIProviderOptions } from "@xmachines/json-render-dom";
 export type { UIProviderOptions } from "@xmachines/json-render-dom";
 /**
- * Options for `PlayRenderer`.
+ * The options of `PlayRenderer`.
  *
- * Extends {@link UIProviderOptions}, which contributes `functions`,
- * `directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
- * are forwarded into `DomRenderContext` on every render pass and are readable
- * by component implementations via `ctx.ctx.*`.
+ * This type extends {@link UIProviderOptions}, which gives `functions`,
+ * `directives`, `validationFunctions`, `navigate`, and `onRenderError`. Each render
+ * pass puts all of them into `DomRenderContext`, and a component implementation
+ * reads them at `ctx.ctx.*`.
  */
 export interface PlayDomOptions extends UIProviderOptions {
     /**
-     * The result from `defineRegistry` — provides both the registry and the handlers factory.
+     * The result of `defineRegistry`. It gives the registry and the factory of the handlers.
      *
-     * When provided, `PlayRenderer` wires `setState` and `getState` from the @xstate/store-backed
-     * `StateStore` into the handlers factory automatically. This is the preferred approach as it
-     * ensures actions always receive live `setState` and `state` bound to the current store.
+     * With this option, `PlayRenderer` connects `setState` and `getState` of the
+     * `StateStore` on @xstate/store to the factory of the handlers for you. This is the
+     * preferred way, because each action then always receives a live `setState` and a
+     * live `state` on the current store.
      */
     registryResult?: DefineRegistryResult;
     /**
-     * Optional external StateStore (e.g. from `xstateStoreStateStore` in @xmachines/json-render-xstate).
+     * The optional external StateStore, for example from `xstateStoreStateStore` in @xmachines/json-render-xstate.
      *
-     * When provided, `PlayRenderer` operates in controlled mode — `spec.state` is ignored and
-     * this store is the single source of truth for UI state (form values, etc.).
-     * When omitted, a fresh `@xstate/store` atom is created internally per view transition,
-     * seeded from `spec.state`.
+     * With this option, `PlayRenderer` works in the controlled mode: it ignores
+     * `spec.state`, and this store is the single source of truth of the UI state, such
+     * as a form value. Without this option, the renderer makes a new `@xstate/store`
+     * atom for each view transition, with the values of `spec.state`.
      */
     store?: StateStore;
     /**
-     * When `true`, indicates the spec is still streaming (e.g. from an AI provider).
+     * With the value `true`, the spec is still streaming, for example from an AI provider.
      *
-     * Forwarded to `renderSpec` so component implementations can read `ctx.ctx.loading`
-     * to render skeleton states. Also suppresses missing-child warnings during stream
-     * ingestion, since referenced elements may not yet have arrived in the incremental spec.
+     * The renderer gives the flag to `renderSpec`. A component implementation therefore
+     * reads `ctx.ctx.loading`, and it can render a skeleton state. The flag also stops
+     * each warning about an absent child during the ingestion of the stream, because an
+     * element of a reference can still be absent from the incremental spec.
      *
-     * Mirrors the `loading` prop from framework renderer providers.
+     * This option matches the `loading` prop of the framework renderer providers.
      */
     loading?: boolean;
 }
 /**
- * Options for `createPlayUI()` — the batteries-included DOM factory.
+ * The options of `createPlayUI()`, the complete DOM factory.
  *
- * Extends {@link UIProviderOptions}, which contributes `functions`,
- * `directives`, `validationFunctions`, `navigate`, and `onRenderError`. All
- * are closed over at factory creation time and forwarded into `PlayRenderer`
- * on every `mount()` call.
+ * This type extends {@link UIProviderOptions}, which gives `functions`,
+ * `directives`, `validationFunctions`, `navigate`, and `onRenderError`. The factory
+ * holds all of them from the moment of its creation, and it gives them to
+ * `PlayRenderer` on every `mount()` call.
  *
- * Parallel to `PlayUIProvider`'s props in the framework renderers.
+ * This type is parallel to the props of `PlayUIProvider` in the framework renderers.
  *
  * @see createPlayUI
  */
 export interface CreatePlayUIOptions extends UIProviderOptions {
     /**
-     * Optional fallback element shown when `currentView` is `null` on **initial mount** only.
+     * The optional fallback element. The factory shows it when `currentView` is `null` on the **first mount** only.
      *
-     * The fallback is appended immediately after `mount()` if the container is empty at
-     * that moment (i.e. the actor's initial view is `null`).
+     * The factory appends the fallback directly after `mount()`, when the container is
+     * empty at that moment, which means that the first view of the actor is `null`.
      *
-     * **Limitation:** If the actor's view transitions to `null` after mount, the container
-     * will be cleared but this fallback will NOT be re-appended. For dynamic fallback
-     * behavior (null view after non-null), use `PlayRenderer` directly and wrap the
-     * `actor.currentView` signal to inject fallback content.
+     * **Limitation:** when the view of the actor becomes `null` after the mount, the
+     * renderer clears the container, and it does NOT append this fallback again. For a
+     * dynamic fallback, which follows a null view after a view that was not null, use
+     * `PlayRenderer` directly and wrap the `actor.currentView` signal to add the
+     * fallback content.
      */
     fallback?: HTMLElement | null;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACxD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAEtC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC7D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACxD;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAEtC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC7D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B"}

package/dist/types.js

@@ -1,8 +1,8 @@
 /**
- * types.ts — XMachines-specific type definitions for play-dom.
+ * types.ts — the type definitions of play-dom that belong to XMachines.
  *
- * These types depend on @xmachines/play-actor and stay in play-dom.
- * Pure json-render types live in @xmachines/json-render-dom.
+ * These types depend on @xmachines/play-actor, and they stay in play-dom.
+ * Each pure json-render type is in @xmachines/json-render-dom.
  *
  * @packageDocumentation
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/play-dom",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Vanilla DOM renderer for XMachines Play architecture with signal-driven rendering",
   "keywords": [
     "actor",
@@ -42,12 +42,13 @@
     "clean": "rm -rf dist *.tsbuildinfo coverage .vitest-attachments test/browser/__screenshots__ node_modules/.svelte2tsx-* node_modules/.vite*",
     "lint": "oxlint .",
     "format": "oxfmt .",
-    "test": "vitest"
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xmachines/play": "2.0.0",
-    "@xmachines/play-actor": "2.0.0",
-    "@xmachines/play-signals": "2.0.0"
+    "@xmachines/play": "2.1.0",
+    "@xmachines/play-actor": "2.1.0",
+    "@xmachines/play-signals": "2.1.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/dist/errors.d.ts

@@ -1,46 +0,0 @@
-import { PlayError } from "@xmachines/play";
-/**
- * Thrown by `PlayRenderer` when the `components` option is `null` or `undefined`.
- *
- * A missing catalog is a programmer error — the components map must be provided
- * to the renderer. The `componentName` that was being looked up is encoded in
- * the error message.
- *
- * **Error code:** `PLAY_DOM_MISSING_CATALOG`
- *
- * @example
- * ```typescript
- * import { MissingCatalogError } from "@xmachines/play-dom";
- *
- * // In a catch block:
- * if (err instanceof MissingCatalogError) {
- *   console.error("components option was not provided to the renderer");
- * }
- * ```
- */
-export declare class MissingCatalogError extends PlayError {
-    constructor(componentName: string, catalogValue: null | undefined);
-}
-/**
- * Thrown by `PlayRenderer` when the component name from `actor.currentView` does
- * not exist as a key in the `components` catalog.
- *
- * This is a programmer error — either the machine's `meta.view.component` name is
- * misspelled, or the component was not registered in the catalog passed to the renderer.
- *
- * **Error code:** `PLAY_DOM_MISSING_COMPONENT`
- *
- * @example
- * ```typescript
- * import { MissingComponentError } from "@xmachines/play-dom";
- *
- * if (err instanceof MissingComponentError) {
- *   // err.message lists both the missing name and available components
- *   console.error(err.message);
- * }
- * ```
- */
-export declare class MissingComponentError extends PlayError {
-    constructor(componentName: string, availableComponents: string[]);
-}
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACrC,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAG,SAAS;CAQjE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACvC,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE;CAQhE"}

package/dist/errors.js

@@ -1,52 +0,0 @@
-import { PlayError } from "@xmachines/play";
-/**
- * Thrown by `PlayRenderer` when the `components` option is `null` or `undefined`.
- *
- * A missing catalog is a programmer error — the components map must be provided
- * to the renderer. The `componentName` that was being looked up is encoded in
- * the error message.
- *
- * **Error code:** `PLAY_DOM_MISSING_CATALOG`
- *
- * @example
- * ```typescript
- * import { MissingCatalogError } from "@xmachines/play-dom";
- *
- * // In a catch block:
- * if (err instanceof MissingCatalogError) {
- *   console.error("components option was not provided to the renderer");
- * }
- * ```
- */
-export class MissingCatalogError extends PlayError {
-    constructor(componentName, catalogValue) {
-        super("PlayRenderer", "PLAY_DOM_MISSING_CATALOG", `Components catalog is ${catalogValue === null ? "null" : "undefined"}. Cannot render component "${componentName}".`);
-        this.name = "MissingCatalogError";
-    }
-}
-/**
- * Thrown by `PlayRenderer` when the component name from `actor.currentView` does
- * not exist as a key in the `components` catalog.
- *
- * This is a programmer error — either the machine's `meta.view.component` name is
- * misspelled, or the component was not registered in the catalog passed to the renderer.
- *
- * **Error code:** `PLAY_DOM_MISSING_COMPONENT`
- *
- * @example
- * ```typescript
- * import { MissingComponentError } from "@xmachines/play-dom";
- *
- * if (err instanceof MissingComponentError) {
- *   // err.message lists both the missing name and available components
- *   console.error(err.message);
- * }
- * ```
- */
-export class MissingComponentError extends PlayError {
-    constructor(componentName, availableComponents) {
-        super("PlayRenderer", "PLAY_DOM_MISSING_COMPONENT", `Component "${componentName}" not found in catalog. Available components: ${availableComponents.join(", ")}`);
-        this.name = "MissingComponentError";
-    }
-}
-//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IACjD,YAAY,aAAqB,EAAE,YAA8B;QAChE,KAAK,CACJ,cAAc,EACd,0BAA0B,EAC1B,yBAAyB,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,8BAA8B,aAAa,IAAI,CACpH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACnC,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IACnD,YAAY,aAAqB,EAAE,mBAA6B;QAC/D,KAAK,CACJ,cAAc,EACd,4BAA4B,EAC5B,cAAc,aAAa,iDAAiD,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACrC,CAAC;CACD"}