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

package/test/route-map.test.ts

@@ -0,0 +1,107 @@
+/**
+ * RouteMap Unit Tests
+ *
+ * Tests bidirectional state ID ↔ path mapping with pattern matching support.
+ * React Router adapter uses same RouteMap as Solid Router.
+ */
+
+import { describe, it, expect } from "vitest";
+import { RouteMap } from "../src/route-map.js";
+
+describe("RouteMap", () => {
+	describe("construction", () => {
+		it("should create RouteMap with mappings", () => {
+			const routeMap = new RouteMap([
+				{ stateId: "#home", path: "/" },
+				{ stateId: "#profile", path: "/profile/:userId" },
+			]);
+
+			expect(routeMap).toBeDefined();
+		});
+
+		it("should handle empty mappings array", () => {
+			const routeMap = new RouteMap([]);
+
+			expect(routeMap).toBeDefined();
+		});
+	});
+
+	describe("getPathByStateId - reverse lookup", () => {
+		it("should return path for valid state ID", () => {
+			const routeMap = new RouteMap([
+				{ stateId: "#home", path: "/" },
+				{ stateId: "#profile", path: "/profile/:userId" },
+			]);
+
+			expect(routeMap.getPathByStateId("#home")).toBe("/");
+		});
+
+		it("should return path pattern for dynamic routes", () => {
+			const routeMap = new RouteMap([{ stateId: "#profile", path: "/profile/:userId" }]);
+
+			expect(routeMap.getPathByStateId("#profile")).toBe("/profile/:userId");
+		});
+
+		it("should return null for non-existent state ID", () => {
+			const routeMap = new RouteMap([{ stateId: "#home", path: "/" }]);
+
+			expect(routeMap.getPathByStateId("#nonexistent")).toBeNull();
+		});
+	});
+
+	describe("getStateIdByPath - exact match", () => {
+		it("should return state ID for exact path match", () => {
+			const routeMap = new RouteMap([
+				{ stateId: "#home", path: "/" },
+				{ stateId: "#about", path: "/about" },
+			]);
+
+			expect(routeMap.getStateIdByPath("/")).toBe("#home");
+			expect(routeMap.getStateIdByPath("/about")).toBe("#about");
+		});
+
+		it("should return null for non-existent path", () => {
+			const routeMap = new RouteMap([{ stateId: "#home", path: "/" }]);
+
+			expect(routeMap.getStateIdByPath("/nonexistent")).toBeNull();
+		});
+	});
+
+	describe("getStateIdByPath - pattern matching", () => {
+		it("should match path with required parameter", () => {
+			const routeMap = new RouteMap([{ stateId: "#profile", path: "/profile/:userId" }]);
+
+			expect(routeMap.getStateIdByPath("/profile/123")).toBe("#profile");
+			expect(routeMap.getStateIdByPath("/profile/abc")).toBe("#profile");
+		});
+
+		it("should match path with optional parameter present", () => {
+			const routeMap = new RouteMap([{ stateId: "#settings", path: "/settings/:section?" }]);
+
+			expect(routeMap.getStateIdByPath("/settings/account")).toBe("#settings");
+		});
+
+		it("should match path with optional parameter absent", () => {
+			const routeMap = new RouteMap([{ stateId: "#settings", path: "/settings/:section?" }]);
+
+			expect(routeMap.getStateIdByPath("/settings")).toBe("#settings");
+		});
+
+		it("should match nested dynamic routes", () => {
+			const routeMap = new RouteMap([
+				{ stateId: "#post", path: "/users/:userId/posts/:postId" },
+			]);
+
+			expect(routeMap.getStateIdByPath("/users/123/posts/456")).toBe("#post");
+		});
+
+		it("should prefer exact match over pattern match", () => {
+			const routeMap = new RouteMap([
+				{ stateId: "#settings-profile", path: "/settings/profile" },
+				{ stateId: "#settings", path: "/settings/:section?" },
+			]);
+
+			expect(routeMap.getStateIdByPath("/settings/profile")).toBe("#settings-profile");
+		});
+	});
+});

package/test/tanstack-router-bridge.test.ts

