@xmachines/docs 6.0.0 → 7.0.0

package/rfc/play.md

@@ -195,6 +195,20 @@ export interface PlaySpec extends Spec {
 	// authored): providers key their store lifecycle on it — changed key
 	// reseeds the store, unchanged key refreshes /context in place.
 	viewKey?: string;
+
+	// Stamped on a composed view: the ids of the composed states. viewKey
+	// stays the id of the outermost view, so a change of a substate keeps
+	// the store and seeds only the keys that it lacks.
+	viewParts?: readonly string[];
+}
+
+// What an author writes in meta.view. The derivation turns it into a
+// PlaySpec, so no renderer receives this type.
+export interface ViewMeta extends Spec {
+	// The element (and the optional named slot) that receives the view of
+	// each active child, keyed by the child state key or "*". The derivation
+	// consumes it.
+	outlets?: Record<string, { element: string; slot?: string }>;
 }
 
 export interface Viewable {
@@ -241,11 +255,12 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 **Responsibilities:**
 
 - Derive `currentRoute` and `currentView` from active state node metadata
+- Compose the view of a parent state that declares `outlets` with the views of its active substates, so the state tree decides the layout
 - Manage atom lifecycle (create on start, dispose on stop)
 - Support snapshot restore for resumable sessions
 - Provide XState DevTools compatibility
 
-```ts
+```ts fragment
 import type { AnyStateMachine, InputFrom } from "xstate";
 
 interface PlayerConfig<TMachine extends AnyStateMachine> {
@@ -348,23 +363,24 @@ Each adapter extends `RouterBridgeBase` and implements the three abstract method
 
 Each view renderer provides a `PlayRenderer` component that passively observes the actor's `currentView` atom and projects the JSON spec into framework-native components via `@json-render`.
 
-| Package                                                           | Framework   | JSON-Render Backend            |
-| ----------------------------------------------------------------- | ----------- | ------------------------------ |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | React       | `@xmachines/json-render-react` |
-| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)     | Vue 3       | `@xmachines/json-render-vue`   |
-| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) | SolidJS     | `@xmachines/json-render-solid` |
-| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)     | Vanilla DOM | `@xmachines/json-render-core`  |
+| Package                                                             | Framework   | JSON-Render Backend             |
+| ------------------------------------------------------------------- | ----------- | ------------------------------- |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | React       | `@xmachines/json-render-react`  |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | Vue 3       | `@xmachines/json-render-vue`    |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | SolidJS     | `@xmachines/json-render-solid`  |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | Svelte 5    | `@xmachines/json-render-svelte` |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | Vanilla DOM | `@xmachines/json-render-dom`    |
 
 **Shared Architecture (all renderers):**
 
 1. Subscribe to `actor.currentView` atom
-2. Resolve a `StateStore` (external or auto-created per view transition via `@xstate/store`)
-3. Wire `actions` prop to `actor.send()` via `ActionProvider`
+2. Resolve a `StateStore`: the external store of the caller, or a new `@xstate/store` store for each `viewKey`
+3. Give the action handlers of the registry to the `ActionProvider`. A handler of `defineRegistry` sends the machine event with `actor.send()`
 4. Render `spec` through the framework's `Renderer` with a `registry` (defined via `defineRegistry`)
 
 **[`@xmachines/play-react`](../api/@xmachines/play-react/README.md) exports (representative):**
 
-```ts
+```ts fragment
 // Batteries-included composite — standard entry point
 // Props: actor, registryResult, store?, fallback?, onError?, onRenderError?,
 //        validationFunctions?, navigate?, functions?
@@ -422,13 +438,18 @@ The original RFC proposed an `@xmachines/play-ui` package for this purpose. The
 Defines the **UI vocabulary** — available components and their prop schemas. No framework code.
 
 ```ts
-import { defineCatalog, z } from "@xmachines/json-render-core";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/json-render-react/schema";
+import { z } from "zod";
 
-export const catalog = defineCatalog({
+export const catalog = defineCatalog(schema, {
 	components: {
 		Dashboard: { props: z.object({ title: z.string() }) },
 		Metric: { props: z.object({ value: z.number(), label: z.string() }) },
 	},
+	actions: {
+		submit: { description: "Submit the form" },
+	},
 });
 ```
 
@@ -438,12 +459,17 @@ Defines **Logic**. No framework code. No routing library imports.
 
 ```ts
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { typedSpec } from "@xmachines/play-view";
 
 export const machine = setup({/* types, guards, actions */}).createMachine({
+	id: "dashboard",
 	initial: "overview",
 	states: {
 		overview: {
+			id: "overview",
 			meta: {
 				route: "/dashboard",
 				view: typedSpec({
@@ -462,20 +488,27 @@ export const machine = setup({/* types, guards, actions */}).createMachine({
 	},
 });
 
-// definePlayer returns a factory function
-export const createDashboard = definePlayer({ machine });
+// definePlayer returns a factory function. The router and the renderer need both capabilities
+export const createDashboard = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 ```
 
 ### 6.3 Application (`App.tsx`)
 
 Binds Logic to a View Renderer and Router Adapter.
 
