@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/api/@xmachines/play-react/variables/PlayUIProvider.md

@@ -0,0 +1,43 @@
+[API](../../../README.md) / [@xmachines/play-react](../README.md) / PlayUIProvider
+
+# Variable: PlayUIProvider
+
+```ts
+const PlayUIProvider: React.FC<PlayUIProviderProps>;
+```
+
+Defined in: [packages/play-react/src/PlayUIProvider.tsx:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-react/src/PlayUIProvider.tsx#L102)
+
+PlayUIProvider — batteries-included entry point for actor-driven UI rendering.
+
+Combines actor lifecycle management (ActorProvider) with full UI provider setup
+(JSONUIProvider including ActionProvider, ValidationProvider, VisibilityProvider,
+StateProvider, and ConfirmDialogManager).
+
+## Example
+
+```tsx
+import { PlayUIProvider, PlayRenderer } from "@xmachines/play-react";
+
+const registryResult = defineRegistry(catalog, {
+  components: { Login, Dashboard },
+  actions: {
+    login: async ({ username }) => actor.send({ type: 'auth.login', username }),
+    logout: async () => actor.send({ type: 'auth.logout' }),
+  },
+});
+
+<PlayUIProvider actor={actor} registryResult={registryResult}>
+  <PlayRenderer />
+</PlayUIProvider>
+
+// With JSONUIProvider options:
+<PlayUIProvider
+  actor={actor}
+  registryResult={registryResult}
+  navigate={(path) => router.push(path)}
+  validationFunctions={{ isEmail: (v) => /^.+@.+$/.test(String(v)) }}
+>
+  <PlayRenderer />
+</PlayUIProvider>
+```

package/api/@xmachines/play-react-router/README.md

@@ -1,179 +1,182 @@
-[Documentation](../../README.md) / @xmachines/play-react-router
+[API](../../README.md) / @xmachines/play-react-router
 
-# @xmachines/play-react-router
+# `@xmachines/play-react-router`
 
-**React Router v7 adapter for XMachines Play using RouterBridgeBase.**
+> React Router v7 adapter for the XMachines Play Universal Player Architecture — synchronizes actor state with the browser URL bidirectionally using the `createBrowserRouter` data API.
 
-## Overview
+Part of the [XMachines Play monorepo](../../README.md).
 
-`@xmachines/play-react-router` connects `react-router` v7 data routers to Play actors.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-react-router)
 
-The package provides:
-
-- `ReactRouterBridge` for direct adapter control
-- `PlayRouterProvider` for React lifecycle wiring
-- `RouteMap` utilities for state ID <-> URL path resolution
-
-Internally, `ReactRouterBridge` extends `RouterBridgeBase` from `@xmachines/play-router`, so behavior matches other bridge adapters in the monorepo.
+---
 
 ## Installation
 
 ```bash
-npm install react react-router
-npm install @xmachines/play-react-router @xmachines/play-router @xmachines/play-react
+pnpm add @xmachines/play-react-router
 ```
 
-## Current Exports
+**Peer dependencies** — install if not already present:
+
+```bash
+pnpm add react@"^18 || ^19" react-router@"^7.0.0" xstate@"^5.31.0"
+```
 
-- `ReactRouterBridge`
-- `PlayRouterProvider` + `PlayRouterProviderProps`
-- `RouteMap`
-- `createRouteMapFromTree`
-- type re-exports: `RouterBridge`, `PlayRouteEvent`
+---
 
-Peer dependencies:
+## Usage
 
-- `react` `^18 || ^19`
-- `react-router` `^7.0.0`
+### `PlayRouterProvider` — Recommended (React component)
 
-Use `@xmachines/play-react` for framework-native rendering (`PlayRenderer`).
+`PlayRouterProvider` connects a `PlayerActor` to React Router inside a React component tree. It creates a `ReactRouterBridge` on mount, keeps actor state and the browser URL in sync bidirectionally, and tears the bridge down cleanly on unmount.
 
