@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/examples/form-validation.md

@@ -1,167 +1,308 @@
-# Form Validation State Machine
+# Form Validation with Typed Context
 
-Managing form state with validation logic using guards and conditional transitions.
+Managing login form state using `setup({ types })`, typed `assign`, guards, and `meta.view` with `$bindState`.
 
 ## Use Case
 
-This example demonstrates a form with idle → validating → valid/invalid states. It's applicable to:
+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:
 
-- Login and signup forms with validation
-- Multi-step form wizards
-- Data entry forms with complex validation rules
-- Any UI requiring state-driven validation feedback
+- Typed context mutations with `setup.assign`
+- Guards as inline functions checking context
+- `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";
 
-// Define context
-interface FormContext {
-	// Context would store form data and validation state
+// Context shape
+interface LoginContext {
+	isAuthenticated: boolean;
+	username: string | null;
+	errorMessage: string | null;
+	params: Record<string, string>;
+	query: Record<string, string>;
 }
 
-// Define events
-type FormEvent = { type: "SUBMIT"; value: string } | { type: "RESET" };
+// 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" };
 
-// Create machine
-const formMachine = setup({
+// 1. Typed setup — always use setup() before createMachine()
+const loginSetup = setup({
 	types: {
-		context: {} as FormContext,
-		events: {} as FormEvent,
+		context: {} as LoginContext,
+		events: {} as LoginEvent,
+		input: {} as Partial<LoginContext> | undefined,
 	},
-}).createMachine({
-	id: "form",
-	initial: "idle",
-	states: {
-		idle: {
-			on: {
-				SUBMIT: "validating",
+});
+
+// 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": {
+				target: ".dashboard",
+				// Guard: allow login only when not already authenticated
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: loginSetup.assign({
+					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": {
+				target: ".idle",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: loginSetup.assign({
+					isAuthenticated: false,
+					username: null,
+				}),
 			},
 		},
-		validating: {
-			on: {
-				SUBMIT: [
-					{
-						target: "valid",
-						cond: (event) => event.value.length >= 3,
-					},
-					{
-						target: "invalid",
+
+		states: {
+			idle: {
+				id: "idle",
+				meta: {
+					route: "/",
+					view: {
+						root: "root",
+						elements: {
+							root: { type: "Home", props: { title: "Welcome" }, children: [] },
+						},
 					},
-				],
+				},
 			},
-		},
-		valid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
+
+			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" } },
+									},
+								},
+							},
+						},
+					},
+				},
 			},
-		},
-		invalid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
+
+			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",
+				},
 			},
 		},
-	},
-});
+	}),
+);
 
-// Usage
-let state = formMachine.initialState;
-console.log(state); // 'idle'
+// 3. Factory and actor
+const createPlayer = definePlayer({ machine: loginMachine });
+const actor = createPlayer();
+actor.start();
 
-// Submit with invalid input
-state = formMachine.transition(state, { type: "SUBMIT", value: "ab" });
-console.log(state); // 'validating'
+// 4. Navigate to login page
+actor.send({ type: "play.route", to: "#login" });
+console.log(actor.getSnapshot().value); // "login"
 
-state = formMachine.transition(state, { type: "SUBMIT", value: "ab" });
-console.log(state); // 'invalid' (value too short)
+// 5. Login with username
+actor.send({ type: "auth.login", username: "alice" });
+console.log(actor.getSnapshot().value); // "dashboard"
+console.log(actor.getSnapshot().context.username); // "alice"
 
-// Reset and try valid input
-state = formMachine.transition(state, { type: "RESET" });
-console.log(state); // 'idle'
+// 6. Guard prevents re-login while authenticated
+actor.send({ type: "auth.login", username: "bob" }); // guard fires, transition rejected
+console.log(actor.getSnapshot().context.username); // still "alice"
 
-state = formMachine.transition(state, { type: "SUBMIT", value: "abc" });
-console.log(state); // 'validating'
+// 7. Logout
+actor.send({ type: "auth.logout" });
+console.log(actor.getSnapshot().value); // "idle"
+console.log(actor.getSnapshot().context.username); // null
 
-state = formMachine.transition(state, { type: "SUBMIT", value: "abc" });
-console.log(state); // 'valid' (meets minimum length)
+actor.stop();
 ```
 
-## Code Explanation
+## `$bindState` and `$state` Pattern
 
-1. **Guards (conditional transitions)** - The `cond` property defines a function that determines which transition to take. If the condition returns `true`, that transition is used; otherwise, the next transition in the array is tried.
+`meta.view` uses the `@xmachines/json-render-core` spec format (`PlaySpec`). Two special directives wire the component to a local per-state state store:
 
-2. **Event payloads** - Events can carry data (`value: string`), allowing validation logic to inspect the actual input being validated.
+| Directive                     | Direction | Usage                                                       |
+| ----------------------------- | --------- | ----------------------------------------------------------- |
+| `{ $bindState: "/username" }` | Two-way   | Prop reads and writes the state store key `/username`       |
+| `{ $state: "/username" }`     | Read-only | Reads the current value from the state store at `/username` |
 
-3. **Multiple transitions per event** - When an event can lead to different states based on conditions, use an array of transition objects with guards.
+The `state:` key in `meta.view` sets the initial values for the local store. When the user types in the form field, the renderer keeps the store in sync. On submit, action params read the final value via `$state`.
 
