@xmachines/play-tanstack-react-router 1.0.0-beta.1

package/examples/demo/src/components/Navigation.tsx

@@ -0,0 +1,262 @@
+/**
+ * Navigation Component - Route Discovery UI
+ *
+ * Displays all available routes organized by category (Public, Protected, Auth).
+ * Demonstrates how UI can help users discover routes without hardcoding paths.
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+interface Route {
+	path: string;
+	label: string;
+	description: string;
+	requiresAuth: boolean;
+	authOnly: boolean;
+}
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type NavigationProps = InferComponentProps<typeof catalog, "Navigation"> & {
+	send: (event: any) => void;
+};
+
+/**
+ * All routes in the application
+ * Organized by access level for user discovery
+ */
+const ROUTES: Route[] = [
+	// Public routes (accessible anytime)
+	{
+		path: "/",
+		label: "Home",
+		description: "Landing page / Dashboard (when logged in)",
+		requiresAuth: false,
+		authOnly: false,
+	},
+	{
+		path: "/about",
+		label: "About",
+		description: "Project information",
+		requiresAuth: false,
+		authOnly: false,
+	},
+	{
+		path: "/contact",
+		label: "Contact",
+		description: "Get in touch",
+		requiresAuth: false,
+		authOnly: false,
+	},
+
+	// Protected routes (require authentication)
+	{
+		path: "/settings",
+		label: "Settings",
+		description: "Account settings",
+		requiresAuth: true,
+		authOnly: false,
+	},
+	{
+		path: "/settings/profile",
+		label: "Settings › Profile",
+		description: "Profile settings section",
+		requiresAuth: true,
+		authOnly: false,
+	},
+	{
+		path: "/profile/demo-user",
+		label: "Profile",
+		description: "User profile (example)",
+		requiresAuth: true,
+		authOnly: false,
+	},
+
+	// Auth-only routes (only when logged out)
+	{
+		path: "/login",
+		label: "Login",
+		description: "Sign in to your account",
+		requiresAuth: false,
+		authOnly: true,
+	},
+	{
+		path: "/register",
+		label: "Register",
+		description: "Create new account",
+		requiresAuth: false,
+		authOnly: true,
+	},
+];
+
+/**
+ * Navigation component with route discovery
+ *
+ * Displays routes categorized by access level:
+ * - Public: Always available
+ * - Protected: Visible but disabled when logged out
+ * - Auth: Only shown when logged out
+ */
+export function Navigation({ send, isAuthenticated, currentPath }: NavigationProps) {
+	// Filter routes by category
+	const publicRoutes = ROUTES.filter((r) => !r.requiresAuth && !r.authOnly);
+	const protectedRoutes = ROUTES.filter((r) => r.requiresAuth);
+	const authRoutes = ROUTES.filter((r) => r.authOnly);
+
+	const handleNavigate = (path: string) => {
+		// Map path to play.route event (unified navigation)
+		const eventMap: Record<string, any> = {
+			"/": { type: "play.route", to: "#home" },
+			"/about": { type: "play.route", to: "#about" },
+			"/contact": { type: "play.route", to: "#contact" },
+			"/settings": { type: "play.route", to: "#settings" },
+			"/settings/profile": {
+				type: "play.route",
+				to: "#settings",
+				params: { section: "profile" },
+			},
+			"/profile/demo-user": {
+				type: "play.route",
+				to: "#profile",
+				params: { userId: "demo-user" },
+			},
+			"/login": { type: "play.route", to: "#login" },
+			"/register": { type: "play.route", to: "#register" },
+		};
+
+		const event = eventMap[path];
+		if (event) {
+			send(event);
+		}
+	};
+
+	const buttonStyle = (path: string, disabled: boolean = false) => ({
+		padding: "10px 15px",
+		fontSize: "14px",
+		backgroundColor: currentPath === path ? "#0056b3" : "#007bff",
+		color: "white",
+		border: "none",
+		borderRadius: "4px",
+		cursor: disabled ? "not-allowed" : "pointer",
+		opacity: disabled ? 0.5 : 1,
+		transition: "background-color 0.2s",
+		textAlign: "left" as const,
+		width: "100%",
+	});
+
+	const sectionStyle = {
+		marginBottom: "20px",
+	};
+
+	const routeListStyle = {
+		display: "flex",
+		flexDirection: "column" as const,
+		gap: "8px",
+	};
+
+	const routeItemStyle = {
+		display: "flex",
+		flexDirection: "column" as const,
+		gap: "4px",
+	};
+
+	const descriptionStyle = {
+		fontSize: "12px",
+		color: "#6c757d",
+		marginLeft: "15px",
+	};
+
+	return (
+		<nav
+			style={{
+				padding: "20px",
+				backgroundColor: "#f8f9fa",
+				borderRadius: "8px",
+				marginBottom: "20px",
+			}}
+		>
+			<h2 style={{ marginTop: 0, marginBottom: "15px", fontSize: "18px" }}>
+				Available Routes
+			</h2>
+
+			{/* Public Routes */}
+			<div style={sectionStyle}>
+				<h3 style={{ fontSize: "14px", fontWeight: "600", marginBottom: "10px" }}>
+					🌍 Public Routes
+				</h3>
+				<div style={routeListStyle}>
+					{publicRoutes.map((route) => (
+						<div key={route.path} style={routeItemStyle}>
+							<button
+								onClick={() => handleNavigate(route.path)}
+								style={buttonStyle(route.path)}
+							>
+								{route.label}
+							</button>
+							<span style={descriptionStyle}>{route.description}</span>
+						</div>
+					))}
+				</div>
+			</div>
+
+			{/* Protected Routes */}
+			<div style={sectionStyle}>
+				<h3 style={{ fontSize: "14px", fontWeight: "600", marginBottom: "10px" }}>
+					🔒 Protected Routes {!isAuthenticated && "(Login required)"}
+				</h3>
+				<div style={routeListStyle}>
+					{protectedRoutes.map((route) => (
+						<div key={route.path} style={routeItemStyle}>
+							<button
+								onClick={() => handleNavigate(route.path)}
+								disabled={!isAuthenticated}
+								style={buttonStyle(route.path, !isAuthenticated)}
+							>
+								{route.label}
+								{!isAuthenticated && " 🔒"}
+							</button>
+							<span style={descriptionStyle}>{route.description}</span>
+						</div>
+					))}
+				</div>
+			</div>
+
+			{/* Auth-Only Routes */}
+			{!isAuthenticated && (
+				<div style={sectionStyle}>
+					<h3 style={{ fontSize: "14px", fontWeight: "600", marginBottom: "10px" }}>
+						🔑 Authentication
+					</h3>
+					<div style={routeListStyle}>
+						{authRoutes.map((route) => (
+							<div key={route.path} style={routeItemStyle}>
+								<button
+									onClick={() => handleNavigate(route.path)}
+									style={buttonStyle(route.path)}
+								>
+									{route.label}
+								</button>
+								<span style={descriptionStyle}>{route.description}</span>
+							</div>
+						))}
+					</div>
+				</div>
+			)}
+
+			{/* Status indicator */}
+			<div
+				style={{
+					marginTop: "20px",
+					padding: "10px",
+					backgroundColor: isAuthenticated ? "#d4edda" : "#fff3cd",
+					borderRadius: "4px",
+					fontSize: "14px",
+				}}
+			>
+				<strong>Status:</strong> {isAuthenticated ? "✓ Authenticated" : "Not authenticated"}
+			</div>
+		</nav>
+	);
+}