-## Quick Start
+> **All three props (`actor`, `router`, `routeMap`) must be stable references.** Create them outside of JSX or memoize with `useMemo`. Recreating them inline triggers a bridge disconnect/reconnect on every render.
 
 ```tsx
-import { createBrowserRouter } from "react-router";
+import { useMemo, useEffect } from "react";
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { ReactRouterBridge, createRouteMapFromTree } from "@xmachines/play-react-router";
+import { myMachine } from "./machine.js";
 
-const router = createBrowserRouter(routes);
-const actor = definePlayer({ machine, catalog })();
-actor.start();
+const createPlayer = definePlayer({ machine: myMachine });
+const routeMap = createRouteMap(myMachine);
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+function createAppRuntime() {
+	const actor = createPlayer();
+	actor.start();
+	const router = createBrowserRouter([{ path: "*", element: <App actor={actor} /> }]);
+	return { actor, router };
+}
 
-const bridge = new ReactRouterBridge(router, actor, routeMap);
-bridge.connect();
+export default function Root() {
+	const { actor, router } = useMemo(createAppRuntime, []);
 
-// later
-bridge.disconnect();
+	useEffect(() => () => actor.stop(), [actor]);
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(_, currentRouter) => <RouterProvider router={currentRouter} />}
+		/>
+	);
+}
 ```
 
-`ReactRouterBridge` requires the data-router API (`createBrowserRouter`).
-`BrowserRouter` is not supported because it does not expose subscribe/navigate APIs needed by the bridge.
+### `ReactRouterBridge` — Manual (imperative API)
 
-## API
+Use `ReactRouterBridge` directly when you need imperative lifecycle control outside React.
 
-### `ReactRouterBridge`
+> **Requires `createBrowserRouter`** (data router API). The legacy `<BrowserRouter>` component is not supported — it does not expose the `subscribe`/`navigate` API.
 
-```ts
-class ReactRouterBridge extends RouterBridgeBase {
-	constructor(
-		router: ReturnType<typeof createBrowserRouter>,
-		actor: AbstractActor<AnyActorLogic> & Routable,
-		routeMap: RouteMap,
-	);
-	connect(): void;
-	disconnect(): void;
-}
+```typescript
+import { createBrowserRouter } from "react-router";
+import { ReactRouterBridge, createRouteMap } from "@xmachines/play-react-router";
+import { myMachine } from "./machine.js";
+
+const router = createBrowserRouter([/* routes */]);
+const routeMap = createRouteMap(myMachine);
+
+const bridge = new ReactRouterBridge(router, actor, routeMap);
+bridge.connect(); // starts bidirectional sync
+// ... later:
+bridge.disconnect(); // stops sync and cleans up subscriptions
 ```
 
-Responsibilities:
+---
 
-- Watch React Router location updates and sync actor via `play.route`
-- Observe actor route changes and navigate router when state changes
-- Handle initial URL sync on cold load/deep links
+## API
 
 ### `PlayRouterProvider`
 
-React wrapper that creates/connects/disconnects `ReactRouterBridge` in `useEffect`:
+A React component that manages a `ReactRouterBridge` lifecycle via `useEffect`.
 
 ```ts