-4. **Validation logic** - Business rules (like minimum length) are encoded as guard functions, keeping validation logic co-located with state definitions.
+```typescript
+// In the machine meta.view — the renderer handles the rest:
+view: {
+  root: "root",
+  state: { username: "" },         // initial store value
+  elements: {
+    root: {
+      type: "Login",
+      props: {
+        username: { $bindState: "/username" }, // two-way binding
+      },
+      on: {
+        submit: {
+          action: "login",
+          params: { username: { $state: "/username" } }, // read on submit
+        },
+      },
+    },
+  },
+}
+```
 
 ## Key Concepts
 
-- **Guards**: Functions that conditionally allow or prevent transitions based on event data or current state
-- **Event payloads**: Events can carry data beyond just the event type
-- **Conditional transitions**: Array of transitions where the first matching guard is taken
-- **State-driven UI**: UI can render different feedback based on state (loading spinner in `validating`, error message in `invalid`)
+- **`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.
+- **Lowercase dot-separated event types**: `"auth.login"`, `"auth.logout"`, `"play.route"` — not `SCREAMING_SNAKE_CASE`.
+
+## Connecting the Renderer
 
-## Advanced Pattern: Multiple Validation Rules
+The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from `@xmachines/play-dom`:
 
 ```typescript
-const advancedFormMachine = createMachine<FormState, FormEvent>({
-	id: "advancedForm",
-	initial: "idle",
-	states: {
-		idle: {
-			on: { SUBMIT: "validating" },
-		},
-		validating: {
-			on: {
-				SUBMIT: [
-					{
-						target: "valid",
-						cond: (event) => {
-							const value = event.value;
-							return (
-								value.length >= 3 &&
-								value.length <= 20 &&
-								/^[a-zA-Z0-9]+$/.test(value)
-							);
-						},
-					},
-					{ target: "invalid" },
-				],
-			},
-		},
-		valid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
-			},
-		},
-		invalid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
-			},
-		},
+import { createRenderer, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { z } from "zod";
+import type { ComponentFn } from "@xmachines/play-dom";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({ title: z.string(), username: z.string().optional() }) },
+		Dashboard: { props: z.object({ title: z.string() }) },
+	},
+	actions: {
+		// Must declare all actions that appear in meta.view on-bindings
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
 	},
 });
-```
+type AppCatalog = typeof catalog;
+
+// Component implementations receive typed props + emit/on helpers
+const Home: ComponentFn<AppCatalog, "Home"> = ({ props }) => {
+	const el = document.createElement("section");
+	el.textContent = props.title;
+	return el;
+};
+
+const Login: ComponentFn<AppCatalog, "Login"> = ({ props, on, ctx }) => {
+	const section = document.createElement("section");
+	const input = document.createElement("input");
+	input.value = props.username ?? "";
+	// Keep the local state store in sync as the user types
+	input.addEventListener("input", () => {
+		ctx.store.update((s) => ({ ...s, username: input.value }));
+	});
+	const button = document.createElement("button");
+	button.textContent = "Log In";
+	const submit = on("submit"); // bound to the spec's on.submit binding
+	button.addEventListener("click", () => submit.emit()); // resolves $state, calls login action
+	section.append(input, button);
+	return section;
+};
+
+const Dashboard: ComponentFn<AppCatalog, "Dashboard"> = ({ props, on }) => {
+	const section = document.createElement("section");
+	section.textContent = props.title;
+	const btn = document.createElement("button");
+	btn.textContent = "Log Out";
+	const logout = on("logout");
+	btn.addEventListener("click", () => logout.emit());
+	section.append(btn);
+	return section;
+};
 
-## Extending for Real Forms
+// createRenderer builds the factory once — call mount() when the actor is ready
+const mount = createRenderer(catalog, { Home, Login, Dashboard });
+
+const actor = createPlayer();
+actor.start();
+
+const disconnect = mount(actor, document.getElementById("app")!);
+
+// Cleanup
+window.addEventListener("beforeunload", () => {
+	disconnect();
+	actor.stop();
+});
+```
 
-For production forms, you might add:
+**Key points:**
 
-- **Context**: Store error messages and validation details
-- **Actions**: Side effects like API calls or analytics tracking
-- **Nested states**: Break down `validating` into `checkingFormat`, `checkingUniqueness`, etc.
-- **History states**: Return to the last valid/invalid state after interruption
+- `actions` in `defineCatalog` must include every action name referenced in `meta.view` `on:` bindings. TypeScript enforces this via `CatalogHasActions`.
+- `on("submit").emit()` resolves `params` from the current state store at call time — the `$state: "/username"` in the spec is read at that moment, not at render time.
+- `ctx.store.update(fn)` is the standard write path for two-way binding. The spec's `$bindState` directive only wires the read direction (prop ← store); the write direction (store ← input) must be implemented in the component.
 
 ## Next Steps
 
-- **[Basic State Machine](basic-state-machine.md)** - Review foundational concepts
-- **[Traffic Light Example](traffic-light.md)** - See cyclic state transitions
-- **[API Documentation](/docs/api/xmachines/play/readme)** - Learn about context, actions, and nested states
-- **[Architecture Guides](/docs/api/guides/core-concepts)** - Understand design patterns and best practices
+- **[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
+- **[`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