@xmachines/docs 2.1.1 → 2.2.0

package/api/@xmachines/play-react-router/interfaces/PlayRouterProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/play-router-provider.tsx#L27)
+Defined in: [play-react-router/src/play-router-provider.tsx:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-react-router/src/play-router-provider.tsx#L27)
 
 The props of the `PlayRouterProvider` of React Router.
 
@@ -12,7 +12,7 @@ The props of the `PlayRouterProvider` of React Router.
 
 ## Extends
 
-- [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md)\<`BrowserRouterInstance`, `TActor`\>
+- [`PlayRouterProviderBaseProps`](../type-aliases/PlayRouterProviderBaseProps.md)\<`BrowserRouterInstance`, `TActor`\>
 
 ## Type Parameters
 
@@ -22,9 +22,11 @@ The props of the `PlayRouterProvider` of React Router.
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Inherited from                                                                                                                 | Defined in                                                                                                                                                                              |
-| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                         | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`actor`](PlayRouterProviderBaseProps.md#property-actor)       | [play-react-router/src/create-play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L40) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                     | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`renderer`](PlayRouterProviderBaseProps.md#property-renderer) | [play-react-router/src/create-play-router-provider.tsx:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L57) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);` | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`routeMap`](PlayRouterProviderBaseProps.md#property-routemap) | [play-react-router/src/create-play-router-provider.tsx:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L55) |
-| <a id="property-router"></a> `router`     | `Router`                             | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                             | [`PlayRouterProviderBaseProps`](PlayRouterProviderBaseProps.md).[`router`](PlayRouterProviderBaseProps.md#property-router)     | [play-react-router/src/create-play-router-provider.tsx:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L42) |
+| Property                                               | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Inherited from                               | Defined in                                                                                                                                              |
+| ------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                    | `TActor`                                   | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `PlayRouterProviderBaseProps.actor`          | [play-router/src/provider-lifecycle.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L40) |
+| <a id="property-basepath"></a> `basePath?`             | `string`                                   | Mounts the routes of the machine under a URL prefix that the host owns, so that the routes of the host and the routes of the machine share one router. `actor`, `router`, and `routeMap` each need a stable reference. This prop needs none, and it rebuilds the bridge never: a change moves the live bridge with `setBasePath()`, so a host route that renders again with a new prefix keeps the actor, the route map, and its cache. The prefix says WHERE an actor is mounted, and never WHICH actor is mounted. An actor never changes identity, so a prefix segment that IDENTIFIES the actor gives a different `actor` prop instead, and THAT rebuilds the bridge — which is correct, because one actor takes one bridge. A location outside the prefix belongs completely to the host: the bridge sends no event there, and it corrects no URL there. Every `:param` needs a value. An unresolved one throws a `MissingBasePathParamError` out of the mount effect, because the bridge writes no URL without it. Render this component only after the host holds the value, which a route loader or a `useParams()` call does already. | `PlayRouterProviderBaseProps.basePath`       | [play-router/src/provider-lifecycle.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L78) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [PlayRouterProviderBaseProps.basePath](#property-basepath), for example `{ machineId }` for `basePath="/:machineId/play"`. An inline object literal is correct here: the provider compares this prop by value, and a move to the same prefix does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `PlayRouterProviderBaseProps.basePathParams` | [play-router/src/provider-lifecycle.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L87) |
+| <a id="property-renderer"></a> `renderer`              | (`actor`, `router`) => `ReactNode`         | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `PlayRouterProviderBaseProps.renderer`       | [play-router/src/provider-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L89) |
+| <a id="property-routemap"></a> `routeMap`              | [`RouteMap`](../classes/RouteMap.md)       | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `PlayRouterProviderBaseProps.routeMap`       | [play-router/src/provider-lifecycle.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L55) |
+| <a id="property-router"></a> `router`                  | `Router`                                   | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PlayRouterProviderBaseProps.router`         | [play-router/src/provider-lifecycle.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L42) |

package/api/@xmachines/play-react-router/interfaces/RouteMapOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/create-route-map.ts#L9)
 
 The options of `createRouteMap` and of `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 | Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
 | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/create-route-map.ts#L21) |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/create-route-map.ts#L21) |

package/api/@xmachines/play-react-router/interfaces/RouteMapping.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L54)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L54)
 
 One entry of the map between a state ID and a path.
 
@@ -24,5 +24,5 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 | Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
 | --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L58) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/base-route-map.ts#L56) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-route-map.ts#L56) |

