@xmachines/play-router 6.0.0 → 7.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-6.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-7.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-router)
 
 This package extracts the routes from a machine graph and looks them up in both directions. The Actor therefore keeps the authority over the navigation.
 
@@ -97,8 +97,10 @@ routeMap.getPathByStateId("profile"); // "/profile/:userId"
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
 import type { PlayRouteEvent } from "@xmachines/play-router";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your routable machine (states carry meta.route)
 
-// machine: your routable machine (states carry meta.route)
 const actor = definePlayer({ machine })();
 actor.start();
 
@@ -136,6 +138,18 @@ a `load` function of SvelteKit — and the `meta.route` tree of the machine give
 everything below `/:machineId/play`.
 
 ```typescript
+import {
+	connectRouter,
+	type RoutableActor,
+	type RouteLookupContract,
+	type VanillaRouter,
+} from "@xmachines/play-dom-router";
+
+declare const actor: RoutableActor;
+declare const router: VanillaRouter;
+declare const routeMap: RouteLookupContract;
+declare const machineId: string;
+
 // The route of the host is /$machineId/play/$ and its loader resolved machineId.
 const disconnect = connectRouter({
 	actor,
@@ -199,6 +213,10 @@ the machine cannot shadow it.
 Read the resolved mount from the bridge instead, where it cannot go stale:
 
 ```typescript
+import type { MountableRouterBridge } from "@xmachines/play-router";
+
+declare const bridge: MountableRouterBridge;
+
 bridge.basePath; // "/abc123/play"
 bridge.basePathParams; // { machineId: "abc123" }
 ```
@@ -242,6 +260,11 @@ a rebuild.
 `setBasePath()` moves WHERE an actor is mounted, and never WHICH actor is mounted:
 
 ```typescript
+import type { MountableRouterBridge } from "@xmachines/play-router";
+
+declare const bridge: MountableRouterBridge;
+declare const machineId: string;
+
 // The host moved this actor from one region of its URL space to another.
 bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 ```
@@ -275,17 +298,40 @@ props**, wired to `setBasePath()`. They need no stable reference, unlike `actor`
 `router`, and `routeMap`, and they rebuild the bridge never:
 
 ```tsx
-// A render with a new `region` moves the mount, and it rebuilds the bridge never. A
-// render with a new `machineId` gives a different `actor` prop, and THAT rebuilds the
-// bridge, which is correct: one actor takes one bridge.
-<PlayRouterProvider
-	actor={actor}
-	router={router}
-	routeMap={routeMap}
-	basePath="/:machineId/play"
-	basePathParams={{ machineId }}
-	renderer={(a) => <PlayRenderer actor={a} registry={registry} />}
-/>
+import { RouterProvider, type createBrowserRouter } from "react-router";
+import {
+	PlayRouterProvider,
+	type RoutableActor,
+	type RouteMap,
+} from "@xmachines/play-react-router";
+
+declare const router: ReturnType<typeof createBrowserRouter>;
+
+interface MountProps {
+	region: string;
+	machineId: string;
+	/** The actor of `machineId`. Keep one actor for each machine id. */
+	actor: RoutableActor;
+	/** The route map of the machine of `machineId`. Keep one for each machine. */
+	routeMap: RouteMap;
+}
+
+function Mount({ region, machineId, actor, routeMap }: MountProps) {
+	// A render with a new `region` moves the mount, and it rebuilds the bridge never. A
+	// render with a new `machineId` comes with the actor of that machine, a different
+	// `actor` prop, and THAT rebuilds the bridge, which is correct: one actor takes one
+	// bridge.
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			basePath="/:region/:machineId/play"
+			basePathParams={{ region, machineId }}
+			renderer={(_, currentRouter) => <RouterProvider router={currentRouter} />}
+		/>
+	);
+}
 ```
 
 To register the routes of the machine in a host router that declares real route
@@ -293,6 +339,10 @@ objects, ask for the list — and drop it again when the machine unloads:
 
 ```typescript
 import { extractMachineRoutes, getRouteMappings } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your routable machine
+declare const machineId: string; // the loader of the host resolved it
 
 const tree = extractMachineRoutes(machine);
 
@@ -335,6 +385,7 @@ Extend `RouterBridgeBase`, then implement the three abstract methods for your fr
 import { RouterBridgeBase } from "@xmachines/play-router";
 import { createRouteMap } from "@xmachines/play-router/xstate";
 import type { RoutableActor } from "@xmachines/play-router";
+import type { AnyStateMachine } from "xstate";
 
 // Shape of your framework's router — adjust to its real API
 type MyRouter = {
@@ -380,6 +431,10 @@ export class MyRouterBridge extends RouterBridgeBase {
 
 // Usage — myRouter: your framework's router instance;
 // machine/actor: your routable machine and its started actor
+declare const myRouter: MyRouter;
+declare const machine: AnyStateMachine;
+declare const actor: RoutableActor;
+
 const routeMap = createRouteMap(machine);
 const bridge = new MyRouterBridge(myRouter, actor, routeMap);
 bridge.connect();
@@ -539,8 +594,10 @@ props that a framework decides, which is why it is a type parameter.
 
 ```typescript
 import { RouterSyncError, DuplicateBridgeError } from "@xmachines/play-router/errors";
+import type { RouterBridge } from "@xmachines/play-router";
+
+declare const bridge: RouterBridge; // the bridge of the adapter example above
 
-// bridge from the adapter example above
 try {
 	bridge.connect();
 } catch (err) {
@@ -558,7 +615,7 @@ try {
 
 Declare the route of an XState state node in its `meta.route` field:
 
-```typescript
+```typescript fragment
 states: {
   home: {
     id: "home",
@@ -588,24 +645,23 @@ breadcrumb. It also carries three fields that the routing layer reads:
 | --------- | -------- | ------------------------------------------------------------------------------- |
 | `path`    | required | The template of the route path                                                  |
 | `handler` | `"root"` | Where the generated `play.route` transition sits: `"root"`, `"local"`, `"both"` |
-| `reenter` | `false`  | Whether the transition re-enters its own domain. See the note below.            |
+| `reenter` | `false`  | Whether the transition re-enters its domain                                     |
 | `data`    | none     | The extra data of the route: a literal value, or a function of the event        |
 
 [`@xmachines/play-xstate`](../play-xstate/README.md) reads `handler`, `reenter`, and `data` when it generates the
 transitions. See the README of that package for what each value does.
 
-**The four names are RESERVED, and this is a change of behaviour.** An earlier release
-read `path` alone, so a state could put any name of its own beside it. A state that
-carries its own `handler` value now throws an `InvalidRouteHandlerError` at the format
-time, and the machine builds never; a state that carries its own `data` value now writes
-that value to `context.data`, where the `/context` projection of every view reads it.
-Give such a field another name.
+**The four names are RESERVED.** The routing layer reads each of them, so a field of
+your own under one of these names changes the machine. An unknown `handler` value throws
+an `InvalidRouteHandlerError` at the format time, and the machine builds never. A `data`
+value goes to `context.data`, where the `/context` projection of every view reads it.
+Give a field of your own another name.
 
 ### Relative vs absolute paths
 
 A child route that starts with `/` is absolute, and it does not inherit the path of its parent. A child route without the first `/` is relative to its nearest routable ancestor:
 
-```typescript
+```typescript fragment
 states: {
   dashboard: {
     id: "dashboard",