@xmachines/docs 1.0.0-beta.10

package/examples/form-validation.md

@@ -0,0 +1,167 @@
+# Form Validation State Machine
+
+Managing form state with validation logic using guards and conditional transitions.
+
+## Use Case
+
+This example demonstrates a form with idle → validating → valid/invalid states. It's applicable to:
+
+- Login and signup forms with validation
+- Multi-step form wizards
+- Data entry forms with complex validation rules
+- Any UI requiring state-driven validation feedback
+
+## Complete Code
+
+```typescript
+import { setup } from "xstate";
+
+// Define context
+interface FormContext {
+	// Context would store form data and validation state
+}
+
+// Define events
+type FormEvent = { type: "SUBMIT"; value: string } | { type: "RESET" };
+
+// Create machine
+const formMachine = setup({
+	types: {
+		context: {} as FormContext,
+		events: {} as FormEvent,
+	},
+}).createMachine({
+	id: "form",
+	initial: "idle",
+	states: {
+		idle: {
+			on: {
+				SUBMIT: "validating",
+			},
+		},
+		validating: {
+			on: {
+				SUBMIT: [
+					{
+						target: "valid",
+						cond: (event) => event.value.length >= 3,
+					},
+					{
+						target: "invalid",
+					},
+				],
+			},
+		},
+		valid: {
+			on: {
+				RESET: "idle",
+				SUBMIT: "validating",
+			},
+		},
+		invalid: {
+			on: {
+				RESET: "idle",
+				SUBMIT: "validating",
+			},
+		},
+	},
+});
+
+// Usage
+let state = formMachine.initialState;
+console.log(state); // 'idle'
+
+// Submit with invalid input
+state = formMachine.transition(state, { type: "SUBMIT", value: "ab" });
+console.log(state); // 'validating'
+
+state = formMachine.transition(state, { type: "SUBMIT", value: "ab" });
+console.log(state); // 'invalid' (value too short)
+
+// Reset and try valid input
+state = formMachine.transition(state, { type: "RESET" });
+console.log(state); // 'idle'
+
+state = formMachine.transition(state, { type: "SUBMIT", value: "abc" });
+console.log(state); // 'validating'
+
+state = formMachine.transition(state, { type: "SUBMIT", value: "abc" });
+console.log(state); // 'valid' (meets minimum length)
+```
+
+## Code Explanation
+
+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.
+
+2. **Event payloads** - Events can carry data (`value: string`), allowing validation logic to inspect the actual input being validated.
+
+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
+
+```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",
+			},
+		},
+	},
+});
+```
+
+## Extending for Real Forms
+
+For production forms, you might add:
+
+- **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
+
+## 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

package/examples/multi-router-integration.md

