@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/api/@xmachines/play-tanstack-router/classes/TanStackRouterBridgeBase.md

@@ -0,0 +1,131 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterBridgeBase
+
+# Class: TanStackRouterBridgeBase
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L102)
+
+Shared TanStack Router adapter implementing RouterBridge protocol via RouterBridgeBase
+
+## Remarks
+
+Extends RouterBridgeBase to handle all common lifecycle and sync logic; adds
+the TanStack-specific navigation and subscription methods shared by the React
+and Solid adapters.
+
+Subscribes to router.history (not router.subscribe("onBeforeLoad")) so that
+back/forward browser navigation (popstate events) are also captured. The
+router.subscribe("onBeforeLoad") approach only works when TanStack's
+Transitioner component is mounted (i.e. inside a full <RouterProvider>).
+Since this bridge is used without <RouterProvider>, we must subscribe to
+the underlying history object directly — which is exactly what Transitioner
+does internally: `router.history.subscribe(router.load)`.
+
+Architectural Invariants:
+
+- INV-02 (Passive Infrastructure): Router reflects actor state, never decides
+- Actor validates all navigation via guards before URL changes
+
+The class is concrete — it can be instantiated directly. The framework
+packages re-export or subclass it purely to bind the public adapter name
+(and, for Solid, to add the `dispose()` alias).
+
+## Example
+
+```typescript
+const bridge = new TanStackRouterBridgeBase(router, actor, routeMap);
+bridge.connect();
+return () => bridge.disconnect();
+```
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Extended by
+
+- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new TanStackRouterBridgeBase(
+   router,
+   actor,
+   routeMap): TanStackRouterBridgeBase;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L112)
+
+Create a TanStack Router bridge
+
+#### Parameters
+
+| Parameter  | Type                                                                 | Description                                       |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | TanStack Router instance (from `createRouter`)    |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance                          |
+| `routeMap` | [`TanStackRouteMapLike`](../type-aliases/TanStackRouteMapLike.md)    | Bidirectional mapping between state IDs and paths |
+
+#### Returns
+
+`TanStackRouterBridgeBase`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:120
+
+Connect the router bridge to the Actor.
+
+Sets up the TC39 Signal watcher for actor → router direction and
+starts watching router changes (framework-specific).
+
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: play-router/dist/router-bridge-base.d.ts:126
+
+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)

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

@@ -0,0 +1,57 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouteMapLike
+
+# Type Alias: TanStackRouteMapLike
+
+```ts
+type TanStackRouteMapLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L66)
+
+Narrow route-map surface required by `TanStackRouterBridgeBase`.
+`RouteMap` from `@xmachines/play-router` satisfies it (null returns are
+adapted to undefined internally).
+
+`getPathByStateId` may receive the stateId in either `"#stateId"` or bare
+`"stateId"` form — the bridge tries both forms automatically, so custom
+implementations keyed on a single form still resolve.
+
+## Methods
+
+### getPathByStateId()
+
+```ts
+getPathByStateId(id): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L68)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `id`      | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`
+
+---
+
+### getStateIdByPath()
+
+```ts
+getStateIdByPath(path): string | null | undefined;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L67)
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+#### Returns
+
+`string` \| `null` \| `undefined`

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

@@ -0,0 +1,100 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-router](../README.md) / TanStackRouterLike
+
+# Type Alias: TanStackRouterLike
+
+```ts
+type TanStackRouterLike = object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L36)
+
+Structural (type-only) interface for the TanStack Router surface used by
+`TanStackRouterBridgeBase`. Both `@tanstack/react-router` and
+`@tanstack/solid-router` instances satisfy it.
+
+## Properties
+
+### history
+
+```ts
+history: object;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L44)
+
+#### location
+
+```ts
+location: object;
+```
+
+Current location — populated from `window.location` when `createRouter()` runs,
+before `router.load()`. Always available in the browser.
+`router.state.location` is only populated after `router.load()` and may be stale.
+
+##### location.pathname
+
+```ts
+pathname: string;
+```
+
+##### location.search?
+
+```ts
+optional search?: string;
+```
+
+#### subscribe()
+
+```ts
+subscribe(handler): () => void;
+```
+
+##### Parameters
+
+| Parameter | Type                |
+| --------- | ------------------- |
+| `handler` | (`event`) => `void` |
+
+##### Returns
+
+() => `void`
+
+## Methods
+
+### load()?
+
+```ts
+optional load(): void | Promise<void>;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L43)
+
+Re-runs TanStack route matching and loaders for the current location.
+Optional: the bridge calls it (fire-and-forget) after every navigation so
+matching/loaders stay in sync even without a mounted `<RouterProvider>`.
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+---
+
+### navigate()
+
+```ts
+navigate(args): void;
+```
+
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L37)
+
+#### Parameters
+
+| Parameter | Type                  |
+| --------- | --------------------- |
+| `args`    | \{ `to`: `string`; \} |
+| `args.to` | `string`              |
+
+#### Returns
+
+`void`