@xmachines/docs 1.0.0-beta.10

package/api/@xmachines/play-solid-router/classes/RouteMap.md

@@ -0,0 +1,150 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / RouteMap
+
+# Class: RouteMap
+
+Defined in: [packages/play-solid-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/route-map.ts#L26)
+
+Shared bidirectional route map base class.
+
+All framework adapter `RouteMap` classes extend this — they add no logic of their
+own and inherit the full public API from here.
+
+**Lookup strategy:**
+
+- Static paths (no `:param`) → O(1) `Map` lookup
+- Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+  of routes sharing the same first path segment
+- Results are cached after the first match
+
+**Pattern syntax** (`:param` / `:param?`):
+
+- `:param` — required segment, matches exactly one non-`/` segment
+- `:param?` — optional segment, matches zero or one non-`/` segment
+
+## Example
+
+```typescript
+import { BaseRouteMap } from "@xmachines/play-router";
+
+const map = new BaseRouteMap([
+	{ stateId: "home", path: "/" },
+	{ stateId: "profile", path: "/profile/:userId" },
+	{ stateId: "settings", path: "/settings/:section?" },
+]);
+
+map.getStateIdByPath("/"); // "home"
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/settings"); // "settings"
+map.getStateIdByPath("/unknown"); // null
+
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+## Extends
+
+- [`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new RouteMap(mappings): RouteMap;
+```
+
+Defined in: packages/play-router/dist/base-route-map.d.ts:81
+
+Build a route map from an array of state ID ↔ path mappings.
+
+Static paths (no `:param`) are indexed in an O(1) `Map`.
+Parameterized paths are compiled to `RegExp` and grouped into first-segment
+buckets for efficient candidate selection.
+
+#### Parameters
+
+| Parameter  | Type                                                                     | Description                                                                                                       |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`BaseRouteMapping`](../../play-router/interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+
+#### Returns
+
+`RouteMap`
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`constructor`](../../play-router/classes/BaseRouteMap.md#constructor)
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(stateId): string | null;
+```
+
+Defined in: packages/play-router/dist/base-route-map.d.ts:111
+
+Look up the path pattern registered for a state ID.
+
+#### Parameters
+
+| Parameter | Type     | Description                                               |
+| --------- | -------- | --------------------------------------------------------- |
+| `stateId` | `string` | State machine state ID (e.g., `"profile"`, `"#settings"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The registered path pattern, or `null` if the state ID is unknown
+
+#### Example
+
+```typescript
+map.getPathByStateId("profile"); // "/profile/:userId"
+map.getPathByStateId("missing"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getPathByStateId`](../../play-router/classes/BaseRouteMap.md#getpathbystateid)
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null;
+```
+
+Defined in: packages/play-router/dist/base-route-map.d.ts:98
+
+Resolve a URL path to its mapped state ID.
+
+Strips query strings and hash fragments before matching. Tries an O(1) exact
+lookup first, then falls back to bucket-indexed pattern matching. Results are
+cached after the first pattern match.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------ |
+| `path`    | `string` | URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`) |
+
+#### Returns
+
+`string` \| `null`
+
+The mapped state ID, or `null` if no route matches
+
+#### Example
+
+```typescript
+map.getStateIdByPath("/profile/123"); // "profile"
+map.getStateIdByPath("/unknown"); // null
+```
+
+#### Inherited from
+
+[`BaseRouteMap`](../../play-router/classes/BaseRouteMap.md).[`getStateIdByPath`](../../play-router/classes/BaseRouteMap.md#getstateidbypath)

package/api/@xmachines/play-solid-router/classes/SolidRouterBridge.md

@@ -0,0 +1,347 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / SolidRouterBridge
+
+# Class: SolidRouterBridge
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L47)
+
+SolidJS Router integration bridge extending RouterBridgeBase
+
+Implements RouterBridge protocol for SolidJS Router using Solid's reactive
+primitives. The actor→router direction uses TC39 Signal watcher (from base class).
+The router→actor direction uses Solid's createEffect for native reactivity.
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new SolidRouterBridge(
+   solidNavigate,
+   location,
+   _params,
+   actor,
+   routeMap): SolidRouterBridge;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L59)
+
+Create a SolidJS Router bridge
+
+**CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
+
+#### Parameters
+
+| Parameter           | Type                                                                                                                         | Description                           |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `solidNavigate`     | (`path`, ...`args`) => `unknown`                                                                                             | Result of useNavigate() hook          |
+| `location`          | \{ `pathname`: `string`; `search`: `string`; \}                                                                              | Result of useLocation() hook          |
+| `location.pathname` | `string`                                                                                                                     | -                                     |
+| `location.search`   | `string`                                                                                                                     | -                                     |
+| `_params`           | `Record`\<`string`, `string` \| `undefined`\>                                                                                | Result of useParams() hook            |
+| `actor`             | [`AbstractActor`](../interfaces/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | XMachines actor instance              |
+| `routeMap`          | [`RouteMap`](RouteMap.md)                                                                                                    | Bidirectional state ID ↔ path mapping |
+
+#### Returns
+
+`SolidRouterBridge`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Properties
+
+| Property                                                              | Modifier    | Type                                                                                                                         | Description                                           | Inherited from                                                                                                                                                                | Defined in                                           |
+| --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../interfaces/AbstractActor.md)\<`AnyActorLogic`\> & [`Routable`](../../play-actor/interfaces/Routable.md) | Actor with currentRoute signal and send method        | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | packages/play-router/dist/router-bridge-base.d.ts:55 |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                    | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | packages/play-router/dist/router-bridge-base.d.ts:61 |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                    | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | packages/play-router/dist/router-bridge-base.d.ts:60 |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                    | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | packages/play-router/dist/router-bridge-base.d.ts:63 |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string`                                                                                                                     | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | packages/play-router/dist/router-bridge-base.d.ts:62 |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                     | Bidirectional route map for stateId ↔ path resolution | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | packages/play-router/dist/router-bridge-base.d.ts:56 |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                            | -                                                     | -                                                                                                                                                                             | packages/play-router/dist/router-bridge-base.d.ts:58 |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                            | -                                                     | -                                                                                                                                                                             | packages/play-router/dist/router-bridge-base.d.ts:57 |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`Watcher`](../../play-signals/namespaces/Signal/namespaces/subtle/classes/Watcher.md) \| `null`                          | -                                                     | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | packages/play-router/dist/router-bridge-base.d.ts:64 |
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:81
+
+Connect the router bridge to the Actor.
+
+Sets up the TC39 Signal watcher for actor → router direction and
+starts watching router changes (framework-specific).
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:87
+
+Disconnect the router bridge from the Actor.
+
+Stops signal watching and unregisters framework-specific router listener.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+
+---
+
+### dispose()
+
+```ts
+dispose(): void;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L123)
+
+Dispose the bridge (alias for disconnect).
+
+#### Returns
+
+`void`
+
+#### Example
+
+```tsx
+onCleanup(() => bridge.dispose());
+```
+
+---
+
+### extractParams()
+
+```ts
+protected extractParams(pathname, stateId): Record<string, string>;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:134
+
+Extract path parameters from URL using the URLPattern API.
+
+Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
+library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
+polyfill), this method returns `{}` silently (graceful degradation — routing still
+works, params will be empty).
+
+#### Parameters
+
+| Parameter  | Type     | Description                                       |
+| ---------- | -------- | ------------------------------------------------- |
+| `pathname` | `string` | The actual URL path (e.g., '/profile/john')       |
+| `stateId`  | `string` | The matched state ID for looking up route pattern |
+
+#### Returns
+
+`Record`\<`string`, `string`\>
+
+Extracted path parameters, or empty object if URLPattern is unavailable or no match
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`extractParams`](../../play-router/classes/RouterBridgeBase.md#extractparams)
+
+---
+
+### extractQuery()
+
+```ts
+protected extractQuery(search): Record<string, string>;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:141
+
+Extract query parameters from URL search string.
+
+#### Parameters
+
+| Parameter | Type     | Description                                      |
+| --------- | -------- | ------------------------------------------------ |
+| `search`  | `string` | URL search string (e.g., '?tab=security&page=1') |
+
+#### Returns
+
+`Record`\<`string`, `string`\>
+
+Extracted query parameters or empty object
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`extractQuery`](../../play-router/classes/RouterBridgeBase.md#extractquery)
+
+---
+
+### getInitialRouterPath()
+
+```ts
+protected getInitialRouterPath(): string | null;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L82)
+
+Get the current router pathname for initial URL -> actor sync on connect.
+
+#### Returns
+
+`string` \| `null`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`getInitialRouterPath`](../../play-router/classes/RouterBridgeBase.md#getinitialrouterpath)
+
+---
+
+### navigateRouter()
+
+```ts
+protected navigateRouter(path): void;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L75)
+
+Navigate SolidJS Router to the given path.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`navigateRouter`](../../play-router/classes/RouterBridgeBase.md#navigaterouter)
+
+---
+
+### syncActorFromRouter()
+
+```ts
+protected syncActorFromRouter(pathname, search?): void;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:101
+
+Sync actor state when router location changes.
+
+Sends play.route event to actor with resolved stateId, params, and query.
+Prevents circular updates via isProcessingNavigation flag.
+
+#### Parameters
+
+| Parameter  | Type     |
+| ---------- | -------- |
+| `pathname` | `string` |
+| `search?`  | `string` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`syncActorFromRouter`](../../play-router/classes/RouterBridgeBase.md#syncactorfromrouter)
+
+---
+
+### syncRouterFromActor()
+
+```ts
+protected syncRouterFromActor(route): void;
+```
+
+Defined in: packages/play-router/dist/router-bridge-base.d.ts:94
+
+Sync router location when actor route signal changes.
+
+Calls navigateRouter() for framework-specific navigation.
+Prevents circular updates via isProcessingNavigation flag.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `route`   | `unknown` |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`syncRouterFromActor`](../../play-router/classes/RouterBridgeBase.md#syncrouterfromactor)
+
+---
+
+### unwatchRouterChanges()
+
+```ts
+protected unwatchRouterChanges(): void;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L111)
+
+Stop watching SolidJS Router changes.
+
+Solid auto-cleans createEffect subscriptions when component unmounts.
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`unwatchRouterChanges`](../../play-router/classes/RouterBridgeBase.md#unwatchrouterchanges)
+
+---
+
+### watchRouterChanges()
+
+```ts
+protected watchRouterChanges(): void;
+```
+
+Defined in: [packages/play-solid-router/src/solid-router-bridge.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/solid-router-bridge.ts#L92)
+
+Subscribe to SolidJS Router location changes using createEffect.
+
+MUST be called inside a Solid reactive owner (component/createRoot).
+Solid auto-cleans createEffect subscriptions on component unmount.
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`watchRouterChanges`](../../play-router/classes/RouterBridgeBase.md#watchrouterchanges)

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

@@ -0,0 +1,19 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / PlayRouterProvider
+
+# Function: PlayRouterProvider()
+
+```ts
+function PlayRouterProvider(props): any;
+```
+
+Defined in: [packages/play-solid-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/play-router-provider.tsx#L21)
+
+## Parameters
+
+| Parameter | Type                                                                  |
+| --------- | --------------------------------------------------------------------- |
+| `props`   | [`PlayRouterProviderProps`](../interfaces/PlayRouterProviderProps.md) |
+
+## Returns
+
+`any`

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

@@ -0,0 +1,32 @@
+[Documentation](../../../README.md) / [@xmachines/play-solid-router](../README.md) / createRouteMap
+
+# Function: createRouteMap()
+
+```ts
+function createRouteMap(machine): RouteMap;
+```
+
+Defined in: [packages/play-solid-router/src/create-route-map.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/00a28432ed57807112288436d1ae4387d9f06919/packages/play-solid-router/src/create-route-map.ts#L27)
+
+Create a RouteMap from an XState machine
+
+## Parameters
+
+| Parameter | Type              | Description                                    |
+| --------- | ----------------- | ---------------------------------------------- |
+| `machine` | `AnyStateMachine` | XState machine with route: {} config on states |
+
+## Returns
+
+[`RouteMap`](../classes/RouteMap.md)
+
+RouteMap for bidirectional state ID ↔ path resolution
+
+## Example
+
+```typescript
+import { createRouteMap } from "@xmachines/play-solid-router";
+import { authMachine } from "./machine.js";
+
+const routeMap = createRouteMap(authMachine);
+```