@xmachines/play-solid-router 2.0.0-alpha.1 → 2.1.0

package/dist/solid-router-bridge.d.ts

@@ -1,14 +1,16 @@
 /**
- * SolidJS Router bridge implementing RouterBridge protocol via RouterBridgeBase
+ * The SolidJS Router bridge. It implements the RouterBridge protocol through RouterBridgeBase
  *
- * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
- * Uses Solid's native reactive primitives (createEffect) for router→actor direction.
+ * The class extends RouterBridgeBase, and the base class does all the common
+ * lifecycle work and synchronization work. This class uses the native reactive
+ * primitives of Solid (createEffect) for the router-to-actor direction.
  *
- * **IMPORTANT:** `connect()` MUST be called inside a Solid reactive owner (component
- * or createRoot). The `createEffect()` in `watchRouterChanges()` runs inside
- * `createRoot()`, which deliberately isolates it from any parent owner — automatic
- * cleanup on component unmount does NOT happen. You MUST call `disconnect()` (or
- * `dispose()`) explicitly, typically in `onCleanup()`.
+ * **IMPORTANT:** call `connect()` inside a Solid reactive owner: a component, or
+ * createRoot. The `createEffect()` call in `watchRouterChanges()` runs inside
+ * `createRoot()`, which keeps the effect separate from every parent owner on
+ * purpose. Therefore the effect does NOT clean up by itself when the component
+ * unmounts. You MUST call `disconnect()` or `dispose()` yourself, usually in
+ * `onCleanup()`.
  *
  * @example
  * ```tsx
@@ -24,7 +26,7 @@
  *   const routeMap = new RouteMap([...]);
  *   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
  *
- *   // connect() MUST be called inside a Solid reactive owner
+ *   // Call connect() inside a Solid reactive owner
  *   bridge.connect();
  *   onCleanup(() => bridge.disconnect());
  *
@@ -38,97 +40,110 @@ import type { LocationLike } from "@xmachines/play-router";
 import type { RoutableActor } from "@xmachines/play-router";
 import type { RouteMap } from "@xmachines/play-router";
 /**
- * SolidJS Router integration bridge extending RouterBridgeBase
+ * The SolidJS Router integration bridge. It extends 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.
+ * The class implements the RouterBridge protocol for SolidJS Router with the
+ * reactive primitives of Solid. The actor-to-router direction uses the TC39 Signal
+ * watcher of the base class. The router-to-actor direction uses the Solid
+ * createEffect function for a native reactivity.
  *
- * Path parameters are extracted from Solid's `useParams()` reactive proxy rather than
- * re-parsing the URL with URLPattern. This means parameterized routes work without the
- * URLPattern polyfill — Solid's router has already extracted the values.
+ * The bridge reads each path parameter from the reactive `useParams()` proxy of
+ * Solid. It does not parse the URL again with URLPattern. Therefore a
+ * parameterized route works without the URLPattern polyfill, because the router of
+ * Solid holds the values already.
  */
 export declare class SolidRouterBridge extends RouterBridgeBase {
     private readonly solidNavigate;
     private readonly location;
     private disposeRouterWatcher;
     /**
-     * Live reactive params object from Solid's `useParams()`.
-     * Read inside the createEffect callback so it always reflects the current route.
+     * The live reactive params object from the `useParams()` function of Solid.
+     * The bridge reads it inside the createEffect callback, so the value always shows
+     * the current route.
      */
     private readonly solidParams;
     /**
-     * Create a SolidJS Router bridge
+     * Creates a SolidJS Router bridge
      *
-     * **CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
+     * **CRITICAL:** call `connect()` inside a Solid component, where the hooks are available.
      *
-     * @param solidNavigate - Result of useNavigate() hook
-     * @param location - Result of useLocation() hook
-     * @param params - Result of useParams() hook — used directly for path parameter extraction,
-     *   avoiding the URLPattern polyfill requirement for parameterized routes
-     * @param actor - XMachines actor instance
-     * @param routeMap - Bidirectional state ID ↔ path mapping
+     * @param solidNavigate - The result of the useNavigate() hook
+     * @param location - The result of the useLocation() hook
+     * @param params - The result of the useParams() hook. The bridge reads each path
+     *   parameter directly from it. A parameterized route therefore does not need the
+     *   URLPattern polyfill
+     * @param actor - The XMachines actor instance
+     * @param routeMap - The bidirectional map between the state IDs and the paths
      */
     constructor(solidNavigate: Navigator, location: LocationLike, params: Params, actor: RoutableActor, routeMap: RouteMap);
     /**
-     * Extract path parameters using Solid's pre-parsed `useParams()` values.
+     * Reads each path parameter from the values that `useParams()` of Solid parsed before.
      *
-     * Solid's router has already extracted all named parameters for the matched route
-     * segment. Reading `this.solidParams` inside the createEffect callback that drives
-     * `syncActorFromRouter` is safe — the reactive proxy always reflects the current
-     * route at the time the effect runs.
+     * The router of Solid holds every named parameter of the matched route segment
+     * already. A read of `this.solidParams` inside the createEffect callback that
+     * drives `syncActorFromRouter` is safe, because the reactive proxy always shows the
+     * route of the moment when the effect runs.
      *
-     * Falls back to URLPattern-based extraction (base class) only when Solid provided
-     * no params for this route (i.e. the route has no `:param` segments).
+     * The method returns to the URLPattern method of the base class only when Solid
+     * gives no param for this route, which means that the route has no `:param`
+     * segment.
      *
-     * @param pathname - The actual URL path (unused — params already extracted by Solid)
-     * @param stateId - The matched state ID (unused — params already extracted by Solid)
-     * @returns Normalized path parameters with undefined/empty values filtered out
+     * @param pathname - The real URL path. The method does not use it, because Solid
+     *   parsed the params before
+     * @param stateId - The matched state ID. The method does not use it, because Solid
+     *   parsed the params before
+     * @returns The normalized path parameters, without an undefined value and without
+     *   an empty value
      */
     protected extractParams(pathname: string, stateId: string): Record<string, string>;
     /**
-     * Navigate SolidJS Router to the given path.
+     * Navigates SolidJS Router to the given path.
      */
     protected navigateRouter(path: string): void;
     /**
-     * Get the current router pathname for initial URL -> actor sync on connect.
+     * Returns the current pathname of the router, for the first URL-to-actor synchronization in connect().
      */
     protected getInitialRouterPath(): string | null;
     /**
-     * Return the initial URL search string for query-param forwarding on `connect()`.
+     * Returns the initial URL search string, so that `connect()` can forward the query params.
      *
-     * Reads `this.location.search` from Solid's `useLocation()` reactive object —
-     * the same source used by `getInitialRouterPath()`. An empty string (no query
-     * params) returns `undefined` so `syncActorFromRouter` produces `query: {}`.
+     * The method reads `this.location.search` from the reactive `useLocation()` object
+     * of Solid, the same source as `getInitialRouterPath()`. For an empty string, which
+     * means no query param, it returns `undefined`. `syncActorFromRouter` then makes
+     * `query: {}`.
      */
     protected getInitialRouterSearch(): string | undefined;
     /**
-     * Subscribe to SolidJS Router location changes using createEffect.
+     * Subscribes to each location change of SolidJS Router with createEffect.
      *
-     * MUST be called inside a Solid reactive owner (component or createRoot).
+     * Call this method inside a Solid reactive owner: a component, or createRoot.
      *
-     * The effect runs inside `createRoot()` to give it a stable owner independent
-     * of the calling component's lifecycle — this prevents the effect from being
-     * disposed if the component re-renders while the bridge should stay active.
-     * The trade-off is that component unmount does NOT automatically clean up the
-     * effect; `disconnect()` (or `dispose()`) MUST be called explicitly to avoid a leak.
+     * The effect runs inside `createRoot()`. The effect then has a stable owner, and
+     * that owner is separate from the lifecycle of the component that calls the method.
+     * Solid therefore does not dispose of the effect when the component renders again
+     * while the bridge must stay active. The cost is that the unmount of the component
+     * does NOT clean up the effect. Call `disconnect()` or `dispose()` yourself, or the
+     * effect stays in memory.
      */
     protected watchRouterChanges(): void;
     /**
-     * Stop watching SolidJS Router changes.
+     * Stops the watch of the SolidJS Router changes.
      *
-     * Calls the `dispose` function returned by `createRoot()` in `watchRouterChanges()`,
-     * tearing down the reactive effect and freeing the isolated owner. This is the only
-     * cleanup path — component unmount does NOT trigger this automatically.
+     * The method calls the `dispose` function that `createRoot()` returned in
+     * `watchRouterChanges()`. This removes the reactive effect and frees the separate
+     * owner. This is the only path that cleans up. The unmount of the component does
+     * NOT start it.
      */
     protected unwatchRouterChanges(): void;
     /**
-     * Dispose the bridge (alias for disconnect).
+     * Disposes of the bridge. This method is the alias of disconnect.
      *
      * @example
      * ```tsx
      * onCleanup(() => bridge.dispose());
      * ```
+     *
+     * @deprecated Use {@link RouterBridgeBase.disconnect | disconnect}. Will be removed in the next major.
      */
     dispose(): void;
 }