-interface PlayRouterProviderProps {
-	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
-	router: ReturnType<typeof createBrowserRouter>;
+interface PlayRouterProviderProps<TActor> {
+	/** The actor to sync with React Router. Must be a stable reference. */
+	actor: TActor;
+	/** The React Router instance returned by `createBrowserRouter`. */
+	router: BrowserRouterInstance;
+	/**
+	 * Bidirectional route map for state ID ↔ URL path lookups.
+	 * Must be a stable reference — memoize with useMemo if constructed inline.
+	 */
 	routeMap: RouteMap;
-	renderer: (
-		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
-		router: ReturnType<typeof createBrowserRouter>,
-	) => ReactNode;
+	/** Render callback — receives the actor and router. */
+	renderer: (actor: TActor, router: BrowserRouterInstance) => ReactNode;
 }
 ```
 
-### `RouteMap` and `createRouteMapFromTree`
-
-`RouteMap` extends `BaseRouteMap` from `@xmachines/play-router`, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
-
-```ts
-// RouteMap is a thin subclass of BaseRouteMap — no extra methods
-class RouteMap extends BaseRouteMap {}
+### `ReactRouterBridge`
 
-// Inherited API:
-routeMap.getStateIdByPath(path: string): string | null
-routeMap.getPathByStateId(stateId: string): string | null
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements the `RouterBridge` protocol.
 
-// Factory from a machine route tree:
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap
-```
+| Method         | Description                                                             |
+| -------------- | ----------------------------------------------------------------------- |
+| `connect()`    | Subscribes to router changes and syncs actor state from the current URL |
+| `disconnect()` | Unsubscribes and stops all synchronization                              |
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+### Types exported from this package
 
-Construct directly when you have static mappings:
+| Export                    | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `PlayRouterProviderProps` | Props interface for `PlayRouterProvider`                                   |
+| `PlayActor`               | Constraint type for actors accepted by `PlayRouterProvider` and the bridge |
 
-```ts
-import { RouteMap } from "@xmachines/play-react-router";
+### Route map utilities (re-exported from `@xmachines/play-router`)
 
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
+| Export                         | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `RouteMap`                     | Bidirectional state ID ↔ URL path map                         |
+| `createRouteMap(machine)`      | Build a `RouteMap` directly from an XState machine definition |
+| `createRouteMapFromTree(tree)` | Build a `RouteMap` from a `RouteTree` object                  |
+| `RouteMapOptions`              | Options type for `createRouteMap`                             |
+| `RouteMapping`                 | Type for a single `{ stateId, path }` entry                   |
+| `RouterBridge`                 | Interface that `ReactRouterBridge` satisfies                  |
+| `PlayRouteEvent`               | The `play.route` event type sent to actors on navigation      |
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-routeMap.getStateIdByPath("/unknown"); // null
-```
+---
 
-Or build from a machine's route tree:
+## Testing
 
-```ts
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-react-router";
+Run tests for this package in isolation:
 
-const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+```bash
+pnpm --filter @xmachines/play-react-router test
 ```
 
-## Examples
+Or from inside the package directory:
 
-- Routing patterns guide: `docs/examples/routing-patterns.md`
-- Multi-router integration guide: `docs/examples/multi-router-integration.md`
+```bash
+pnpm test
+```
 
-## Architecture
+Tests use [Vitest](https://vitest.dev/). Component tests (`*.test.tsx`) run in a `jsdom` environment via `@testing-library/react`. Unit tests (`*.test.ts`) run in Node.
 
-Bridge-first adapter flow:
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce: BACK/FORWARD navigation, `router.subscribe` callback ordering, echo suppression under real microtask timing, and subscriber teardown on `disconnect()`.
 
-1. Build route map from `extractMachineRoutes(machine)`.
-2. Connect `ReactRouterBridge` (or `PlayRouterProvider`).
-3. Router navigation emits path updates to actor via `play.route` events.
-4. Actor transitions (and guards) determine valid state.
-5. Actor route signal updates router URL when accepted.
+```bash
+# Run browser tests only
+pnpm exec vitest --config vitest.browser.config.ts --project play-react-router-browser
+```
 
-This keeps infrastructure passive and preserves Actor Authority.
+Coverage thresholds (v8 provider):
 
-## Related Packages
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 80%       |
+| Statements | 80%       |
 
-- [@xmachines/play-router](../play-router/README.md)
-- [@xmachines/play-xstate](../play-xstate/README.md)
-- [@xmachines/play-react](../play-react/README.md)
+---
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+[MIT](./LICENSE)
 
 @xmachines/play-react-router
 
@@ -187,12 +190,24 @@ Synchronizes browser URL with actor state using createBrowserRouter data API.
 
 ## Interfaces
 
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [PlayRouterProviderBaseProps](interfaces/PlayRouterProviderBaseProps.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
+## Type Aliases
+
+- [PlayRouterBridgeConstructor](type-aliases/PlayRouterBridgeConstructor.md)
+
+## Variables
+
+- [PlayRouterProvider](variables/PlayRouterProvider.md)
+
 ## Functions
 
+- [createPlayRouterProvider](functions/createPlayRouterProvider.md)
+- [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [PlayRouterProvider](functions/PlayRouterProvider.md)