@@ -0,0 +1,318 @@
+/**
+ * TanStackReactRouterBridge Unit Tests
+ *
+ * Tests RouterBridge protocol compliance, bidirectional sync with Signal.subtle.Watcher pattern,
+ * and circular update prevention.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Signal } from "@xmachines/play-signals";
+import { TanStackReactRouterBridge } from "../src/tanstack-router-bridge.js";
+import { RouteMap } from "../src/route-map.js";
+
+describe("TanStackReactRouterBridge", () => {
+	let mockRouter: any;
+	let mockActor: any;
+	let routeMap: RouteMap;
+
+	beforeEach(() => {
+		// Mock TanStack React Router with router.history.subscribe
+		const historySubscribers: Set<
+			(event: { location: { pathname: string; search: string }; action: string }) => void
+		> = new Set();
+
+		mockRouter = {
+			state: {
+				location: {
+					pathname: "/",
+					search: "",
+				},
+			},
+			navigate: vi.fn(),
+			history: {
+				subscribe: vi.fn((fn: (event: any) => void) => {
+					historySubscribers.add(fn);
+					return () => historySubscribers.delete(fn);
+				}),
+				location: { pathname: "/", search: "" },
+			},
+			// Helper: trigger a navigation event (simulates PUSH, POP, BACK, FORWARD)
+			_triggerNavigation: (pathname: string, search = "", action = "PUSH") => {
+				mockRouter.state.location.pathname = pathname;
+				mockRouter.state.location.search = search;
+				mockRouter.history.location.pathname = pathname;
+				mockRouter.history.location.search = search;
+				historySubscribers.forEach((fn) => fn({ location: { pathname, search }, action }));
+			},
+		};
+
+		// Mock actor with Signal.State
+		const currentRoute = new Signal.State<string | null>("/");
+		mockActor = {
+			currentRoute,
+			send: vi.fn(),
+		};
+
+		// Simple RouteMap
+		routeMap = new RouteMap([
+			{ stateId: "#home", path: "/" },
+			{ stateId: "#dashboard", path: "/dashboard" },
+			{ stateId: "#settings", path: "/settings/:section?" },
+		]);
+	});
+
+	describe("RouterBridge protocol compliance", () => {
+		it("should implement connect() method", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			expect(bridge.connect).toBeDefined();
+			expect(typeof bridge.connect).toBe("function");
+		});
+
+		it("should implement disconnect() method", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			expect(bridge.disconnect).toBeDefined();
+			expect(typeof bridge.disconnect).toBe("function");
+		});
+
+		it("should not throw when calling connect()", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			expect(() => bridge.connect()).not.toThrow();
+		});
+
+		it("should not throw when calling disconnect()", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+			expect(() => bridge.disconnect()).not.toThrow();
+		});
+	});
+
+	describe("actor → router sync", () => {
+		it("should navigate router when actor state changes", async () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockRouter.navigate.mockClear();
+
+			// Trigger signal change
+			mockActor.currentRoute.set("/dashboard");
+
+			// Wait for watcher callback and its internal microtask
+			await new Promise((resolve) => setTimeout(resolve, 10));
+
+			expect(mockRouter.navigate).toHaveBeenCalledWith({ to: "/dashboard" });
+		});
+
+		it("should skip navigation if path unchanged (lastSyncedPath guard)", async () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockActor.currentRoute.set("/dashboard");
+			await new Promise((resolve) => setTimeout(resolve, 0));
+
+			mockRouter.navigate.mockClear();
+
+			// Set same path again
+			mockActor.currentRoute.set("/dashboard");
+			await new Promise((resolve) => setTimeout(resolve, 0));
+
+			expect(mockRouter.navigate).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("router → actor sync", () => {
+		it("should send play.route event when router navigates (PUSH)", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockActor.send.mockClear();
+
+			mockRouter._triggerNavigation("/dashboard", "", "PUSH");
+
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({
+					type: "play.route",
+					to: "#dashboard",
+				}),
+			);
+		});
+
+		it("should send play.route event for BACK navigation", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			// First navigate forward
+			mockRouter._triggerNavigation("/dashboard", "", "PUSH");
+			mockActor.send.mockClear();
+
+			// Then go back
+			mockRouter._triggerNavigation("/", "", "BACK");
+
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({
+					type: "play.route",
+					to: "#home",
+				}),
+			);
+		});
+
+		it("should send play.route event for FORWARD navigation", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			// Navigate to /dashboard first so lastSyncedPath is "/"
+			mockRouter._triggerNavigation("/dashboard", "", "PUSH");
+			mockActor.send.mockClear();
+
+			// Then back to /, then forward to /dashboard
+			mockRouter._triggerNavigation("/", "", "BACK");
+			mockActor.send.mockClear();
+
+			mockRouter._triggerNavigation("/dashboard", "", "FORWARD");
+
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({
+					type: "play.route",
+					to: "#dashboard",
+				}),
+			);
+		});
+
+		it("should extract parameters from URL", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockActor.send.mockClear();
+
+			mockRouter._triggerNavigation("/settings/account", "");
+
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({
+					type: "play.route",
+					to: "#settings",
+					params: { section: "account" },
+				}),
+			);
+		});
+
+		it("should extract query parameters", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			// Navigate to /dashboard first so "/" is not lastSyncedPath
+			mockRouter._triggerNavigation("/dashboard", "");
+			mockActor.send.mockClear();
+
+			mockRouter._triggerNavigation("/", "?tab=home&view=grid");
+
+			expect(mockActor.send).toHaveBeenCalledWith(
+				expect.objectContaining({
+					type: "play.route",
+					to: "#home",
+					query: { tab: "home", view: "grid" },
+				}),
+			);
+		});
+
+		it("should skip send if state ID not found", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockActor.send.mockClear();
+
+			mockRouter._triggerNavigation("/unknown", "");
+
+			expect(mockActor.send).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("getInitialRouterPath", () => {
+		it("should return current router pathname for initial sync", () => {
+			mockRouter.state.location.pathname = "/dashboard";
+
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			const initialPath = (bridge as any).getInitialRouterPath();
+			expect(initialPath).toBe("/dashboard");
+		});
+
+		it("should return null if router.state is missing", () => {
+			mockRouter.state = undefined;
+
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			const initialPath = (bridge as any).getInitialRouterPath();
+			expect(initialPath).toBeNull();
+		});
+	});
+
+	describe("circular update prevention", () => {
+		it("should prevent actor → router → actor loops", async () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockActor.send.mockClear();
+			mockRouter.navigate.mockClear();
+
+			// Actor changes route → should navigate router
+			mockActor.currentRoute.set("/dashboard");
+			await new Promise((resolve) => setTimeout(resolve, 0));
+
+			expect(mockRouter.navigate).toHaveBeenCalledTimes(1);
+
+			// Simulate router firing history event for that navigation
+			// (this is the round-trip that should be suppressed)
+			mockRouter._triggerNavigation("/dashboard", "", "PUSH");
+			await new Promise((resolve) => setTimeout(resolve, 0));
+
+			// Should still be 1 — no circular navigation
+			expect(mockRouter.navigate).toHaveBeenCalledTimes(1);
+		});
+
+		it("should skip redundant updates (same path)", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			mockRouter._triggerNavigation("/dashboard", "");
+			mockActor.send.mockClear();
+
+			// Same path again
+			mockRouter._triggerNavigation("/dashboard", "");
+
+			expect(mockActor.send).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("cleanup", () => {
+		it("should subscribe to router.history on connect", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+
+			expect(mockRouter.history.subscribe).toHaveBeenCalledWith(expect.any(Function));
+		});
+
+		it("should unsubscribe from router.history on disconnect", () => {
+			const unsubscribeSpy = vi.fn();
+			mockRouter.history.subscribe.mockReturnValue(unsubscribeSpy);
+
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+			bridge.disconnect();
+
+			expect(unsubscribeSpy).toHaveBeenCalled();
+		});
+
+		it("should clear routerUnsubscribe after disconnect", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+			bridge.disconnect();
+
+			expect((bridge as any).routerUnsubscribe).toBeNull();
+		});
+	});
+
+	describe("Signal.subtle.Watcher integration", () => {
+		it("should create watcher on connect (routeWatcher from base class)", () => {
+			const bridge = new TanStackReactRouterBridge(mockRouter, mockActor, routeMap);
+			bridge.connect();
+			expect((bridge as any).routeWatcher).toBeDefined();
+		});
+	});
+});

package/test/urlpattern-integration.test.ts

@@ -0,0 +1,145 @@
+/**
+ * URLPattern integration tests for extractParams()
+ * Tests URLPattern.exec() implementation for parameter extraction
+ */
+
+import { describe, test, expect, vi } from "vitest";
+
+// Import the actual extractParams implementation by creating a history instance
+// and extracting the function. This tests the real implementation.
+// Note: extractParams is a private function in signal-synced-history.ts
+// For testing, we'll import the module and test via the class usage
+
+// We can't directly import extractParams (it's private), so we'll test it
+// indirectly via the signal-synced-history.ts module.
+// Create a test version that matches the implementation signature.
+
+/**
+ * extractParams implementation from signal-synced-history.ts
+ * Uses URLPattern API for robust pattern matching
+ */
+function extractParams(
+	path: string,
+	pattern: string | undefined,
+): { params: Record<string, string>; match?: URLPatternResult } {
+	if (!pattern) {
+		return { params: {} };
+	}
+
+	try {
+		// Normalize path by removing trailing slash (except for root "/")
+		// URLPattern is strict about trailing slashes
+		const normalizedPath = path === "/" || !path.endsWith("/") ? path : path.slice(0, -1);
+
+		// Create URLPattern for pathname matching
+		const urlPattern = new URLPattern({ pathname: pattern });
+
+		// Execute pattern match against path
+		const match = urlPattern.exec({ pathname: normalizedPath });
+
+		if (!match) {
+			return { params: {} };
+		}
+
+		// Extract named groups from pathname component
+		const groups = match.pathname.groups || {};
+		const params: Record<string, string> = {};
+
+		Object.keys(groups).forEach((key) => {
+			const value = groups[key];
+			if (value !== undefined) {
+				// Decode URI component to handle URL encoding (%20 → space, etc.)
+				params[key] = decodeURIComponent(value);
+			}
+		});
+
+		return {
+			params,
+			match, // Full result for observability
+		};
+	} catch (error) {
+		// Invalid pattern (e.g., malformed regex) - log and return empty
+		console.error(`[extractParams] Invalid pattern: ${pattern}`, error);
+		return { params: {} };
+	}
+}
+
+describe("URLPattern integration - extractParams()", () => {
+	test("extracts simple parameter from /profile/:userId pattern", () => {
+		const result = extractParams("/profile/alice", "/profile/:userId");
+
+		expect(result).toHaveProperty("params");
+		expect(result.params).toEqual({ userId: "alice" });
+		expect(result).toHaveProperty("match");
+	});
+
+	test("handles optional parameter /settings/:section? with and without value", () => {
+		// With section parameter
+		const withSection = extractParams("/settings/account", "/settings/:section?");
+		expect(withSection.params).toEqual({ section: "account" });
+
+		// Without section parameter
+		const withoutSection = extractParams("/settings", "/settings/:section?");
+		expect(withoutSection.params).toEqual({});
+	});
+
+	test("validates regex constraint /api/:id(\\d+) for numeric IDs only", () => {
+		// Should match numeric ID
+		const numericResult = extractParams("/api/123", "/api/:id(\\d+)");
+		expect(numericResult.params).toEqual({ id: "123" });
+
+		// Should NOT match alphabetic ID
+		const alphaResult = extractParams("/api/abc", "/api/:id(\\d+)");
+		expect(alphaResult.params).toEqual({});
+	});
+
+	test("matches wildcard pattern /docs/* for nested paths", () => {
+		// Single level
+		const singleLevel = extractParams("/docs/intro", "/docs/*");
+		expect(singleLevel.params).toBeDefined();
+
+		// Multiple levels
+		const multiLevel = extractParams("/docs/guides/advanced", "/docs/*");
+		expect(multiLevel.params).toBeDefined();
+	});
+
+	test("automatically decodes URL-encoded parameters", () => {
+		// %20 should decode to space
+		const result = extractParams("/search/hello%20world", "/search/:q");
+		expect(result.params).toEqual({ q: "hello world" });
+	});
+
+	test("handles invalid pattern gracefully with empty params", () => {
+		const errorSpy = vi
+			.spyOn(console, "error")
+			.mockImplementation((..._args: unknown[]) => undefined);
+		// Malformed pattern should return empty params
+		const result = extractParams("/profile/alice", "/:invalid(()");
+		expect(result.params).toEqual({});
+		errorSpy.mockRestore();
+	});
+
+	test("returns URLPatternResult in match field for observability", () => {
+		const result = extractParams("/profile/alice", "/profile/:userId");
+
+		expect(result).toHaveProperty("match");
+		expect(result.match).toBeDefined();
+		// URLPatternResult has pathname.groups
+		expect(result.match).toHaveProperty("pathname");
+		expect(result.match?.pathname).toHaveProperty("groups");
+	});
+
+	test("handles edge cases: empty pattern, no params, trailing slashes", () => {
+		// Empty/undefined pattern
+		const emptyResult = extractParams("/profile/alice", undefined);
+		expect(emptyResult.params).toEqual({});
+
+		// Pattern with no parameters
+		const noParamsResult = extractParams("/about", "/about");
+		expect(noParamsResult.params).toEqual({});
+
+		// Trailing slash handling
+		const trailingResult = extractParams("/profile/alice/", "/profile/:userId");
+		expect(trailingResult.params).toEqual({ userId: "alice" });
+	});
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "@xmachines/shared/tsconfig",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": ["ESNext", "DOM"],
+    "jsx": "react-jsx"
+  },
+  "references": [
+    { "path": "../play-actor" },
+    { "path": "../play-router" },
+    { "path": "../play-signals" }
+  ],
+  "include": ["src/**/*"]
+}