@xmachines/docs 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,114 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / BaseComponentProps
+
+# Type Alias: BaseComponentProps\<P\>
+
+```ts
+type BaseComponentProps<P> = object;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+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
+@xmachines/json-render-react, /vue, /svelte.
+
+## Example
+
+```ts
+import type { BaseComponentProps } from "@xmachines/json-render-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: `@xmachines/json-render-dom`
+
+---
+
+### children
+
+```ts
+children: Node[];
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+---
+
+### ctx
+
+```ts
+ctx: DomRenderContext;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+---
+
+### emit
+
+```ts
+emit: (event) => void;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+`void`
+
+---
+
+### on
+
+```ts
+on: (event) => EventHandle;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `event`   | `string` |
+
+#### Returns
+
+[`EventHandle`](../interfaces/EventHandle.md)
+
+---
+
+### props
+
+```ts
+props: P;
+```
+
+Defined in: `@xmachines/json-render-dom`

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

@@ -0,0 +1,25 @@
+[API](../../../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: `@xmachines/json-render-dom`
+
+Evaluates to `true` when a catalog declares at least one action; `false` otherwise.
+
+Mirrors `CatalogHasActions<C>` from @xmachines/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

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentFn
+
+# Type Alias: ComponentFn\<C, K\>
+
+```ts
+type ComponentFn<C, K> = (ctx) => HTMLElement | Text | null;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+## Type Parameters
+
+| Type Parameter                                      |
+| --------------------------------------------------- |
+| `C` _extends_ `Catalog`                             |
+| `K` _extends_ keyof `InferCatalogComponents`\<`C`\> |
+
+## Parameters
+
+| Parameter | Type                                                                |
+| --------- | ------------------------------------------------------------------- |
+| `ctx`     | [`ComponentContext`](../interfaces/ComponentContext.md)\<`C`, `K`\> |
+
+## Returns
+
+`HTMLElement` \| `Text` \| `null`

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

@@ -0,0 +1,15 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ComponentRegistry
+
+# Type Alias: ComponentRegistry\<C\>
+
+```ts
+type ComponentRegistry<C> = { [K in keyof InferCatalogComponents<C>]: ComponentFn<C, K> };
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+## Type Parameters
+
+| Type Parameter          |
+| ----------------------- |
+| `C` _extends_ `Catalog` |

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

@@ -0,0 +1,44 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / ConfirmHandler
+
+# Type Alias: ConfirmHandler
+
+```ts
+type ConfirmHandler = (confirm, action) => boolean | Promise<boolean>;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Hook consulted before executing an action binding that declares `confirm`.
+
+The DOM renderer is headless, so instead of the framework adapters'
+`pendingConfirmation` state (which a dialog component resolves via
+`confirmAction()` / `cancelAction()`), @xmachines/json-render-dom exposes a single async
+callback: return (or resolve) `true` to execute the action, `false` to
+skip it. The confirmation flow — `window.confirm`, a custom dialog, or a
+test stub — is entirely the host's responsibility.
+
+If no `ConfirmHandler` is configured, confirm-gated actions do NOT execute;
+a `console.warn` is emitted instead. This matches the framework adapters,
+where a pending confirmation that is never resolved never runs the handler.
+
+## Parameters
+
+| Parameter | Type             | Description                                                                                                    |
+| --------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |
+| `confirm` | `ActionConfirm`  | The confirm config from the spec, with `title` and `message` already `${path}`-interpolated against the store. |
+| `action`  | `ResolvedAction` | The fully resolved action (name, params, chain handlers).                                                      |
+
+## Returns
+
+`boolean` \| `Promise`\<`boolean`\>
+
+`true` (or a promise of `true`) to execute the action; anything
+falsy to skip it silently.
+
+## Example
+
+```typescript
+renderSpec(spec, store, registry, {
+	onConfirm: (confirm) => window.confirm(`${confirm.title}\n${confirm.message}`),
+});
+```

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

@@ -0,0 +1,39 @@
+[API](../../../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: `@xmachines/json-render-dom`
+
+Options for `defineRegistry`.
+
+Mirrors `DefineRegistryOptions<C>` from @xmachines/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. | -          |
+
+## 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

@@ -0,0 +1,20 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DomComponentRenderer
+
+# Type Alias: DomComponentRenderer
+
+```ts
+type DomComponentRenderer = (element, ctx) => HTMLElement | Text | null;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+## Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `element` | `UIElement`                                             |
+| `ctx`     | [`DomRenderContext`](../interfaces/DomRenderContext.md) |
+
+## Returns
+
+`HTMLElement` \| `Text` \| `null`

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

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DomRegistry
+
+# Type Alias: DomRegistry
+
+```ts
+type DomRegistry = Record<string, DomComponentRenderer>;
+```
+
+Defined in: `@xmachines/json-render-dom`

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

@@ -0,0 +1,9 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / DomSchema
+
+# Type Alias: DomSchema
+
+```ts
+type DomSchema = typeof schema;
+```
+
+Defined in: `@xmachines/json-render-dom`

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

@@ -0,0 +1,27 @@
+[API](../../../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:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/src/create-play-ui.ts#L69)
+
+The mount function returned by `createPlayUI`.
+
+Call with `(actor, container, mountOptions?)` to start the renderer.
+Returns a `disconnect` cleanup function that stops rendering and clears
+the container.
+
+## 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 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / RenderErrorHandler
+
+# Type Alias: RenderErrorHandler
+
+```ts
+type RenderErrorHandler = (error, elementType) => void;
+```
+
+Defined in: `@xmachines/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 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / SetState
+
+# Type Alias: SetState
+
+```ts
+type SetState = (updater) => void;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+Function to update the local state store.
+
+Mirrors `SetState` from @xmachines/json-render-react, /solid, /vue, /svelte.
+In the DOM renderer, this writes through to the backing `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

@@ -0,0 +1,62 @@
+[API](../../../README.md) / [@xmachines/play-dom](../README.md) / schema
+
+# Variable: schema
+
+```ts
+const schema: _json_render_core.Schema<{
+	catalog: _json_render_core.SchemaType<
+		"object",
+		{
+			actions: _json_render_core.SchemaType<
+				"map",
+				{
+					description: _json_render_core.SchemaType<"string", unknown>;
+					params: _json_render_core.SchemaType<"zod", unknown>;
+				}
+			>;
+			components: _json_render_core.SchemaType<
+				"map",
+				{
+					description: _json_render_core.SchemaType<"string", unknown>;
+					example: _json_render_core.SchemaType<"any", unknown>;
+					props: _json_render_core.SchemaType<"zod", unknown>;
+					slots: _json_render_core.SchemaType<
+						"array",
+						_json_render_core.SchemaType<"string", unknown>
+					>;
+				}
+			>;
+		}
+	>;
+	spec: _json_render_core.SchemaType<
+		"object",
+		{
+			elements: _json_render_core.SchemaType<
+				"record",
+				_json_render_core.SchemaType<
+					"object",
+					{
+						children: _json_render_core.SchemaType<
+							"array",
+							_json_render_core.SchemaType<"string", unknown>
+						>;
+						props: _json_render_core.SchemaType<"propsOf", string>;
+						type: _json_render_core.SchemaType<"ref", string>;
+						visible: _json_render_core.SchemaType<"any", unknown>;
+					}
+				>
+			>;
+			root: _json_render_core.SchemaType<"string", unknown>;
+		}
+	>;
+}>;
+```
+
+Defined in: `@xmachines/json-render-dom`
+
+The schema for @xmachines/json-render-dom
+
+Defines:
+
+- Spec: A flat tree of elements with keys, types, props, children, and on-bindings
+- Catalog: Components with props schemas, and optional actions with param schemas