package/examples/demo/src/components/Profile.tsx

@@ -0,0 +1,46 @@
+/**
+ * Profile - Protected user profile page with required userId parameter
+ *
+ * Demonstrates:
+ * - Protected route (requires authentication)
+ * - Required route parameter (userId)
+ * - Parameter validation (guard checks userId exists)
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type ProfileProps = InferComponentProps<typeof catalog, "Profile"> & {
+	send: (event: any) => void;
+};
+
+export function Profile({ username, send }: ProfileProps) {
+	return (
+		<div
+			className="profile"
+			style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}
+		>
+			<h1>Profile: {username}</h1>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "20px" }}>
+				This is your profile page.
+			</p>
+			<button
+				onClick={() => send({ type: "play.route", to: "#dashboard" })}
+				style={{
+					padding: "10px 20px",
+					fontSize: "16px",
+					backgroundColor: "#6c757d",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+				}}
+			>
+				Back to Dashboard
+			</button>
+		</div>
+	);
+}

package/examples/demo/src/components/Register.tsx

@@ -0,0 +1,109 @@
+/**
+ * Register - Auth-only registration form
+ *
+ * Demonstrates:
+ * - Auth-only route (redirects to dashboard if already authenticated)
+ * - Form submission sending machine event
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+import { type FormEvent } from "react";
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type RegisterProps = InferComponentProps<typeof catalog, "Register"> & {
+	send: (event: any) => void;
+};
+
+export function Register({ title, send }: RegisterProps) {
+	const handleRegister = (e: FormEvent<HTMLFormElement>) => {
+		e.preventDefault();
+		const formData = new FormData(e.currentTarget);
+		send({
+			type: "auth.register",
+			username: formData.get("username") as string,
+			email: formData.get("email") as string,
+			password: formData.get("password") as string,
+		});
+	};
+
+	return (
+		<div
+			className="register"
+			style={{ maxWidth: "400px", margin: "50px auto", padding: "20px" }}
+		>
+			<h1>{title}</h1>
+			<form onSubmit={handleRegister}>
+				<div style={{ marginBottom: "15px" }}>
+					<label htmlFor="username" style={{ display: "block", marginBottom: "5px" }}>
+						Username
+					</label>
+					<input
+						type="text"
+						name="username"
+						id="username"
+						required
+						style={{ width: "100%", padding: "8px", fontSize: "16px" }}
+					/>
+				</div>
+				<div style={{ marginBottom: "15px" }}>
+					<label htmlFor="email" style={{ display: "block", marginBottom: "5px" }}>
+						Email
+					</label>
+					<input
+						type="email"
+						name="email"
+						id="email"
+						required
+						style={{ width: "100%", padding: "8px", fontSize: "16px" }}
+					/>
+				</div>
+				<div style={{ marginBottom: "15px" }}>
+					<label htmlFor="password" style={{ display: "block", marginBottom: "5px" }}>
+						Password
+					</label>
+					<input
+						type="password"
+						name="password"
+						id="password"
+						required
+						style={{ width: "100%", padding: "8px", fontSize: "16px" }}
+					/>
+				</div>
+				<button
+					type="submit"
+					style={{
+						width: "100%",
+						padding: "10px",
+						fontSize: "16px",
+						backgroundColor: "#28a745",
+						color: "white",
+						border: "none",
+						borderRadius: "4px",
+						cursor: "pointer",
+						marginBottom: "15px",
+					}}
+				>
+					Register
+				</button>
+			</form>
+			<button
+				onClick={() => send({ type: "play.route", to: "#login" })}
+				style={{
+					width: "100%",
+					padding: "10px",
+					fontSize: "16px",
+					backgroundColor: "#6c757d",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+				}}
+			>
+				Back to Login
+			</button>
+		</div>
+	);
+}

package/examples/demo/src/components/Settings.tsx

@@ -0,0 +1,92 @@
+/**
+ * Settings - Protected settings page with optional section parameter
+ *
+ * Demonstrates:
+ * - Protected route (requires authentication)
+ * - Optional route parameter (section)
+ * - Parameter-driven content display
+ *
+ * @invariant Passive Infrastructure - Forwards events to actor, doesn't control navigation
+ * @invariant Strict Separation - Zero router imports
+ */
+
+import type { InferComponentProps } from "@xmachines/play-catalog";
+import type { catalog } from "@xmachines/play-router-shared";
+
+type SettingsProps = InferComponentProps<typeof catalog, "Settings"> & {
+	send: (event: any) => void;
+	routeParams?: Record<string, string>;
+};
+
+export function Settings({ section, username, send, routeParams }: SettingsProps) {
+	// Use section from route params (dynamic from URL) with fallback to prop or "general"
+	const actualSection = routeParams?.section || section || "general";
+
+	return (
+		<div
+			className="settings"
+			style={{ maxWidth: "800px", margin: "50px auto", padding: "20px" }}
+		>
+			<h1>Settings - {username}</h1>
+			<p style={{ fontSize: "16px", lineHeight: "1.6", marginBottom: "20px" }}>
+				Current section: {actualSection}
+			</p>
+			<nav style={{ display: "flex", gap: "10px", marginBottom: "30px" }}>
+				<button
+					onClick={() =>
+						send({
+							type: "play.route",
+							to: "#settings",
+							params: { section: "account" },
+						})
+					}
+					style={{
+						padding: "10px 20px",
+						fontSize: "16px",
+						backgroundColor: "#007bff",
+						color: "white",
+						border: "none",
+						borderRadius: "4px",
+						cursor: "pointer",
+					}}
+				>
+					Account
+				</button>
+				<button
+					onClick={() =>
+						send({
+							type: "play.route",
+							to: "#settings",
+							params: { section: "privacy" },
+						})
+					}
+					style={{
+						padding: "10px 20px",
+						fontSize: "16px",
+						backgroundColor: "#007bff",
+						color: "white",
+						border: "none",
+						borderRadius: "4px",
+						cursor: "pointer",
+					}}
+				>
+					Privacy
+				</button>
+			</nav>
+			<button
+				onClick={() => send({ type: "play.route", to: "#home" })}
+				style={{
+					padding: "10px 20px",
+					fontSize: "16px",
+					backgroundColor: "#6c757d",
+					color: "white",
+					border: "none",
+					borderRadius: "4px",
+					cursor: "pointer",
+				}}
+			>
+				Back to Home
+			</button>
+		</div>
+	);
+}

