@xmachines/docs 1.0.0 → 2.0.0-alpha.1

package/examples/form-validation.md

@@ -2,22 +2,28 @@
 
 # Form Validation with Typed Context
 
-Managing login form state using `setup({ types })`, typed `assign`, guards, and `meta.view` with `$bindState`.
+Managing login form state using `setup({ schemas })`, typed context patches, guard logic in transition functions, and `meta.view` with `$bindState`.
 
 ## Use Case
 
 This example mirrors the `authMachine` login pattern: a form state with a local state store (`$bindState` two-way binding), a guard on the submit action, and a `meta.view` spec describing the component tree. It covers:
 
-- Typed context mutations with `setup.assign`
-- Guards as inline functions checking context
+- Typed context patches returned from transition functions
+- Guard logic as early returns inside transition functions
 - `meta.view` spec with `$bindState` for two-way form binding
 - Sending typed domain events from the view layer
 
 ## Complete Code
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
 // Context shape
 interface LoginContext {
@@ -28,133 +34,136 @@ interface LoginContext {
 	query: Record<string, string>;
 }
 
-// Event union — lowercase dot-separated names
-type LoginEvent =
-	| {
-			type: "play.route";
-			to: string;
-			params?: Record<string, string>;
-			query?: Record<string, string>;
-	  }
-	| { type: "auth.login"; username: string }
-	| { type: "auth.logout" };
-
-// 1. Typed setup — always use setup() before createMachine()
+// 1. Typed setup — always use setup() before createMachine().
+//    The events schema maps event type -> payload shape (payload excludes `type`);
+//    event names are lowercase dot-separated.
 const loginSetup = setup({
-	types: {
-		context: {} as LoginContext,
-		events: {} as LoginEvent,
-		input: {} as Partial<LoginContext> | undefined,
+	schemas: {
+		context: types<LoginContext>(),
+		input: types<Partial<LoginContext> | undefined>(),
+		events: {
+			"play.route": playRouteEventSchema,
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
+		},
+		// State meta carries route templates (meta.route) and typed PlaySpec
+		// view specs (meta.view)
+		meta: playMetaSchema,
 	},
 });
 
-// 2. Machine — wraps config in formatPlayRouteTransitions for play.route support
-const loginMachine = loginSetup.createMachine(
-	formatPlayRouteTransitions({
-		id: "login",
-		initial: "idle",
-		context: ({ input }) => ({
-			isAuthenticated: input?.isAuthenticated ?? false,
-			username: input?.username ?? null,
-			errorMessage: null,
-			params: input?.params ?? {},
-			query: input?.query ?? {},
-		}),
-
-		// Root-level event handlers — accessible from any state
-		on: {
-			"auth.login": {
+// 2. Machine — createRoutedMachine wires play.route support from id + meta.route
+//    pairs, with the same config typing as loginSetup.createMachine itself
+const loginMachine = createRoutedMachine(loginSetup)({
+	id: "login",
+	initial: "idle",
+	context: ({ input }) => ({
+		isAuthenticated: input?.isAuthenticated ?? false,
+		username: input?.username ?? null,
+		errorMessage: null,
+		params: input?.params ?? {},
+		query: input?.query ?? {},
+	}),
+
+	// Root-level event handlers — accessible from any state.
+	// Transitions are plain functions: guard with an early return,
+	// update context by returning a shallow patch.
+	on: {
+		"auth.login": ({ context, event }) => {
+			// Guard: allow login only when not already authenticated
+			if (context.isAuthenticated) return;
+			return {
 				target: ".dashboard",
-				// Guard: allow login only when not already authenticated
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: loginSetup.assign({
+				context: {
 					isAuthenticated: true,
 					errorMessage: null,
-					// Typed by the event union — TypeScript narrows event.username safely
-					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
-				}),
-			},
-			"auth.logout": {
+					// Typed by the event schema — event.username is already narrowed
+					username: event.username,
+				},
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
 				target: ".idle",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: loginSetup.assign({
+				context: {
 					isAuthenticated: false,
 					username: null,
-				}),
-			},
+				},
+			};
 		},
+	},
 
-		states: {
-			idle: {
-				id: "idle",
-				meta: {
-					route: "/",
-					view: {
-						root: "root",
-						elements: {
-							root: { type: "Home", props: { title: "Welcome" }, children: [] },
-						},
+	states: {
+		idle: {
+			id: "idle",
+			meta: {
+				route: "/",
+				view: {
+					root: "root",
+					elements: {
+						root: { type: "Home", props: { title: "Welcome" }, children: [] },
 					},
 				},
 			},
+		},
 
-			login: {
-				id: "login",
-				meta: {
-					route: "/login",
-					view: {
-						root: "root",
-						// Local state store — initial value shown in the form field
-						state: { username: "" },
-						elements: {
-							root: {
-								type: "Login",
-								props: {
-									title: "Sign In",
-									// $bindState wires the prop to the local state store (two-way)
-									username: { $bindState: "/username" },
-								},
-								children: [],
-								on: {
-									// emit("submit") → resolves username from $state, calls login action
-									submit: {
-										action: "login",
-										params: { username: { $state: "/username" } },
-									},
+		login: {
+			id: "login",
+			meta: {
+				route: "/login",
+				view: {
+					root: "root",
+					// Local state store — initial value shown in the form field
+					state: { username: "" },
+					elements: {
+						root: {
+							type: "Login",
+							props: {
+								title: "Sign In",
+								// $bindState wires the prop to the local state store (two-way)
+								username: { $bindState: "/username" },
+							},
+							children: [],
+							on: {
+								// emit("submit") → resolves username from $state, calls login action
+								submit: {
+									action: "login",
+									params: { username: { $state: "/username" } },
 								},
 							},
 						},
 					},
 				},
 			},
+		},
 
-			dashboard: {
-				id: "dashboard",
-				meta: {
-					route: "/dashboard",
-					view: {
-						root: "root",
-						elements: {
-							root: {
-								type: "Dashboard",
-								props: { title: "Dashboard" },
-								children: [],
-								on: {
-									logout: { action: "logout" },
-								},
+		dashboard: {
+			id: "dashboard",
+			meta: {
+				route: "/dashboard",
+				view: {
+					root: "root",
+					elements: {
+						root: {
+							type: "Dashboard",
+							props: { title: "Dashboard" },
+							children: [],
+							on: {
+								logout: { action: "logout" },
 							},
 						},
 					},
 				},
-				// always-guard: redirect to login if not authenticated
-				always: {
-					guard: ({ context }) => !context.isAuthenticated,
-					target: "login",
-				},
+			},
+			// always-transition: redirect to login if not authenticated
+			always: ({ context }) => {
+				if (context.isAuthenticated) return;
+				return { target: "login" };
 			},
 		},
-	}),
-);
+	},
+});
 
 // 3. Factory and actor
 const createPlayer = definePlayer({ machine: loginMachine });
@@ -171,7 +180,7 @@ console.log(actor.getSnapshot().value); // "dashboard"
 console.log(actor.getSnapshot().context.username); // "alice"
 
 // 6. Guard prevents re-login while authenticated
-actor.send({ type: "auth.login", username: "bob" }); // guard fires, transition rejected
+actor.send({ type: "auth.login", username: "bob" }); // early return — transition rejected
 console.log(actor.getSnapshot().context.username); // still "alice"
 
 // 7. Logout
@@ -217,10 +226,10 @@ view: {
 
 ## Key Concepts
 
-- **`setup({ types })`**: Always declare context, events, and input types before `createMachine`.
-- **`setup.assign(...)`**: Use the scoped `assign` from your `setup` instance, not the bare one from `xstate`. This provides full type inference.
-- **Guards as inline functions**: `({ context }) => !context.isAuthenticated` — guards check state invariants ("can I BE in this state?"), not event details.
-- **`always` transitions**: Entry guards on states. Used for protected routes — if the guard fires, the machine redirects before the state is fully entered.
+- **`setup({ schemas })`**: Always declare context, events, input, and meta schemas before `createMachine` — via `types<T>()` for your own shapes, and the shared `playRouteEventSchema` / `playMetaSchema` / `emptyEventSchema` constants from `@xmachines/play-xstate` for the Play-standard ones. `playMetaSchema` types `meta.view` as a `PlaySpec`, so view specs are checked, not `unknown`.
+- **Context patches**: Update context by returning a shallow `context` patch from the transition function. This provides full type inference — no `assign` action.
+- **Guards as early returns**: `if (context.isAuthenticated) return;` — the transition function checks state invariants ("can I BE in this state?") and returns `undefined` to reject the transition.
+- **`always` transitions**: Functions evaluated on state entry. Used for protected routes — return `{ target }` to redirect before the state is fully entered, or `undefined` to stay.
 - **Lowercase dot-separated event types**: `"auth.login"`, `"auth.logout"`, `"play.route"` — not `SCREAMING_SNAKE_CASE`.
 
 ## Connecting the Renderer
@@ -305,6 +314,6 @@ window.addEventListener("beforeunload", () => {
 ## Next Steps
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
-- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
+- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth redirects
 - **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, `$state`, and `contextProps`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/examples/routing-patterns.md

@@ -2,7 +2,7 @@
 
 # Routing Patterns
 
-How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` guards to implement actor-authoritative URL routing.
+How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` transitions to implement actor-authoritative URL routing.
 
 ## Overview
 
@@ -62,12 +62,17 @@ states: {
 
 ### `formatPlayRouteTransitions` — Auto-Generating Route Handlers
 
-Instead of hand-writing `play.route` event handlers for every routable state, wrap your machine config with `formatPlayRouteTransitions`:
+Instead of hand-writing `play.route` event handlers for every routable state, create the machine through `createRoutedMachine` — it has the same signature as the setup's own `createMachine` (full config inference) and applies `formatPlayRouteTransitions` at runtime:
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import type { PlayRouteEvent } from "@xmachines/play-router";
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
 interface AuthContext {
 	isAuthenticated: boolean;
@@ -77,47 +82,72 @@ interface AuthContext {
 }
 
 const authSetup = setup({
-	types: {
-		context: {} as AuthContext,
-		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as Partial<AuthContext> | undefined,
+	schemas: {
+		context: types<AuthContext>(),
+		input: types<Partial<AuthContext> | undefined>(),
+		events: {
+			"play.route": playRouteEventSchema,
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
+		},
+		meta: playMetaSchema,
 	},
 });
 
-const authMachine = authSetup.createMachine(
-	formatPlayRouteTransitions({
-		id: "auth",
-		initial: "home",
-		context: ({ input }) => ({
-			isAuthenticated: input?.isAuthenticated ?? false,
-			username: input?.username ?? null,
-			params: input?.params ?? {},
-			query: input?.query ?? {},
-		}),
-		states: {
-			home: { id: "home", meta: { route: "/" } },
-			about: { id: "about", meta: { route: "/about" } },
-			login: { id: "login", meta: { route: "/login" } },
-			profile: { id: "profile", meta: { route: "/profile/:username" } },
-		},
+const authMachine = createRoutedMachine(authSetup)({
+	id: "auth",
+	initial: "home",
+	context: ({ input }) => ({
+		isAuthenticated: input?.isAuthenticated ?? false,
+		username: input?.username ?? null,
+		params: input?.params ?? {},
+		query: input?.query ?? {},
 	}),
-);
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		about: { id: "about", meta: { route: "/about" } },
+		login: { id: "login", meta: { route: "/login" } },
+		profile: { id: "profile", meta: { route: "/profile/:username" } },
+	},
+});
 ```
 
-`formatPlayRouteTransitions` generates root-level handlers equivalent to:
+Under the hood, `formatPlayRouteTransitions` wires the routed states to XState v6's **native routing**: each routed state receives a static `route: {}` config (making it targetable via the built-in `xstate.route` event and visible to graph tooling), and one root-level `play.route` forwarder handles the public API by navigating those targets **directly, in one atomic transition**:
 
 ```typescript
+// Equivalent of what formatPlayRouteTransitions produces:
+states: {
+  home:    { id: "home",    meta: { route: "/" },                  route: {} },
+  about:   { id: "about",   meta: { route: "/about" },             route: {} },
+  login:   { id: "login",   meta: { route: "/login" },             route: {} },
+  profile: { id: "profile", meta: { route: "/profile/:username" }, route: {} },
+},
 on: {
   "play.route": [
-    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: true, actions: assign({ params, query }) },
-    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: true, actions: assign({ params, query }) },
-    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: true, actions: assign({ params, query }) },
-    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: true, actions: assign({ params, query }) },
+    // routeTargets maps each routed #id to its state path, collected during
+    // the crawl (or to null when the state declares its OWN route config).
+    ({ event }, enq) => {
+      const target = routeTargets.get(event.to);
+      if (target === undefined) return undefined; // fall through to your fallbacks
+      if (target === null) {
+        // user-declared route config: its resolver decides (and owns any patch)
+        enq.raise({ ...event, type: "xstate.route" });
+        return {};
+      }
+      // one atomic transition: navigation + params/query patch together
+      return {
+        target,
+        reenter: true,
+        context: { params: event.params ?? {}, query: event.query ?? {} },
+      };
+    },
+    // ...your own play.route fallbacks (e.g. a 404 route) run for unknown targets
   ],
 }
 ```
 
+For injected routes the forwarder navigates directly — navigation and the `params`/`query` patch are one atomic transition, so exit actions see the old params and no `always` transition can observe a half-navigated state. The injected `route: {}` configs keep statically-targeted `xstate.route` edges in the graph for tooling. States that declare their **own** `route` config are re-raised as `xstate.route` instead, so the user's resolver decides (including blocking — in which case context stays untouched). Unknown targets return `undefined`, falling through to any `play.route` fallbacks you define yourself.
+
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
@@ -146,61 +176,63 @@ actor.send({
 
 **`to` always uses `"#stateId"` format** — the state's `id` field prefixed with `#`. Do not pass URL paths here.
 
-### `always` Guards — Protected Routes
+### `always` Transitions — Protected Routes
 
-Use XState `always` transitions to protect states. If the guard fires, the machine redirects _before_ the state is fully entered:
+Use XState `always` transitions to protect states. An `always` transition is a function evaluated on state entry: return `{ target }` to redirect _before_ the state is fully entered, or `undefined` to stay:
 
 ```typescript
 dashboard: {
   id: "dashboard",
   meta: { route: "/dashboard" },
-  always: {
+  always: ({ context }) => {
     // If not authenticated, redirect to login immediately
-    guard: ({ context }) => !context.isAuthenticated,
-    target: "login",
+    if (context.isAuthenticated) return;
+    return { target: "login" };
   },
 },
 profile: {
   id: "profile",
   meta: { route: "/profile/:username" },
-  always: {
-    guard: ({ context }) => !context.isAuthenticated,
-    target: "login",
+  always: ({ context }) => {
+    if (context.isAuthenticated) return;
+    return { target: "login" };
   },
 },
 ```
 
-**Why `always` and not event guards?** Guards on events check "can I TAKE this transition?". `always` guards check "can I BE in this state?" — the correct invariant for authentication. The actor enforces the guard even on direct URL access (browser back/forward or deep link), because the router sends a `play.route` event which triggers the `always` guard.
+**Why `always` and not guards on events?** Guard checks inside event transitions answer "can I TAKE this transition?". `always` transitions check "can I BE in this state?" — the correct invariant for authentication. The actor enforces the check even on direct URL access (browser back/forward or deep link), because the router sends a `play.route` event which triggers the `always` transition.
 
 ### Root-Level Event Handlers
 
 Domain events placed at the root `on:` level are handled from any state:
 
 ```typescript
-const authMachine = authSetup.createMachine(
-	formatPlayRouteTransitions({
-		// ...
-		on: {
-			"auth.login": {
+const authMachine = createRoutedMachine(authSetup)({
+	// ...
+	on: {
+		"auth.login": ({ context, event }) => {
+			if (context.isAuthenticated) return;
+			return {
 				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: authSetup.assign({
+				context: {
 					isAuthenticated: true,
-					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
-				}),
-			},
-			"auth.logout": {
+					username: event.username,
+				},
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
 				target: ".home",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: authSetup.assign({
+				context: {
 					isAuthenticated: false,
 					username: null,
-				}),
-			},
+				},
+			};
 		},
-		states: {/* ... */},
-	}),
-);
+	},
+	states: {/* ... */},
+});
 ```
 
 ## Complete Actor Usage
@@ -287,7 +319,7 @@ function App() {
 | **Actor Authority (INV-01)**        | Guards on the machine validate every navigation. The router cannot change state directly.      |
 | **Passive Infrastructure (INV-04)** | The router observes `actor.currentRoute` — it never decides where to go.                       |
 | **State-Driven Reset (INV-03)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
-| **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, actions, and context are pure TypeScript.      |
+| **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, transitions, and context are pure TypeScript.  |
 
 ## Next Steps