package/dist/solid-router-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solid-router-bridge.d.ts","sourceRoot":"","sources":["../src/solid-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;IAsBrD,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAtB1B,OAAO,CAAC,oBAAoB,CAA6B;IAEzD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;;;;;;;OAWG;gBAEe,aAAa,EAAE,SAAS,EACxB,QAAQ,EAAE,YAAY,EACvC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,QAAQ;IASnB;;;;;;;;;;;;;;OAcG;cACgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAY3F;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;cACgB,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAIxD;;;;;;OAMG;cACgB,sBAAsB,IAAI,MAAM,GAAG,SAAS;IAI/D;;;;;;;;;;OAUG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAepC;;;;;;OAMG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAKtC;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAGf"}
+{"version":3,"file":"solid-router-bridge.d.ts","sourceRoot":"","sources":["../src/solid-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;IAwBrD,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAxB1B,OAAO,CAAC,oBAAoB,CAA6B;IAEzD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC;;;;;;;;;;;;OAYG;gBAEe,aAAa,EAAE,SAAS,EACxB,QAAQ,EAAE,YAAY,EACvC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,QAAQ;IASnB;;;;;;;;;;;;;;;;;;OAkBG;cACgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAY3F;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;cACgB,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAIxD;;;;;;;OAOG;cACgB,sBAAsB,IAAI,MAAM,GAAG,SAAS;IAI/D;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAepC;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAKtC;;;;;;;;;OASG;IACH,OAAO,IAAI,IAAI;CAGf"}

package/dist/solid-router-bridge.js

@@ -1,166 +1,182 @@
-/**
- * SolidJS Router bridge implementing RouterBridge protocol via RouterBridgeBase
- *
- * Extends RouterBridgeBase to handle all common lifecycle and sync logic.
- * Uses Solid's native reactive primitives (createEffect) for router→actor direction.
- *
- * **IMPORTANT:** `connect()` MUST be called inside a Solid reactive owner (component
- * or createRoot). The `createEffect()` in `watchRouterChanges()` runs inside
- * `createRoot()`, which deliberately isolates it from any parent owner — automatic
- * cleanup on component unmount does NOT happen. You MUST call `disconnect()` (or
- * `dispose()`) explicitly, typically in `onCleanup()`.
- *
- * @example
- * ```tsx
- * import { useNavigate, useLocation, useParams } from '@solidjs/router';
- * import { onCleanup } from 'solid-js';
- * import { SolidRouterBridge, RouteMap } from '@xmachines/play-solid-router';
- *
- * function App() {
- *   const navigate = useNavigate();
- *   const location = useLocation();
- *   const params = useParams();
- *
- *   const routeMap = new RouteMap([...]);
- *   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
- *
- *   // connect() MUST be called inside a Solid reactive owner
- *   bridge.connect();
- *   onCleanup(() => bridge.disconnect());
- *
- *   return <div>...</div>;
- * }
- * ```
- */
 import { createEffect, createRoot, on } from "solid-js";
 import { RouterBridgeBase } from "@xmachines/play-router";
+//#region packages/play-solid-router/src/solid-router-bridge.ts
+/**
+* The SolidJS Router bridge. It implements the RouterBridge protocol through RouterBridgeBase
+*
+* The class extends RouterBridgeBase, and the base class does all the common
+* lifecycle work and synchronization work. This class uses the native reactive
+* primitives of Solid (createEffect) for the router-to-actor direction.
+*
+* **IMPORTANT:** call `connect()` inside a Solid reactive owner: a component, or
+* createRoot. The `createEffect()` call in `watchRouterChanges()` runs inside
+* `createRoot()`, which keeps the effect separate from every parent owner on
+* purpose. Therefore the effect does NOT clean up by itself when the component
+* unmounts. You MUST call `disconnect()` or `dispose()` yourself, usually in
+* `onCleanup()`.
+*
+* @example
+* ```tsx
+* import { useNavigate, useLocation, useParams } from '@solidjs/router';
+* import { onCleanup } from 'solid-js';
+* import { SolidRouterBridge, RouteMap } from '@xmachines/play-solid-router';
+*
+* function App() {
+*   const navigate = useNavigate();
+*   const location = useLocation();
+*   const params = useParams();
+*
+*   const routeMap = new RouteMap([...]);
+*   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);
+*
+*   // Call connect() inside a Solid reactive owner
+*   bridge.connect();
+*   onCleanup(() => bridge.disconnect());
+*
+*   return <div>...</div>;
+* }
+* ```
+*/
 /**
- * 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.
- *
- * Path parameters are extracted from Solid's `useParams()` reactive proxy rather than
- * re-parsing the URL with URLPattern. This means parameterized routes work without the
- * URLPattern polyfill — Solid's router has already extracted the values.
- */
-export class SolidRouterBridge extends RouterBridgeBase {
-    solidNavigate;
-    location;
-    disposeRouterWatcher = null;
-    /**
-     * Live reactive params object from Solid's `useParams()`.
-     * Read inside the createEffect callback so it always reflects the current route.
-     */
-    solidParams;
-    /**
-     * Create a SolidJS Router bridge
-     *
-     * **CRITICAL:** `connect()` must be called inside a Solid component where hooks are available.
-     *
-     * @param solidNavigate - Result of useNavigate() hook
-     * @param location - Result of useLocation() hook
-     * @param params - Result of useParams() hook — used directly for path parameter extraction,
-     *   avoiding the URLPattern polyfill requirement for parameterized routes
-     * @param actor - XMachines actor instance
-     * @param routeMap - Bidirectional state ID ↔ path mapping
-     */
-    constructor(solidNavigate, location, params, actor, routeMap) {
-        super(actor, {
-            getStateIdByPath: (path) => routeMap.getStateIdByPath(path),
-            getPathByStateId: (id) => routeMap.getPathByStateId(id),
-        });
-        this.solidNavigate = solidNavigate;
-        this.location = location;
-        this.solidParams = params;
-    }
-    /**
-     * Extract path parameters using Solid's pre-parsed `useParams()` values.
-     *
-     * Solid's router has already extracted all named parameters for the matched route
-     * segment. Reading `this.solidParams` inside the createEffect callback that drives
-     * `syncActorFromRouter` is safe — the reactive proxy always reflects the current
-     * route at the time the effect runs.
-     *
-     * Falls back to URLPattern-based extraction (base class) only when Solid provided
-     * no params for this route (i.e. the route has no `:param` segments).
-     *
-     * @param pathname - The actual URL path (unused — params already extracted by Solid)
-     * @param stateId - The matched state ID (unused — params already extracted by Solid)
-     * @returns Normalized path parameters with undefined/empty values filtered out
-     */
-    extractParams(pathname, stateId) {
-        const entries = Object.entries(this.solidParams).filter((entry) => entry[1] !== undefined && entry[1] !== null && entry[1] !== "");
-        if (entries.length > 0) {
-            return Object.fromEntries(entries);
-        }
-        // No params from Solid — fall back to URLPattern for routes with no segments
-        return super.extractParams(pathname, stateId);
-    }
-    /**
-     * Navigate SolidJS Router to the given path.
-     */
-    navigateRouter(path) {
-        this.solidNavigate(path);
-    }
-    /**
-     * Get the current router pathname for initial URL -> actor sync on connect.
-     */
-    getInitialRouterPath() {
-        return this.location.pathname ?? null;
-    }
-    /**
-     * Return the initial URL search string for query-param forwarding on `connect()`.
-     *
-     * Reads `this.location.search` from Solid's `useLocation()` reactive object —
-     * the same source used by `getInitialRouterPath()`. An empty string (no query
-     * params) returns `undefined` so `syncActorFromRouter` produces `query: {}`.
-     */
-    getInitialRouterSearch() {
-        return this.location.search || undefined;
-    }
-    /**
-     * Subscribe to SolidJS Router location changes using createEffect.
-     *
-     * MUST be called inside a Solid reactive owner (component or createRoot).
-     *
-     * The effect runs inside `createRoot()` to give it a stable owner independent
-     * of the calling component's lifecycle — this prevents the effect from being
-     * disposed if the component re-renders while the bridge should stay active.
-     * The trade-off is that component unmount does NOT automatically clean up the
-     * effect; `disconnect()` (or `dispose()`) MUST be called explicitly to avoid a leak.
-     */
-    watchRouterChanges() {
-        this.disposeRouterWatcher = createRoot((dispose) => {
-            createEffect(on(() => this.location.pathname, (pathname) => {
-                const search = this.location.search ?? "";
-                this.syncActorFromRouter(pathname, search);
-            }));
-            return dispose;
-        });
-    }
-    /**
-     * Stop watching SolidJS Router changes.
-     *
-     * Calls the `dispose` function returned by `createRoot()` in `watchRouterChanges()`,
-     * tearing down the reactive effect and freeing the isolated owner. This is the only
-     * cleanup path — component unmount does NOT trigger this automatically.
-     */
-    unwatchRouterChanges() {
-        this.disposeRouterWatcher?.();
-        this.disposeRouterWatcher = null;
-    }
-    /**
-     * Dispose the bridge (alias for disconnect).
-     *
-     * @example
-     * ```tsx
-     * onCleanup(() => bridge.dispose());
-     * ```
-     */
-    dispose() {
-        this.disconnect();
-    }
-}
+* The SolidJS Router integration bridge. It extends RouterBridgeBase
+*
+* The class implements the RouterBridge protocol for SolidJS Router with the
+* reactive primitives of Solid. The actor-to-router direction uses the TC39 Signal
+* watcher of the base class. The router-to-actor direction uses the Solid
+* createEffect function for a native reactivity.
+*
+* The bridge reads each path parameter from the reactive `useParams()` proxy of
+* Solid. It does not parse the URL again with URLPattern. Therefore a
+* parameterized route works without the URLPattern polyfill, because the router of
+* Solid holds the values already.
+*/
+var SolidRouterBridge = class extends RouterBridgeBase {
+	solidNavigate;
+	location;
+	disposeRouterWatcher = null;
+	/**
+	* The live reactive params object from the `useParams()` function of Solid.
+	* The bridge reads it inside the createEffect callback, so the value always shows
+	* the current route.
+	*/
+	solidParams;
+	/**
+	* Creates a SolidJS Router bridge
+	*
+	* **CRITICAL:** call `connect()` inside a Solid component, where the hooks are available.
+	*
+	* @param solidNavigate - The result of the useNavigate() hook
+	* @param location - The result of the useLocation() hook
+	* @param params - The result of the useParams() hook. The bridge reads each path
+	*   parameter directly from it. A parameterized route therefore does not need the
+	*   URLPattern polyfill
+	* @param actor - The XMachines actor instance
+	* @param routeMap - The bidirectional map between the state IDs and the paths
+	*/
+	constructor(solidNavigate, location, params, actor, routeMap) {
+		super(actor, {
+			getStateIdByPath: (path) => routeMap.getStateIdByPath(path),
+			getPathByStateId: (id) => routeMap.getPathByStateId(id)
+		});
+		this.solidNavigate = solidNavigate;
+		this.location = location;
+		this.solidParams = params;
+	}
+	/**
+	* Reads each path parameter from the values that `useParams()` of Solid parsed before.
+	*
+	* The router of Solid holds every named parameter of the matched route segment
+	* already. A read of `this.solidParams` inside the createEffect callback that
+	* drives `syncActorFromRouter` is safe, because the reactive proxy always shows the
+	* route of the moment when the effect runs.
+	*
+	* The method returns to the URLPattern method of the base class only when Solid
+	* gives no param for this route, which means that the route has no `:param`
+	* segment.
+	*
+	* @param pathname - The real URL path. The method does not use it, because Solid
+	*   parsed the params before
+	* @param stateId - The matched state ID. The method does not use it, because Solid
+	*   parsed the params before
+	* @returns The normalized path parameters, without an undefined value and without
+	*   an empty value
+	*/
+	extractParams(pathname, stateId) {
+		const entries = Object.entries(this.solidParams).filter((entry) => entry[1] !== void 0 && entry[1] !== null && entry[1] !== "");
+		if (entries.length > 0) return Object.fromEntries(entries);
+		return super.extractParams(pathname, stateId);
+	}
+	/**
+	* Navigates SolidJS Router to the given path.
+	*/
+	navigateRouter(path) {
+		this.solidNavigate(path);
+	}
+	/**
+	* Returns the current pathname of the router, for the first URL-to-actor synchronization in connect().
+	*/
+	getInitialRouterPath() {
+		return this.location.pathname ?? null;
+	}
+	/**
+	* Returns the initial URL search string, so that `connect()` can forward the query params.
+	*
+	* The method reads `this.location.search` from the reactive `useLocation()` object
+	* of Solid, the same source as `getInitialRouterPath()`. For an empty string, which
+	* means no query param, it returns `undefined`. `syncActorFromRouter` then makes
+	* `query: {}`.
+	*/
+	getInitialRouterSearch() {
+		return this.location.search || void 0;
+	}
+	/**
+	* Subscribes to each location change of SolidJS Router with createEffect.
+	*
+	* Call this method inside a Solid reactive owner: a component, or createRoot.
+	*
+	* The effect runs inside `createRoot()`. The effect then has a stable owner, and
+	* that owner is separate from the lifecycle of the component that calls the method.
+	* Solid therefore does not dispose of the effect when the component renders again
+	* while the bridge must stay active. The cost is that the unmount of the component
+	* does NOT clean up the effect. Call `disconnect()` or `dispose()` yourself, or the
+	* effect stays in memory.
+	*/
+	watchRouterChanges() {
+		this.disposeRouterWatcher = createRoot((dispose) => {
+			createEffect(on(() => this.location.pathname, (pathname) => {
+				const search = this.location.search ?? "";
+				this.syncActorFromRouter(pathname, search);
+			}));
+			return dispose;
+		});
+	}
+	/**
+	* Stops the watch of the SolidJS Router changes.
+	*
+	* The method calls the `dispose` function that `createRoot()` returned in
+	* `watchRouterChanges()`. This removes the reactive effect and frees the separate
+	* owner. This is the only path that cleans up. The unmount of the component does
+	* NOT start it.
+	*/
+	unwatchRouterChanges() {
+		this.disposeRouterWatcher?.();
+		this.disposeRouterWatcher = null;
+	}
+	/**
+	* Disposes of the bridge. This method is the alias of disconnect.
+	*
+	* @example
+	* ```tsx
+	* onCleanup(() => bridge.dispose());
+	* ```
+	*
+	* @deprecated Use {@link RouterBridgeBase.disconnect | disconnect}. Will be removed in the next major.
+	*/
+	dispose() {
+		this.disconnect();
+	}
+};
+//#endregion
+export { SolidRouterBridge };
+
 //# sourceMappingURL=solid-router-bridge.js.map

package/dist/solid-router-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"solid-router-bridge.js","sourceRoot":"","sources":["../src/solid-router-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK1D;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAkB,SAAQ,gBAAgB;IAsBpC;IACA;IAtBV,oBAAoB,GAAwB,IAAI,CAAC;IAEzD;;;OAGG;IACc,WAAW,CAAS;IAErC;;;;;;;;;;;OAWG;IACH,YACkB,aAAwB,EACxB,QAAsB,EACvC,MAAc,EACd,KAAoB,EACpB,QAAkB;QAElB,KAAK,CAAC,KAAK,EAAE;YACZ,gBAAgB,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC;YACnE,gBAAgB,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;SAC/D,CAAC,CAAC;QATc,kBAAa,GAAb,aAAa,CAAW;QACxB,aAAQ,GAAR,QAAQ,CAAc;QASvC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACgB,aAAa,CAAC,QAAgB,EAAE,OAAe;QACjE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CACtD,CAAC,KAAK,EAA6B,EAAE,CACpC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAC/D,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QACD,6EAA6E;QAC7E,OAAO,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACO,cAAc,CAAC,IAAY;QACpC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACgB,oBAAoB;QACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,IAAI,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACgB,sBAAsB;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,SAAS,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;OAUG;IACO,kBAAkB;QAC3B,IAAI,CAAC,oBAAoB,GAAG,UAAU,CAAC,CAAC,OAAO,EAAE,EAAE;YAClD,YAAY,CACX,EAAE,CACD,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAC5B,CAAC,QAAgB,EAAE,EAAE;gBACpB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;gBAC1C,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC,CACD,CACD,CAAC;YACF,OAAO,OAAO,CAAC;QAChB,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACO,oBAAoB;QAC7B,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAClC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,EAAE,CAAC;IACnB,CAAC;CACD"}
+{"version":3,"file":"solid-router-bridge.js","names":[],"sources":["../src/solid-router-bridge.ts"],"sourcesContent":["/**\n * The SolidJS Router bridge. It implements the RouterBridge protocol through RouterBridgeBase\n *\n * The class extends RouterBridgeBase, and the base class does all the common\n * lifecycle work and synchronization work. This class uses the native reactive\n * primitives of Solid (createEffect) for the router-to-actor direction.\n *\n * **IMPORTANT:** call `connect()` inside a Solid reactive owner: a component, or\n * createRoot. The `createEffect()` call in `watchRouterChanges()` runs inside\n * `createRoot()`, which keeps the effect separate from every parent owner on\n * purpose. Therefore the effect does NOT clean up by itself when the component\n * unmounts. You MUST call `disconnect()` or `dispose()` yourself, usually in\n * `onCleanup()`.\n *\n * @example\n * ```tsx\n * import { useNavigate, useLocation, useParams } from '@solidjs/router';\n * import { onCleanup } from 'solid-js';\n * import { SolidRouterBridge, RouteMap } from '@xmachines/play-solid-router';\n *\n * function App() {\n *   const navigate = useNavigate();\n *   const location = useLocation();\n *   const params = useParams();\n *\n *   const routeMap = new RouteMap([...]);\n *   const bridge = new SolidRouterBridge(navigate, location, params, actor, routeMap);\n *\n *   // Call connect() inside a Solid reactive owner\n *   bridge.connect();\n *   onCleanup(() => bridge.disconnect());\n *\n *   return <div>...</div>;\n * }\n * ```\n */\n\nimport { createEffect, createRoot, on } from \"solid-js\";\nimport type { Navigator, Params } from \"@solidjs/router\";\nimport { RouterBridgeBase } from \"@xmachines/play-router\";\nimport type { LocationLike } from \"@xmachines/play-router\";\nimport type { RoutableActor } from \"@xmachines/play-router\";\nimport type { RouteMap } from \"@xmachines/play-router\";\n\n/**\n * The SolidJS Router integration bridge. It extends RouterBridgeBase\n *\n * The class implements the RouterBridge protocol for SolidJS Router with the\n * reactive primitives of Solid. The actor-to-router direction uses the TC39 Signal\n * watcher of the base class. The router-to-actor direction uses the Solid\n * createEffect function for a native reactivity.\n *\n * The bridge reads each path parameter from the reactive `useParams()` proxy of\n * Solid. It does not parse the URL again with URLPattern. Therefore a\n * parameterized route works without the URLPattern polyfill, because the router of\n * Solid holds the values already.\n */\nexport class SolidRouterBridge extends RouterBridgeBase {\n\tprivate disposeRouterWatcher: (() => void) | null = null;\n\n\t/**\n\t * The live reactive params object from the `useParams()` function of Solid.\n\t * The bridge reads it inside the createEffect callback, so the value always shows\n\t * the current route.\n\t */\n\tprivate readonly solidParams: Params;\n\n\t/**\n\t * Creates a SolidJS Router bridge\n\t *\n\t * **CRITICAL:** call `connect()` inside a Solid component, where the hooks are available.\n\t *\n\t * @param solidNavigate - The result of the useNavigate() hook\n\t * @param location - The result of the useLocation() hook\n\t * @param params - The result of the useParams() hook. The bridge reads each path\n\t *   parameter directly from it. A parameterized route therefore does not need the\n\t *   URLPattern polyfill\n\t * @param actor - The XMachines actor instance\n\t * @param routeMap - The bidirectional map between the state IDs and the paths\n\t */\n\tconstructor(\n\t\tprivate readonly solidNavigate: Navigator,\n\t\tprivate readonly location: LocationLike,\n\t\tparams: Params,\n\t\tactor: RoutableActor,\n\t\trouteMap: RouteMap,\n\t) {\n\t\tsuper(actor, {\n\t\t\tgetStateIdByPath: (path: string) => routeMap.getStateIdByPath(path),\n\t\t\tgetPathByStateId: (id: string) => routeMap.getPathByStateId(id),\n\t\t});\n\t\tthis.solidParams = params;\n\t}\n\n\t/**\n\t * Reads each path parameter from the values that `useParams()` of Solid parsed before.\n\t *\n\t * The router of Solid holds every named parameter of the matched route segment\n\t * already. A read of `this.solidParams` inside the createEffect callback that\n\t * drives `syncActorFromRouter` is safe, because the reactive proxy always shows the\n\t * route of the moment when the effect runs.\n\t *\n\t * The method returns to the URLPattern method of the base class only when Solid\n\t * gives no param for this route, which means that the route has no `:param`\n\t * segment.\n\t *\n\t * @param pathname - The real URL path. The method does not use it, because Solid\n\t *   parsed the params before\n\t * @param stateId - The matched state ID. The method does not use it, because Solid\n\t *   parsed the params before\n\t * @returns The normalized path parameters, without an undefined value and without\n\t *   an empty value\n\t */\n\tprotected override extractParams(pathname: string, stateId: string): Record<string, string> {\n\t\tconst entries = Object.entries(this.solidParams).filter(\n\t\t\t(entry): entry is [string, string] =>\n\t\t\t\tentry[1] !== undefined && entry[1] !== null && entry[1] !== \"\",\n\t\t);\n\t\tif (entries.length > 0) {\n\t\t\treturn Object.fromEntries(entries);\n\t\t}\n\t\t// Solid gives no param: use URLPattern for a route with no segment\n\t\treturn super.extractParams(pathname, stateId);\n\t}\n\n\t/**\n\t * Navigates SolidJS Router to the given path.\n\t */\n\tprotected navigateRouter(path: string): void {\n\t\tthis.solidNavigate(path);\n\t}\n\n\t/**\n\t * Returns the current pathname of the router, for the first URL-to-actor synchronization in connect().\n\t */\n\tprotected override getInitialRouterPath(): string | null {\n\t\treturn this.location.pathname ?? null;\n\t}\n\n\t/**\n\t * Returns the initial URL search string, so that `connect()` can forward the query params.\n\t *\n\t * The method reads `this.location.search` from the reactive `useLocation()` object\n\t * of Solid, the same source as `getInitialRouterPath()`. For an empty string, which\n\t * means no query param, it returns `undefined`. `syncActorFromRouter` then makes\n\t * `query: {}`.\n\t */\n\tprotected override getInitialRouterSearch(): string | undefined {\n\t\treturn this.location.search || undefined;\n\t}\n\n\t/**\n\t * Subscribes to each location change of SolidJS Router with createEffect.\n\t *\n\t * Call this method inside a Solid reactive owner: a component, or createRoot.\n\t *\n\t * The effect runs inside `createRoot()`. The effect then has a stable owner, and\n\t * that owner is separate from the lifecycle of the component that calls the method.\n\t * Solid therefore does not dispose of the effect when the component renders again\n\t * while the bridge must stay active. The cost is that the unmount of the component\n\t * does NOT clean up the effect. Call `disconnect()` or `dispose()` yourself, or the\n\t * effect stays in memory.\n\t */\n\tprotected watchRouterChanges(): void {\n\t\tthis.disposeRouterWatcher = createRoot((dispose) => {\n\t\t\tcreateEffect(\n\t\t\t\ton(\n\t\t\t\t\t() => this.location.pathname,\n\t\t\t\t\t(pathname: string) => {\n\t\t\t\t\t\tconst search = this.location.search ?? \"\";\n\t\t\t\t\t\tthis.syncActorFromRouter(pathname, search);\n\t\t\t\t\t},\n\t\t\t\t),\n\t\t\t);\n\t\t\treturn dispose;\n\t\t});\n\t}\n\n\t/**\n\t * Stops the watch of the SolidJS Router changes.\n\t *\n\t * The method calls the `dispose` function that `createRoot()` returned in\n\t * `watchRouterChanges()`. This removes the reactive effect and frees the separate\n\t * owner. This is the only path that cleans up. The unmount of the component does\n\t * NOT start it.\n\t */\n\tprotected unwatchRouterChanges(): void {\n\t\tthis.disposeRouterWatcher?.();\n\t\tthis.disposeRouterWatcher = null;\n\t}\n\n\t/**\n\t * Disposes of the bridge. This method is the alias of disconnect.\n\t *\n\t * @example\n\t * ```tsx\n\t * onCleanup(() => bridge.dispose());\n\t * ```\n\t *\n\t * @deprecated Use {@link RouterBridgeBase.disconnect | disconnect}. Will be removed in the next major.\n\t */\n\tdispose(): void {\n\t\tthis.disconnect();\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,IAAa,oBAAb,cAAuC,iBAAiB;CAwBrC;CACA;CAxBlB,uBAAoD;;;;;;CAOpD;;;;;;;;;;;;;;CAeA,YACC,eACA,UACA,QACA,OACA,UACC;EACD,MAAM,OAAO;GACZ,mBAAmB,SAAiB,SAAS,iBAAiB,IAAI;GAClE,mBAAmB,OAAe,SAAS,iBAAiB,EAAE;EAC/D,CAAC;EATgB,KAAA,gBAAA;EACA,KAAA,WAAA;EASjB,KAAK,cAAc;CACpB;;;;;;;;;;;;;;;;;;;;CAqBA,cAAiC,UAAkB,SAAyC;EAC3F,MAAM,UAAU,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,QAC/C,UACA,MAAM,OAAO,KAAA,KAAa,MAAM,OAAO,QAAQ,MAAM,OAAO,EAC9D;EACA,IAAI,QAAQ,SAAS,GACpB,OAAO,OAAO,YAAY,OAAO;EAGlC,OAAO,MAAM,cAAc,UAAU,OAAO;CAC7C;;;;CAKA,eAAyB,MAAoB;EAC5C,KAAK,cAAc,IAAI;CACxB;;;;CAKA,uBAAyD;EACxD,OAAO,KAAK,SAAS,YAAY;CAClC;;;;;;;;;CAUA,yBAAgE;EAC/D,OAAO,KAAK,SAAS,UAAU,KAAA;CAChC;;;;;;;;;;;;;CAcA,qBAAqC;EACpC,KAAK,uBAAuB,YAAY,YAAY;GACnD,aACC,SACO,KAAK,SAAS,WACnB,aAAqB;IACrB,MAAM,SAAS,KAAK,SAAS,UAAU;IACvC,KAAK,oBAAoB,UAAU,MAAM;GAC1C,CACD,CACD;GACA,OAAO;EACR,CAAC;CACF;;;;;;;;;CAUA,uBAAuC;EACtC,KAAK,uBAAuB;EAC5B,KAAK,uBAAuB;CAC7B;;;;;;;;;;;CAYA,UAAgB;EACf,KAAK,WAAW;CACjB;AACD"}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type definitions for @xmachines/play-solid-router
+ * The type definitions of @xmachines/play-solid-router
  */
 export type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
 export type { AbstractActor } from "@xmachines/play-actor";