@@ -0,0 +1,277 @@
+# Multi-Router Integration - Renderer Prop Pattern
+
+Learn how to integrate Play Architecture with three router modes using the unified renderer prop pattern introduced in
+
+## Overview
+
+introduces a unified multi-router architecture supporting three integration modes with consistent API:
+
+1. **TanStack Router** - React + TanStack Router with full feature set
+2. **Vanilla Router** - JSX frameworks (Preact, Solid, Vue) with framework-agnostic router
+3. **Pure Browser** - Manual integration for jQuery, Alpine, vanilla JS
+
+All modes use the **renderer prop pattern** where providers receive an `actor` and `router`, then pass a `renderer` function (not children).
+
+## Key Concepts
+
+### 1. Renderer Prop Pattern
+
+All providers use a `renderer` prop that receives the actor and returns a ReactNode:
+
+```typescript
+<PlayTanStackRouterProvider
+  actor={actor}
+  router={router}
+  renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
+/>
+```
+
+**Why renderer prop instead of children?**
+
+- Explicit dependency injection (actor passed to renderer function)
+- Type-safe integration (renderer function signature enforced)
+- Consistent pattern across all three modes
+
+### 2. RouteMap as Explicit Prop
+
+All providers require `routeMap` as an explicit prop. Routers fundamentally don't know about Play state IDs — the map bridges the gap:
+
+```typescript
+const routeTree = createPlayRouter({ machine });
+const router = createRouter({ routeTree, history: createMemoryHistory() });
+
+<PlayTanStackRouterProvider
+  actor={actor}
+  router={router}
+  routeMap={routeMap}  // Explicit mapping
+  renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
+/>
+```
+
+### 3. Provider Composition Pattern
+
+Providers wrap external providers (like TanStack's `RouterProvider`) and add Play integration layer:
+
+```typescript
+// Provider wraps TanStack RouterProvider
+<RouterProvider router={router}>
+  {/* Play integration layer */}
+  {renderer(actor)}
+</RouterProvider>
+```
+
+## Mode 1: TanStack Router (React)
+
+Complete integration with React and TanStack Router.
+
+See [multi-router-example.ts](./src/multi-router-example.ts) for runnable example.
+
+```typescript
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { createRouter, createMemoryHistory } from '@tanstack/react-router';
+import { createPlayRouter, PlayTanStackRouterProvider } from '@xmachines/play-tanstack-react-router';
+import { PlayRenderer } from '@xmachines/play-react';
+import { definePlayer } from '@xmachines/play-xstate';
+
+// 1. Create actor
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+
+// 2. Create router from machine
+const routeTree = createPlayRouter({ machine });
+const router = createRouter({
+  routeTree,
+  history: createMemoryHistory()
+});
+
+// 3. Define React components
+const components = {
+  HomeView: ({ send }) => (
+    <div>
+      <h1>Home</h1>
+      <button onClick={() => send({ type: 'play.route', to: '/about' })}>
+        Go to About
+      </button>
+    </div>
+  ),
+  AboutView: ({ send }) => (
+    <div>
+      <h1>About</h1>
+      <button onClick={() => send({ type: 'play.route', to: '/' })}>
+        Go to Home
+      </button>
+    </div>
+  )
+};
+
+// 4. Render with provider + renderer prop
+function App() {
+  return (
+    <PlayTanStackRouterProvider
+      actor={actor}
+      router={router}
+      renderer={(actor) => <PlayRenderer actor={actor} components={components} />}
+    />
+  );
+}
+
+const root = createRoot(document.getElementById('app')!);
+root.render(<StrictMode><App /></StrictMode>);
+```
+
+### Benefits
+
+- Full React ecosystem support
+- Type-safe routing with TanStack Router
+- Browser history integration automatic
+- Signal reactivity via `PlayRenderer`
+
+## Mode 2: Vanilla Router (Preact, Solid, Vue)
+
+Framework-agnostic router for JSX-based frameworks.
+
+```typescript
+import { createPlayRouter, connectRouter } from '@xmachines/play-router';
+import { definePlayer } from '@xmachines/play-xstate';
+
+// 1. Create actor
+const createPlayer = definePlayer({ machine, catalog });
+const actor = createPlayer();
+
+// 2. Create framework-agnostic router
+const router = createPlayRouter({ machine });
+
+// 3. Connect router with manual integration
+const disconnect = connectRouter(actor, {
+  onNavigate: (path) => {
+    // Update your framework's router
+    myFrameworkRouter.push(path);
+  }
+});
+
+// 4. Framework-specific rendering
+// Preact:
+import { h } from 'preact';
+const view = actor.currentView.get();
+render(h(components[view.component], viewProps), container);
+
+// Solid:
+import { Dynamic } from 'solid-js/web';
+<Dynamic component={components[view.component]} {...viewProps} />
+
+// Vue 3:
+import { h, resolveComponent } from 'vue';
+h(resolveComponent(view.component), viewProps)
+```
+
+### Benefits
+
+- Works with any JSX framework
+- Manual control over routing integration
+- No React dependency
+- Same actor/signal API
+
+## Mode 3: Pure Browser (jQuery, Alpine, Vanilla JS)
+
+Manual browser integration with no framework.
+
+```typescript
+import { createPlayRouter, connectRouter } from "@xmachines/play-router";
+
+// 1. Create actor
+const actor = createPlayer();
+
+// 2. Connect router with browser integration
+const disconnect = connectRouter(actor, {
+	onNavigate: (path) => {
+		// Update browser history
+		window.history.pushState({}, "", path);
+		renderView();
+	},
+});
+
+// 3. Manual rendering
+function renderView() {
+	const view = actor.currentView.get();
+
+	// Vanilla JS rendering
+	if (view.component === "HomeView") {
+		document.getElementById("app").innerHTML = `
+      <h1>Home</h1>
+      <button onclick="navigateToAbout()">Go to About</button>
+    `;
+	} else if (view.component === "AboutView") {
+		document.getElementById("app").innerHTML = `
+      <h1>About</h1>
+      <button onclick="navigateToHome()">Go to Home</button>
+    `;
+	}
+}
+
+// 4. Listen to browser back/forward
+window.addEventListener("popstate", () => {
+	const path = window.location.pathname;
+	actor.send({ type: "play.route", to: path });
+});
+
+// 5. Manual event handlers
+function navigateToAbout() {
+	actor.send({ type: "play.route", to: "/about" });
+}
+
+function navigateToHome() {
+	actor.send({ type: "play.route", to: "/" });
+}
+
+// Start
+actor.start();
+renderView();
+```
+
+### Benefits
+
+- No framework dependency at all
+- Maximum control and flexibility
+- Works with jQuery, Alpine.js, HTMX, etc.
+- Signals available via `actor.currentView.get()`
+
+## Provider API Parallelism
+
+All three modes follow the same pattern:
+
+| Concept     | TanStack Mode                      | Vanilla Mode                         | Pure Browser Mode          |
+| ----------- | ---------------------------------- | ------------------------------------ | -------------------------- |
+| Actor       | `createPlayer()`                   | `createPlayer()`                     | `createPlayer()`           |
+| Router      | `createRouter()` (TanStack)        | `createPlayRouter()`                 | `connectRouter()`          |
+| Integration | `<PlayTanStackRouterProvider>`     | Manual via `onNavigate` callback     | Manual + `window.popstate` |
+| Rendering   | `<PlayRenderer>` via renderer prop | Framework-specific (h, Dynamic, etc) | `innerHTML` or DOM API     |
+| Events      | Component `onClick` → `send()`     | Same                                 | Same                       |
+| Signals     | Observed by `useSignalEffect`      | Manual `actor.currentView.get()`     | Same                       |
+
+The API parallelism ensures consistent patterns regardless of mode.
+
+## Architectural Invariants
+
+All three modes preserve the 5 architectural invariants:
+
+1. **Actor Authority (INV-01):** Guards validate all navigation across all modes
+2. **Strict Separation (INV-02):** Business logic (machine) has zero framework imports
+3. **Signal-Only Reactivity (INV-05):** TC39 Signals work identically in all modes
+4. **Passive Infrastructure (INV-04):** Router observes actor, never decides
+5. **State-Driven Reset (INV-03):** Browser back/forward sends events to actor
+
+## Next Steps
+
+- **[Routing Patterns](./routing-patterns.md)** - Learn play.route events with parameters
+- **[Integration Example](./src/integration-example.ts)** - Complete authentication flow
+- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Production example using TanStack mode
+- **[Vue Router Demo](../../packages/play-vue-router/examples/demo/)** - Vue Composition API integration
+- **[SolidJS Router Demo](../../packages/play-solidjs-router/examples/demo/)** - Solid signals integration
+
+## Learn More
+
+- [play-tanstack-router README](../../packages/play-tanstack-react-router/README.md) - TanStack integration details
+- [play-react README](../../packages/play-react/README.md) - React renderer documentation
+- [play-router README](../../packages/play-router/README.md) - Framework-agnostic routing
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md) - Complete specification