package/api/@xmachines/play-react-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L358)
+Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L359)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -56,7 +56,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L375)
+Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L376)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +86,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L391)
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L392)
 
 Disconnects the router bridge from the Actor
 

package/api/@xmachines/play-react-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -3,13 +3,18 @@
 # Type Alias: PlayRouterBridgeConstructor\<TRouter\>
 
 ```ts
-type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/create-play-router-provider.tsx#L20)
+Defined in: [play-router/src/provider-lifecycle.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/provider-lifecycle.ts#L101)
 
-The constructor shape that a bridge class must satisfy for
-`createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
+The constructor shape that a bridge class must satisfy for a provider factory: `(router, actor, routeMap, options?) → RouterBridge`.
+
+The return type is `RouterBridge`, the published contract of a bridge, so a
+consumer bridge of its own keeps compiling. Every bridge on `RouterBridgeBase` also
+satisfies `MountableRouterBridge`, and the provider finds that mount API at run
+time: a bridge without it ignores `basePath`, exactly as it did before the option
+existed.
 
 ## Type Parameters
 
@@ -19,11 +24,12 @@ The constructor shape that a bridge class must satisfy for
 
 ## Parameters
 
-| Parameter  | Type                                      |
-| ---------- | ----------------------------------------- |
-| `router`   | `TRouter`                                 |
-| `actor`    | [`PlayActor`](../interfaces/PlayActor.md) |
-| `routeMap` | [`RouteMap`](../classes/RouteMap.md)      |
+| Parameter  | Type                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `router`   | `TRouter`                                                                |
+| `actor`    | [`PlayActor`](../interfaces/PlayActor.md)                                |
+| `routeMap` | [`RouteMap`](../classes/RouteMap.md)                                     |
+| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) |
 
 ## Returns
 

package/api/@xmachines/play-react-router/type-aliases/PlayRouterProviderBaseProps.md

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-react-router](../README.md) / PlayRouterProviderBaseProps
+
+# Type Alias: PlayRouterProviderBaseProps\<TRouter, TActor\>
+
+```ts
+type PlayRouterProviderBaseProps<TRouter, TActor> = PlayRouterProviderBaseProps<
+	TRouter,
+	TActor,
+	ReactNode
+>;
+```
+
+Defined in: [play-react-router/src/create-play-router-provider.tsx:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-react-router/src/create-play-router-provider.tsx#L35)
+
+The props of a React `PlayRouterProvider`.
+
+`TRouter` is the type of the router instance of the adapter, and the node type is
+bound to `ReactNode`. See `PlayRouterProviderBaseProps` of
+`@xmachines/play-router` for what each prop means.
+
+## Type Parameters
+
+| Type Parameter                                               | Default type                              |
+| ------------------------------------------------------------ | ----------------------------------------- |
+| `TRouter`                                                    | -                                         |
+| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) | [`PlayActor`](../interfaces/PlayActor.md) |

package/api/@xmachines/play-react-router/variables/PlayRouterProvider.md

@@ -6,7 +6,7 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-react-router/src/play-router-provider.tsx#L40)
+Defined in: [play-react-router/src/play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-react-router/src/play-router-provider.tsx#L40)
 
 Connects a `PlayerActor` to React Router. It keeps the actor state and the browser
 URL in step, in both directions.
@@ -24,9 +24,9 @@ references**: create them outside the JSX, or hold them with `useMemo`.
 
 ## Parameters
 
-| Parameter           | Type                                                                                                |
-| ------------------- | --------------------------------------------------------------------------------------------------- |
-| `__namedParameters` | [`PlayRouterProviderBaseProps`](../interfaces/PlayRouterProviderBaseProps.md)\<`Router`, `TActor`\> |
+| Parameter           | Type                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `__namedParameters` | [`PlayRouterProviderBaseProps`](../type-aliases/PlayRouterProviderBaseProps.md)\<`Router`, `TActor`\> |
 
 ## Returns