package/examples/demo/src/components/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Component Exports
+ *
+ * Centralized exports for all demo app components.
+ * Components are framework-agnostic and receive props from PlayRenderer.
+ */
+
+export { About } from "./About.js";
+export { Contact } from "./Contact.js";
+export { Dashboard } from "./Dashboard.js";
+export { Home } from "./Home.js";
+export { Login } from "./Login.js";
+export { Navigation } from "./Navigation.js";
+export { Profile } from "./Profile.js";
+export { Register } from "./Register.js";
+export { Settings } from "./Settings.js";

package/examples/demo/src/main.tsx

@@ -0,0 +1,20 @@
+/**
+ * Application Entry Point
+ *
+ * Standard Vite + React entry point.
+ * Mounts the App component into the DOM root element.
+ */
+
+import ReactDOM from "react-dom/client";
+import App from "./App.js";
+
+// Get root element from HTML
+const rootElement = document.getElementById("root");
+
+if (!rootElement) {
+	throw new Error("Root element not found. Check index.html has <div id='root'>");
+}
+
+// Create React root and render app
+// Note: StrictMode disabled during development to avoid double-render issues with actors
+ReactDOM.createRoot(rootElement).render(<App />);

package/examples/demo/test/actor-authority.test.ts

@@ -0,0 +1,50 @@
+/**
+ * DEMO-02: Actor Authority Invariant Test
+ *
+ * Validates that Actor controls navigation via guards (Actor Authority).
+ * Guards reject invalid navigation - infrastructure doesn't decide.
+ */
+
+import { test } from "vitest";
+import { expect } from "vitest";
+import { definePlayer } from "@xmachines/play-xstate";
+import { authMachine, catalog } from "@xmachines/play-router-shared";
+
+test("DEMO-02: Actor Authority - Guards reject invalid navigation", async () => {
+	// Provide catalog so view-binding validation uses real component vocabulary
+	const createPlayer = definePlayer({ machine: authMachine, catalog });
+	const actor = createPlayer();
+	actor.start();
+
+	// Initial state: home (not authenticated)
+	expect(actor.getSnapshot().matches("home")).toBe(true);
+	expect(actor.currentRoute.get()).toBe("/");
+
+	// Navigate to login page
+	actor.send({ type: "play.route", to: "#login" });
+	expect(actor.getSnapshot().matches("login")).toBe(true);
+
+	// Attempt to navigate back to / (which should stay in home when not authenticated)
+	actor.send({ type: "play.route", to: "#home" });
+
+	// Should go to home state
+	expect(actor.getSnapshot().matches("home")).toBe(true);
+	expect(actor.currentRoute.get()).toBe("/");
+
+	// Login successfully
+	actor.send({ type: "auth.login", username: "test", password: "pass" });
+
+	// Now in dashboard state with protected route
+	expect(actor.getSnapshot().matches("dashboard")).toBe(true);
+	expect(actor.currentRoute.get()).toBe("/dashboard");
+	expect(actor.getSnapshot().context.username).toBe("test");
+
+	// Can now navigate to protected routes
+	actor.send({ type: "play.route", to: "#settings" });
+	expect(actor.getSnapshot().matches("settings")).toBe(true);
+
+	actor.stop();
+
+	// Allow microtasks to complete to prevent async activity warnings
+	await new Promise((resolve) => setTimeout(resolve, 10));
+});