package/examples/routing-patterns.md

@@ -0,0 +1,260 @@
+# Routing Patterns - Play Architecture
+
+Learn how to implement parameter-aware navigation using routing patterns with `meta.route` URL patterns and `play.route` events.
+
+## Overview
+
+introduces enhanced routing capabilities that allow state machines to handle dynamic routes with parameters while maintaining Actor Authority (INV-01). The router observes actor state changes and syncs the browser URL, but the actor decides which routes are valid through guards.
+
+## Key Concepts
+
+### Route Marker
+
+States with `meta.route` property are routable - they can receive `play.route` events and be navigated to by URL. States without `meta.route` are internal machine states that don't correspond to URLs.
+
+```typescript
+states: {
+  dashboard: {
+    meta: {
+      route: '/dashboard',  // Marks state as routable
+      view: { component: 'Dashboard' }
+    }
+  }
+}
+```
+
+### Play.route Events with Parameters
+
+Use `play.route` events to navigate with parameters. Unlike `xstate.route` (which doesn't support parameters), `play.route` allows passing data alongside navigation:
+
+```typescript
+// Navigate to profile with userId parameter
+actor.send({
+	type: "play.route",
+	to: "/profile/user123",
+	params: { userId: "user123" },
+});
+```
+
+### Parameter Patterns in meta.route
+
+Define URL patterns with `:param` syntax for required parameters and `:param?` for optional ones:
+
+```typescript
+meta: {
+  route: '/profile/:userId',        // Required parameter
+  route: '/settings/:section?',     // Optional parameter
+}
+```
+
+## Complete Example
+
+See [routing-example.ts](./src/routing-example.ts) for a complete runnable example demonstrating all patterns.
+
+### Machine Configuration
+
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const authMachine = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			userId: string;
+			routeParams: Record<string, string>;
+		},
+		events: {} as
+			| { type: "play.route"; to: string; params?: Record<string, string> }
+			| { type: "auth.login"; userId: string },
+	},
+}).createMachine({
+	initial: "login",
+	context: {
+		isAuthenticated: false,
+		userId: "",
+		routeParams: {},
+	},
+	states: {
+		login: {
+			id: "login",
+			meta: {
+				route: "/login",
+				view: { component: "LoginView" },
+			},
+			on: {
+				"auth.login": {
+					target: "profile",
+					actions: ({ context, event }) => {
+						context.isAuthenticated = true;
+						context.userId = event.userId;
+					},
+				},
+			},
+		},
+
+		profile: {
+			id: "profile",
+			meta: {
+				route: "/profile/:userId",
+				view: {
+					component: "ProfileView",
+					userId: (ctx) => ctx.routeParams.userId || ctx.userId,
+				},
+			},
+			always: [
+				{
+					target: "login",
+					guard: ({ context }) => !context.isAuthenticated,
+					// Redirect to login if not authenticated
+				},
+			],
+			on: {
+				"play.route": {
+					actions: ({ context, event }) => {
+						if (event.params?.userId) {
+							context.routeParams = { userId: event.params.userId };
+						}
+					},
+				},
+			},
+		},
+	},
+});
+
+const createPlayer = definePlayer({ machine: authMachine });
+```
+
+### Using the Actor
+
+```typescript
+// Create and start actor
+const actor = createPlayer();
+actor.start();
+
+// Login (transitions to profile)
+actor.send({ type: "auth.login", userId: "user123" });
+
+// Navigate to different profile with parameters
+actor.send({
+	type: "play.route",
+	to: "/profile/user456",
+	params: { userId: "user456" },
+});
+
+// Parameter extracted and available in view
+const view = actor.currentView.get();
+console.log(view.userId); // 'user456'
+```
+
+## Pattern Matching for Dynamic Routes
+
+Routes with parameters use pattern matching to resolve URL paths:
+
+- `/profile/:userId` matches `/profile/user123`, `/profile/alice`, etc.
+- `/settings/:section?` matches `/settings` (no section) or `/settings/privacy`
+
+The router extracts parameters from the URL and passes them in `play.route` events, which the machine stores in context for view projection.
+
+## Guard Placement Architecture
+
+**Core Principle:** Guards check if you can BE in a state (state entry), not if you can TAKE an event (event handlers).
+
+### Pattern 1: Using formatPlayRouteTransitions (RECOMMENDED)
+
+```typescript
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+const machineConfig = {
+	initial: "home",
+	context: { isAuthenticated: false },
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		profile: {
+			id: "profile",
+			meta: { route: "/profile/:userId" },
+			// Always-guard validates state entry
+			always: [
+				{
+					target: "login",
+					guard: ({ context }) => !context.isAuthenticated,
+				},
+			],
+		},
+	},
+};
+
+// Utility handles routing infrastructure
+const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+```
+
+**Why this works:**
+
+- `formatPlayRouteTransitions` adds routing infrastructure (event.to matching)
+- Always-guards handle business logic (authentication, authorization)
+- Clear separation: routing layer (infrastructure) vs validation layer (business logic)
+
+### Pattern 2: Manual Always-Guards (Advanced)
+
+For advanced users who need full control:
+
+```typescript
+const machine = createMachine({
+	context: { intendedRoute: null, isAuthenticated: false },
+	on: {
+		"play.route": {
+			actions: assign({
+				intendedRoute: ({ event }) => event.to,
+			}),
+		},
+	},
+	always: [
+		{
+			target: "profile",
+			guard: ({ context }) => context.intendedRoute === "#profile" && context.isAuthenticated,
+			reenter: true,
+		},
+		{
+			target: "login",
+			guard: ({ context }) =>
+				context.intendedRoute === "#profile" && !context.isAuthenticated,
+		},
+	],
+});
+```
+
+### Anti-Pattern: Guards on Events
+
+**NEVER do this:**
+
+```typescript
+// ❌ WRONG - Guard on event checking event property
+on: {
+  'play.route': [
+    {
+      guard: ({ event }) => event.to === "#dashboard",
+      target: "dashboard"
+    }
+  ]
+}
+```
+
+**Why this is wrong:** The state doesn't care HOW it was entered (which event triggered it). Guards should validate state invariants: "Can I BE in this state given current context?" not "Can I TAKE this event?"
+
+**Correct approach:** Use `formatPlayRouteTransitions` for routing infrastructure, use always-guards for state validation.
+
+### Actor Authority in Action
+
+This demonstrates **Actor Authority (INV-01)** — the state machine controls navigation through guards, not the router. If a guard returns `false`, the transition is rejected and the URL doesn't change.
+
+## Next Steps
+
+- **[Multi-Router Integration](./multi-router-integration.md)** - Learn about renderer prop pattern
+- **[Integration Example](./src/integration-example.ts)** - See complete authentication flow with all patterns
+- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Production example with all 5 architectural invariants
+
+## Learn More
+
+- [XState Routes Documentation](https://stately.ai/docs/routes) - Official Stately routing patterns
+- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md) - Complete architectural specification
+- [play-router README](../../packages/play-router/README.md) - Route extraction and tree building