@xmachines/docs 1.0.0-beta.32 → 1.0.0-beta.34

package/api/@xmachines/play-dom/type-aliases/ActionFn.md

@@ -3,14 +3,18 @@
 # Type Alias: ActionFn\<C, K\>
 
 ```ts
-type ActionFn<C, K> = (params) => Promise<void>;
+type ActionFn<C, K> = (params, setState, state) => Promise<void>;
 ```
 
-Defined in: [json-render/types.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L126)
+Defined in: [packages/play-dom/src/json-render/types.ts:272](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L272)
 
 Catalog-typed action function — mirrors `ActionFn<C, K>` from @json-render/react, /solid, /vue.
-`params` is typed to the exact param schema defined in the catalog, or `undefined` if no spec
-provided params. The handler must guard against undefined before accessing params.
+
+- `params` is typed to the exact param schema defined in the catalog, or `undefined` if the
+  spec provided no params. Guard against undefined before accessing params.
+- `setState` writes to the @xstate/store-backed local state store. Use it to update ephemeral
+  UI state (e.g. form field values, error messages) from within an action handler.
+- `state` is a snapshot of the current state model at the time the action was invoked.
 
 ## Type Parameters
 
@@ -21,10 +25,22 @@ provided params. The handler must guard against undefined before accessing param
 
 ## Parameters
 
-| Parameter | Type                                           |
-| --------- | ---------------------------------------------- |
-| `params`  | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| Parameter  | Type                                           |
+| ---------- | ---------------------------------------------- |
+| `params`   | `InferActionParams`\<`C`, `K`\> \| `undefined` |
+| `setState` | [`SetState`](SetState.md)                      |
+| `state`    | `StateModel`                                   |
 
 ## Returns
 
 `Promise`\<`void`\>
+
+## Example
+
+```ts
+login: async (params, setState, state) => {
+	if (!params) return;
+	setState((prev) => ({ ...prev, loading: true }));
+	await actor.send({ type: "auth.login", username: params.username });
+};
+```

package/api/@xmachines/play-dom/type-aliases/Actions.md

@@ -6,7 +6,7 @@
 type Actions<C> = { [K in keyof InferCatalogActions<C>]: ActionFn<C, K> };
 ```
 
-Defined in: [json-render/types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L134)
+Defined in: [packages/play-dom/src/json-render/types.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L282)
 
 Map of catalog-typed action handler functions.
 Each key is a catalog action name; each value is an `ActionFn<C, K>` for that action.

package/api/@xmachines/play-dom/type-aliases/BaseComponentProps.md

@@ -0,0 +1,114 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / BaseComponentProps
+
+# Type Alias: BaseComponentProps\<P\>
+
+```ts
+type BaseComponentProps<P> = object;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L227)
+
+Catalog-agnostic component props type.
+
+Use this when building shared component libraries that should not be tied to
+a specific catalog instance. Mirrors `BaseComponentProps<P>` from
+@json-render/react, /vue, /svelte.
+
+## Example
+
+```ts
+import type { BaseComponentProps } from "@xmachines/play-dom";
+
+function MyButton({ props, emit }: BaseComponentProps<{ label: string }>) {
+	const el = document.createElement("button");
+	el.textContent = props.label;
+	el.addEventListener("click", () => emit("click"));
+	return el;
+}
+```
+
+## Type Parameters
+
+| Type Parameter                                | Default type                    |
+| --------------------------------------------- | ------------------------------- |
+| `P` _extends_ `Record`\<`string`, `unknown`\> | `Record`\<`string`, `unknown`\> |
+
+## Properties
+
+### bindings
+
+```ts
+bindings: Record<string, string> | undefined;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L230)
+
+---
+
+### children
+
+```ts
+children: Node[];
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L229)
+
+---
+
+### ctx
+
+```ts
+ctx: DomRenderContext;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:233](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L233)
+
+---
+
+### emit
+
+```ts
+emit: (event) => void;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L231)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+`void`
+
+---
+
+### on
+
+```ts
+on: (event) => EventHandle;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:232](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L232)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+[`EventHandle`](../interfaces/EventHandle.md)
+
+---
+
+### props
+
+```ts
+props: P;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L228)

package/api/@xmachines/play-dom/type-aliases/CatalogHasActions.md

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / CatalogHasActions
+
+# Type Alias: CatalogHasActions\<C\>
+
+```ts
+type CatalogHasActions<C> = [InferCatalogActions<C>] extends [never]
+	? false
+	: [keyof InferCatalogActions<C>] extends [never]
+		? false
+		: true;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L98)
+
+Evaluates to `true` when a catalog declares at least one action; `false` otherwise.
+
+Mirrors `CatalogHasActions<C>` from @json-render/react, /solid, /vue.
+Used to make the `actions` field required in `DefineRegistryOptions` when the
+catalog defines actions, and optional when it does not.
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |

package/api/@xmachines/play-dom/type-aliases/ComponentFn.md

@@ -6,7 +6,7 @@
 type ComponentFn<C, K> = (ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L105)
+Defined in: [packages/play-dom/src/json-render/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L238)
 
 ## Type Parameters
 

package/api/@xmachines/play-dom/type-aliases/ComponentRegistry.md

@@ -6,7 +6,7 @@
 type ComponentRegistry<C> = { [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K> };
 ```
 
