@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/examples/form-validation.md

@@ -1,167 +1,319 @@
-# Form Validation State Machine
+<!-- generated-by: gsd-doc-writer -->
 
-Managing form state with validation logic using guards and conditional transitions.
+# Form Validation with Typed Context
+
+Managing login form state using `setup({ schemas })`, typed context patches, guard logic in transition functions, 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 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 { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} 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" };
-
-// Create machine
-const formMachine = setup({
-	types: {
-		context: {} as FormContext,
-		events: {} as FormEvent,
+// 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({
+	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,
 	},
-}).createMachine({
-	id: "form",
+});
+
+// 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",
+				context: {
+					isAuthenticated: true,
+					errorMessage: null,
+					// Typed by the event schema — event.username is already narrowed
+					username: event.username,
+				},
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
+				target: ".idle",
+				context: {
+					isAuthenticated: false,
+					username: null,
+				},
+			};
+		},
+	},
+
 	states: {
 		idle: {
-			on: {
-				SUBMIT: "validating",
+			id: "idle",
+			meta: {
+				route: "/",
+				view: {
+					root: "root",
+					elements: {
+						root: { type: "Home", props: { title: "Welcome" }, children: [] },
+					},
+				},
 			},
 		},
-		validating: {
-			on: {
-				SUBMIT: [
-					{
-						target: "valid",
-						cond: (event) => event.value.length >= 3,
-					},
-					{
-						target: "invalid",
+
+		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" } },
+								},
+							},
+						},
 					},
-				],
+				},
 			},
 		},
-		valid: {
-			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" },
+							},
+						},
+					},
+				},
 			},
-		},
-		invalid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
+			// always-transition: redirect to login if not authenticated
+			always: ({ context }) => {
+				if (context.isAuthenticated) return;
+				return { 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" }); // early return — 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({ 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`.
 
-## Advanced Pattern: Multiple Validation Rules
+## Connecting the Renderer
+
+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 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