-```tsx
-import { createDashboard, machine } from "./features/dashboard/player";
-import { catalog } from "./catalog";
+```tsx fragment
+import { createRootRoute, createRouter } from "@tanstack/react-router";
+import { createDashboard, machine } from "./dashboard.player.js";
+import { catalog } from "./catalog.js";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
-import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
+import {
+	createRouteMapFromTree,
+	TanStackReactRouterBridge,
+} from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 // 1. Create the actor
 const actor = createDashboard();
@@ -500,7 +533,8 @@ const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 // 4. Connect router adapter (router, actor, routeMap)
-const bridge = new TanStackReactRouterBridge(tanstackRouter, actor, routeMap);
+const router = createRouter({ routeTree: createRootRoute() });
+const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
 // 5. Render — PlayUIProvider is the batteries-included composite; PlayRenderer is the zero-prop leaf

package/api/@xmachines/play-view/index/functions/createFailureLatch.md

@@ -1,20 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / createFailureLatch
-
-# Function: createFailureLatch()
-
-```ts
-function createFailureLatch(): FailureLatch;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L202)
-
-Makes a [FailureLatch](../interfaces/FailureLatch.md).
-
-The latch holds the three inputs BESIDE the flag. Clearing on each emission would be
-enough for a provider that can hook every emission, and the identity check covers the
-one that cannot: a render that runs again with nothing changed reports nothing, whether
-or not the provider noticed that it ran.
-
-## Returns
-
-[`FailureLatch`](../interfaces/FailureLatch.md)

package/api/@xmachines/play-view/index/functions/sameViewInputs.md

@@ -1,25 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / sameViewInputs
-
-# Function: sameViewInputs()
-
-```ts
-function sameViewInputs(a, b): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L45)
-
-Answers whether two sets of inputs are the SAME attempt.
-
-Identity, and not a deep compare: a provider holds the references that it rendered, and
-a new spec object is a new attempt even when it holds equal fields.
-
-## Parameters
-
-| Parameter | Type                                        |
-| --------- | ------------------------------------------- |
-| `a`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-| `b`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-
-## Returns
-
-`boolean`

package/api/@xmachines/play-view/index/interfaces/FailureLatch.md

@@ -1,60 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / FailureLatch
-
-# Interface: FailureLatch
-
-Defined in: [packages/play-view/src/failure-latch.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L174)
-
-The record of what a provider reported. See [createFailureLatch](../functions/createFailureLatch.md).
-
-## Methods
-
-### clear()
-
-```ts
-clear(): void;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L191)
-
-Forgets the record, so the next failure reports again.
-
-A caller clears it on EVERY emission of a view, the null emission included: a view,
-then null, then the same view is a real sequence of an actor, and the second failure
-of that view is a second attempt that the host must hear about. It also clears it on
-a resolution that works, and on a retry that the host starts — the host asked for
-that attempt, so it must hear the result.
-
-#### Returns
-
-`void`
-
----
-
-### shouldReport()
-
-```ts
-shouldReport(
-   actor,
-   view,
-   store
-): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L181)
-
-Answers whether a failure of these three inputs is new, and records it.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `actor`   | `unknown` |
-| `view`    | `unknown` |
-| `store`   | `unknown` |
-
-#### Returns
-
-`boolean`
-
-`true` the first time for one set of inputs, and `false` for every repeat
-of the same set. A caller reports only when it returns `true`.

package/api/@xmachines/play-view/index/interfaces/ViewInputs.md

@@ -1,19 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / ViewInputs
-
-# Interface: ViewInputs
-
-Defined in: [packages/play-view/src/failure-latch.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L33)
-
-The three inputs that a provider resolves a store from.
-
-`ViewStoreLifecycle.resolve` takes exactly these, and every provider names all three in
-its reset rule. The type gives the rule one name, so the comparison below stands one
-time instead of once for each renderer that needs it.
-
-## Properties
-
-| Property                            | Type      | Defined in                                                                                                                                         |
-| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor` | `unknown` | [packages/play-view/src/failure-latch.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L34) |
-| <a id="property-store"></a> `store` | `unknown` | [packages/play-view/src/failure-latch.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L36) |
-| <a id="property-view"></a> `view`   | `unknown` | [packages/play-view/src/failure-latch.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-view/src/failure-latch.ts#L35) |