-Defined in: [json-render/types.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L111)
+Defined in: [packages/play-dom/src/json-render/types.ts:244](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L244)
 
 ## Type Parameters
 

package/api/@xmachines/play-dom/type-aliases/DefineRegistryOptions.md

@@ -0,0 +1,39 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / DefineRegistryOptions
+
+# Type Alias: DefineRegistryOptions\<C\>
+
+```ts
+type DefineRegistryOptions<C> = object & CatalogHasActions<C> extends true ? object : object;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:304](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L304)
+
+Options for `defineRegistry`.
+
+Mirrors `DefineRegistryOptions<C>` from @json-render/react, /solid, /svelte, /vue.
+`actions` accepts catalog-typed async handler functions — params, setState, and state are
+fully typed. When the catalog declares actions, `actions` is required; otherwise optional.
+
+## Type Declaration
+
+| Name          | Type                                               | Description                                                                                                                                                             | Defined in                                                                                                                                                         |
+| ------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `components?` | [`ComponentRegistry`](ComponentRegistry.md)\<`C`\> | Catalog-typed component implementations. If omitted, all elements fall through to the `fallback` renderer (if provided) or return `null` — the container will be empty. | [packages/play-dom/src/json-render/types.ts:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L310) |
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |
+
+## Example
+
+```ts
+actions: {
+  login: async (params, setState, state) => {
+    if (!params) return;
+    setState(prev => ({ ...prev, loading: true }));
+    actor.send({ type: 'auth.login', username: params.username });
+  },
+}
+```

package/api/@xmachines/play-dom/type-aliases/DomComponentRenderer.md

@@ -6,7 +6,7 @@
 type DomComponentRenderer = (element, ctx) => HTMLElement | Text | null;
 ```
 
-Defined in: [json-render/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L71)
+Defined in: [packages/play-dom/src/json-render/types.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L174)
 
 ## Parameters
 

package/api/@xmachines/play-dom/type-aliases/DomRegistry.md

@@ -6,4 +6,4 @@
 type DomRegistry = Record<string, DomComponentRenderer>;
 ```
 
-Defined in: [json-render/types.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/types.ts#L117)
+Defined in: [packages/play-dom/src/json-render/types.ts:250](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L250)

package/api/@xmachines/play-dom/type-aliases/DomSchema.md

@@ -6,4 +6,4 @@
 type DomSchema = typeof schema;
 ```
 
-Defined in: [json-render/schema.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/schema.ts#L60)
+Defined in: [packages/play-dom/src/json-render/schema.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/schema.ts#L60)

package/api/@xmachines/play-dom/type-aliases/MountFn.md

@@ -0,0 +1,25 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / MountFn
+
+# Type Alias: MountFn
+
+```ts
+type MountFn = (actor, container, options?) => () => void;
+```
+
+Defined in: [packages/play-dom/src/create-play-ui.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/create-play-ui.ts#L47)
+
+The mount function returned by createPlayUI.
+Call with (actor, container, mountOptions?) to start the renderer.
+Returns a disconnect function for cleanup.
+
+## Parameters
+
+| Parameter   | Type                                                                                                                                                                                          |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`     | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)\> & [`Viewable`](../../play-actor/interfaces/Viewable.md) |
+| `container` | `HTMLElement`                                                                                                                                                                                 |
+| `options?`  | [`MountOptions`](../interfaces/MountOptions.md)                                                                                                                                               |
+
+## Returns
+
+() => `void`

package/api/@xmachines/play-dom/type-aliases/RenderErrorHandler.md

@@ -0,0 +1,23 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / RenderErrorHandler
+
+# Type Alias: RenderErrorHandler
+
+```ts
+type RenderErrorHandler = (error, elementType) => void;
+```
+
+Defined in: `@json-render/core`
+
+Callback invoked when an individual catalog component throws during render.
+Implemented by each framework renderer's error boundary / error capture mechanism.
+
+## Parameters
+
+| Parameter     | Type      |
+| ------------- | --------- |
+| `error`       | `unknown` |
+| `elementType` | `string`  |
+
+## Returns
+
+`void`

package/api/@xmachines/play-dom/type-aliases/SetState.md

@@ -0,0 +1,30 @@
+[Documentation](../../../README.md) / [@xmachines/play-dom](../README.md) / SetState
+
+# Type Alias: SetState
+
+```ts
+type SetState = (updater) => void;
+```
+
+Defined in: [packages/play-dom/src/json-render/types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/types.ts#L46)
+
+Function to update the local state store.
+
+Mirrors `SetState` from @json-render/react, /solid, /vue, /svelte.
+In the DOM renderer, this writes through to the @xstate/store-backed StateStore.
+
+## Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `updater` | (`prev`) => `Record`\<`string`, `unknown`\> |
+
+## Returns
+
+`void`
+
+## Example
+
+```ts
+setState((prev) => ({ ...prev, username: "alice" }));
+```

package/api/@xmachines/play-dom/variables/schema.md

@@ -46,7 +46,7 @@ const schema: Schema<{
 }>;
 ```
 
-Defined in: [json-render/schema.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.32/packages/play-dom/src/json-render/schema.ts#L20)
+Defined in: [packages/play-dom/src/json-render/schema.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.34/packages/play-dom/src/json-render/schema.ts#L20)
 
 The schema for @xmachines/play-dom