@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/play-router/interfaces/PlayRouteEvent.md

@@ -1,135 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / PlayRouteEvent
-
-# Interface: PlayRouteEvent
-
-Defined in: [types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L238)
-
-The routing event, with its parameters and its query
-
-This is the one routing event of the complete Play architecture. It supports a
-navigation that knows the parameters, for example `/profile/:userId`, for a dynamic
-route segment.
-
-**Architectural context:** the event implements **Passive Infrastructure
-(INV-04)**, because it holds the navigation intent of the user, and the Actor then
-evaluates that intent with its guards. The infrastructure makes a request with a
-`play.route` event, and the Actor decides with a transition of its state machine.
-
-**The flow of a browser navigation:**
-
-1. The browser fires `popstate`
-2. The router adapter resolves the URL to a route target
-3. The adapter sends a `PlayRouteEvent` to the Actor
-4. The Actor checks the transition with the guards of its state machine
-
-## Param
-
-**type**
-
-The discriminator of the event. It is always "play.route"
-
-## Param
-
-**to**
-
-The target state ID, with a # prefix, for example '#home' or '#profile'
-
-## Param
-
-**params**
-
-The route parameters of the path only, from the URL path, for
-example `{ userId: '123' }` of `/profile/123`. The `query` field holds the query
-parameters separately.
-
-## Param
-
-**query**
-
-The query parameters only. They stay separate from the params of the path
-
-## Param
-
-**match**
-
-The complete match result of URLPattern, for the debug work and for
-the observability. It is optional
-
-## Examples
-
-The base event and the routing event together
-
-```typescript
-import type { PlayEvent } from "@xmachines/play";
-import type { PlayRouteEvent } from "@xmachines/play-router";
-
-type AppEvent = PlayEvent | PlayRouteEvent;
-```
-
-A basic navigation to a route
-
-```typescript
-import type { PlayRouteEvent } from "@xmachines/play-router";
-
-const event: PlayRouteEvent = {
-	type: "play.route",
-	to: "#home",
-};
-actor.send(event);
-```
-
-A navigation with route parameters
-
-```typescript
-import type { PlayRouteEvent } from "@xmachines/play-router";
-
-const event: PlayRouteEvent = {
-	type: "play.route",
-	to: "#profile",
-	params: { userId: "123" },
-};
-actor.send(event);
-// It resolves to the route /profile/123
-```
-
-A navigation with query parameters
-
-```typescript
-import type { PlayRouteEvent } from "@xmachines/play-router";
-
-const event: PlayRouteEvent = {
-	type: "play.route",
-	to: "#settings",
-	params: { section: "profile" }, // a route parameter of the path only
-	query: { tab: "security" }, // the query only
-};
-actor.send(event);
-// It resolves to the route /settings/profile?tab=security
-```
-
-## See
-
-[Play RFC](../../../../rfc/play.md)
-
-## Remarks
-
-Use `play.route` when you need a navigation that knows the parameters, with the
-`route: {}` config pattern on the nodes of your state machine. The `match` field
-gives you the complete URLPatternResult, for an advanced use such as a debug or an
-analysis of the pattern.
-
-## Indexable
-
-```ts
-[key: string]: unknown
-```
-
-## Properties
-
-| Property                               | Modifier   | Type                           | Defined in                                                                                                      |
-| -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:243](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L243) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L241) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L242) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L240) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L239) |

package/api/@xmachines/play-router/interfaces/RoutableActor.md

@@ -1,65 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RoutableActor
-
-# Interface: RoutableActor
-
-Defined in: [types.ts:273](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L273)
-
-The minimal actor interface that `RouterBridgeBase` and every framework router
-adapter require.
-
-This interface, and not `AbstractActor<AnyActorLogic> & Routable`, gives
-`RouterBridgeBase.actor.send` the type that accepts a `PlayRouteEvent` directly.
-It therefore removes the unsafe cast `(actor.send as (e: PlayRouteEvent) => void)`,
-which the weaker `EventObject` constraint of the actor type needed before.
-
-Every `AbstractActor` subclass satisfies this interface structurally, for two
-reasons:
-
-- `AbstractActor` implements `send(event: TEvent): void`, and `TEvent` accepts each
-  `EventObject`. Therefore it always accepts a `PlayRouteEvent`, which is a subtype.
-- `Routable` gives `currentRoute` and `initialRoute`.
-
-## Example
-
-```typescript
-import type { RoutableActor } from "@xmachines/play-router";
-
-class MyBridge extends RouterBridgeBase {
-	constructor(actor: RoutableActor, routeMap: RouteMap) {
-		super(actor, routeMap);
-	}
-}
-```
-
-## Extended by
-
-- [`PlayActor`](PlayActor.md)
-
-## Properties
-
-| Property                                          | Modifier   | Type                                                                                         | Description                                                                                                                                                                                                                              | Defined in                                                                                                      |
-| ------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\> | The TC39 Signal of the current URL path of the actor, or of its state ID.                                                                                                                                                                | [types.ts:275](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L275) |
-| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                           | The route of the initial state of the machine. The constructor fixes it. A router bridge compares it with the browser URL. It therefore separates a deep link, where the router wins, from a restore of a session, where the actor wins. | [types.ts:281](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L281) |
-
-## Methods
-
-### send()
-
-```ts
-send(event): void;
-```
-
-Defined in: [types.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L283)
-
-Sends a route navigation event to the actor.
-
-#### Parameters
-
-| Parameter | Type                                  |
-| --------- | ------------------------------------- |
-| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
-
-#### Returns
-
-`void`

