@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.27

package/examples/form-validation.md

@@ -1,167 +1,239 @@
-# 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({ 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";
-
-// Define context
-interface FormContext {
-	// Context would store form data and validation state
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+// 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({
+// 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()
+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: {
+						component: "Home",
+						spec: {
+							root: "root",
+							elements: {
+								root: { type: "Home", props: { title: "Welcome" }, children: [] },
+							},
+						},
 					},
-				],
+				},
 			},
-		},
-		valid: {
-			on: {
-				RESET: "idle",
-				SUBMIT: "validating",
+
+			login: {
+				id: "login",
+				meta: {
+					route: "/login",
+					view: {
+						component: "Login",
+						spec: {
+							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: {
+						component: "Dashboard",
+						spec: {
+							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.spec` uses the `@json-render/core` spec format. 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.
-
-4. **Validation logic** - Business rules (like minimum length) are encoded as guard functions, keeping validation logic co-located with state definitions.
-
-## 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`)
-
-## Advanced Pattern: Multiple Validation Rules
+The `state:` object in the spec 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`.
 
 ```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",
-			},
-		},
-	},
-});
+// In the machine spec — the renderer handles the rest:
+spec: {
+  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
+        },
+      },
+    },
+  },
+}
 ```
 
-## Extending for Real Forms
-
-For production forms, you might add:
+## Key Concepts
 
-- **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
+- **`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`.
 
 ## Next Steps
 
-- **[Basic State Machine](basic-state-machine.md)** - Review foundational concepts
-- **[Traffic Light Example](traffic-light.md)** - See cyclic state transitions
-- **[API Documentation](../api/@xmachines/play/README.md)** - Learn about context, actions, and nested states
-- **[API Reference](../api/README.md)** - 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
+- **[play-router README](../api/@xmachines/play-router/README.md)** — Route extraction and tree building