package/api/@xmachines/play-router/interfaces/RouteMatch.md

@@ -1,12 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMatch
-
-# Interface: RouteMatch
-
-Defined in: [router-sync.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/router-sync.ts#L12)
-
-## Properties
-
-| Property                               | Type                              | Defined in                                                                                                                |
-| -------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/router-sync.ts#L14) |
-| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/router-sync.ts#L13) |

package/api/@xmachines/play-router/interfaces/RouteObject.md

@@ -1,21 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteObject
-
-# Interface: RouteObject
-
-Defined in: [types.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L46)
-
-A route object, with more metadata.
-
-## Indexable
-
-```ts
-[key: string]: unknown
-```
-
-The additional metadata of the route: a title, a breadcrumb, and so on
-
-## Properties
-
-| Property                          | Type     | Description                                             | Defined in                                                                                                    |
-| --------------------------------- | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | The template of the route path, for example '/user/:id' | [types.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L48) |

package/api/@xmachines/play-router/interfaces/RouteTree.md

@@ -1,21 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteTree
-
-# Interface: RouteTree
-
-Defined in: [types.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L123)
-
-The complete route tree, with its lookup maps
-
-It gives you the map between a state ID and a URL path, in both directions:
-
-- byStateId: it maps each state ID to its route node, for the target of a play.route event
-- byPath: it maps each URL path to its route node, for the browser navigation
-
-## Properties
-
-| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                      |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a complete path to its route node. It gives you the state ID of a URL path, for the target of a play.route event                                                                                                                                                                                                                                                                       | [types.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L135) |
-| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a state ID to its route node. It gives you the URL path of a state ID, for the update of the browser URL                                                                                                                                                                                                                                                                               | [types.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L130) |
-| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | The graph of the state machine, for an advanced query. extractMachineRoutes() fills it. Use it for a query of the hierarchy, for a test of the reachability, and for a navigation that knows the transitions, through the algorithms of @statelyai/graph. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L148) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | The root node of the routes                                                                                                                                                                                                                                                                                                                                                                         | [types.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L125) |

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

@@ -1,13 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / BaseRouteMapping
-
-# ~~Type Alias: BaseRouteMapping~~
-
-```ts
-type BaseRouteMapping = RouteMapping;
-```
-
-Defined in: [index.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/index.ts#L103)
-
-## Deprecated
-
-Use [RouteMapping](../interfaces/RouteMapping.md). Will be removed in the next major.

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

@@ -1,36 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / PlayRouterBridgeConstructor
-
-# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
-
-```ts
-type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
-```
-
-Defined in: [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 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
-
-| Type Parameter |
-| -------------- |
-| `TRouter`      |
-
-## Parameters
-
-| Parameter  | Type                                                  |
-| ---------- | ----------------------------------------------------- |
-| `router`   | `TRouter`                                             |
-| `actor`    | [`PlayActor`](../interfaces/PlayActor.md)             |
-| `routeMap` | [`RouteMap`](../classes/RouteMap.md)                  |
-| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md) |
-
-## Returns
-
-[`RouterBridge`](../interfaces/RouterBridge.md)

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

@@ -1,11 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMetadata
-
-# Type Alias: RouteMetadata
-
-```ts
-type RouteMetadata = string | RouteObject;
-```
-
-Defined in: [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/types.ts#L56)
-
-The route metadata of the `meta.route` field of a state machine.

package/api/@xmachines/play-solid-router/functions/createRouteMap.md

@@ -1,40 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-solid-router](../README.md) / createRouteMap
-
-# Function: createRouteMap()
-
-```ts
-function createRouteMap(machine, options?): RouteMap;
-```
-
-Defined in: [packages/play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/create-route-map.ts#L47)
-
-Creates a `RouteMap` from an XState state machine.
-
-The function reads every state with a route, which means each state with a
-`meta.route` field. It then builds the lookup structure between a path and a
-stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
-converts each change of the browser URL into a `play.route` actor event, and each
-actor route into a URL.
-
-## Parameters
-
-| Parameter  | Type                                                                      | Description                                                                                                                     |
-| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine, with a `meta.route` annotation on each state with a route.                                         |
-| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | The optional configuration. Give `{ cacheSize }` to change the default size of the LRU cache of the parameterized path lookups. |
-
-## Returns
-
-[`RouteMap`](../classes/RouteMap.md)
-
-A `RouteMap` for each adapter on `RouterBridgeBase`.
-
-## Example
-
-```typescript
-import { createRouteMap } from "@xmachines/play-router";
-import { connectRouter } from "@xmachines/play-dom-router";
-
-const routeMap = createRouteMap(myMachine);
-const disconnect = connectRouter({ actor, router, routeMap });
-```