@molecule/app-routing-react-router 1.2.5 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
3
  Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
4
  Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
5
  To change this document, edit the module-level JSDoc in src/index.ts.
6
- Generated: 2026-11-09T16:18:22.180Z
6
+ Generated: 2026-11-13T19:22:37.386Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-routing-react-router
@@ -236,6 +236,74 @@ interface LazyPageOptions {
236
236
  }
237
237
  ```
238
238
 
239
+ #### `ReactRouterConfig`
240
+
241
+ React Router-specific configuration.
242
+
243
+ ```typescript
244
+ interface ReactRouterConfig {
245
+ /**
246
+ * React Router navigate function (from useNavigate).
247
+ */
248
+ navigate?: NavigateFunction
249
+
250
+ /**
251
+ * Current location (from useLocation).
252
+ */
253
+ location?: {
254
+ pathname: string
255
+ search: string
256
+ hash: string
257
+ state?: unknown
258
+ key?: string
259
+ }
260
+
261
+ /**
262
+ * Current params (from useParams).
263
+ */
264
+ params?: Record<string, string | undefined>
265
+
266
+ /**
267
+ * Initial route definitions.
268
+ */
269
+ routes?: RouteDefinition[]
270
+ }
271
+ ```
272
+
273
+ #### `ReactRouterHooks`
274
+
275
+ React Router hooks adapter.
276
+
277
+ ```typescript
278
+ interface ReactRouterHooks {
279
+ /**
280
+ * The navigate function from useNavigate.
281
+ */
282
+ navigate: NavigateFunction
283
+
284
+ /**
285
+ * Location from useLocation.
286
+ */
287
+ location: {
288
+ pathname: string
289
+ search: string
290
+ hash: string
291
+ state?: unknown
292
+ key?: string
293
+ }
294
+
295
+ /**
296
+ * Params from useParams.
297
+ */
298
+ params: Record<string, string | undefined>
299
+
300
+ /**
301
+ * Search params from useSearchParams.
302
+ */
303
+ searchParams: URLSearchParams
304
+ }
305
+ ```
306
+
239
307
  #### `ListRouteFilter`
240
308
 
241
309
  Where a list filter lives in the URL. Path values take precedence over query values.
@@ -321,7 +389,7 @@ interface ListRouteChange<Filter extends string = string, Selection extends stri
321
389
 
322
390
  #### `ListRouteResult`
323
391
 
324
- Reactive list state and navigation, derived directly from React Router's current location.
392
+ List state and navigation, derived directly from the current location.
325
393
 
326
394
  ```typescript
327
395
  interface ListRouteResult<Filter extends string = string, Selection extends string = string> {
@@ -359,74 +427,6 @@ interface ListRouteResult<Filter extends string = string, Selection extends stri
359
427
  }
360
428
  ```
361
429
 
362
- #### `ReactRouterConfig`
363
-
364
- React Router-specific configuration.
365
-
366
- ```typescript
367
- interface ReactRouterConfig {
368
- /**
369
- * React Router navigate function (from useNavigate).
370
- */
371
- navigate?: NavigateFunction
372
-
373
- /**
374
- * Current location (from useLocation).
375
- */
376
- location?: {
377
- pathname: string
378
- search: string
379
- hash: string
380
- state?: unknown
381
- key?: string
382
- }
383
-
384
- /**
385
- * Current params (from useParams).
386
- */
387
- params?: Record<string, string | undefined>
388
-
389
- /**
390
- * Initial route definitions.
391
- */
392
- routes?: RouteDefinition[]
393
- }
394
- ```
395
-
396
- #### `ReactRouterHooks`
397
-
398
- React Router hooks adapter.
399
-
400
- ```typescript
401
- interface ReactRouterHooks {
402
- /**
403
- * The navigate function from useNavigate.
404
- */
405
- navigate: NavigateFunction
406
-
407
- /**
408
- * Location from useLocation.
409
- */
410
- location: {
411
- pathname: string
412
- search: string
413
- hash: string
414
- state?: unknown
415
- key?: string
416
- }
417
-
418
- /**
419
- * Params from useParams.
420
- */
421
- params: Record<string, string | undefined>
422
-
423
- /**
424
- * Search params from useSearchParams.
425
- */
426
- searchParams: URLSearchParams
427
- }
428
- ```
429
-
430
430
  #### `RouteLocation`
431
431
 
432
432
  Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
@@ -685,27 +685,30 @@ Callback invoked on each route change with the new location and the
685
685
  navigation action that triggered it.
686
686
 
687
687
  ```typescript
688
- type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void
688
+ type RouteChangeListener = (location: RouteLocation, action: NavigationAction) => void
689
689
  ```
690
690
 
691
691
  ### Functions
692
692
 
693
693
  #### `MoleculeRouterProvider(props)`
694
694
 
695
- Provider component that creates a molecule Router from React Router hooks and
696
- bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
695
+ Provider component that creates ONE molecule Router over React Router for its whole
696
+ mounted life and bonds it as the active singleton via `@molecule/app-routing`'s
697
+ `setRouter`. Subscribers and guards registered on the router survive navigation:
698
+ `@molecule/app-routing`'s `getRouter()` keeps returning it, `onRouterReady` fires once,
699
+ and React Router's own links and the back button reach `router.subscribe()`.
697
700
 
698
- Bonding happens in an effect on mount (and again whenever the location/params
699
- change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
700
- React Router adapter — no manual `setRouter` wiring required. Mount it once inside
701
- any React Router router when non-React code needs the bond, named routes are
702
- configured, or `onRouterReady` is needed. The routing hooks work without this provider.
701
+ Bonding happens in an effect on mount, so `@molecule/app-routing`'s
702
+ `navigate()`/`getRouter()` drive THIS real React Router adapter — no manual `setRouter`
703
+ wiring required. Mount it once inside any React Router router when non-React code needs
704
+ the bond, named routes are configured, or `onRouterReady` is needed. The routing hooks
705
+ work without this provider.
703
706
 
704
707
  ```typescript
705
708
  function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
706
709
  ```
707
710
 
708
- - `props` — The provider props (see {@link MoleculeRouterProviderProps}): `children` (rendered inside the router context), `routes` (optional named-route definitions), and `onRouterReady` (optional callback invoked with the router after it is bonded, e.g. to register guards — bonding via `setRouter` happens regardless).
711
+ - `props` — The provider props (see {@link MoleculeRouterProviderProps}): `children` (rendered inside the router context), `routes` (optional named-route definitions; pass a stable array — later identities register onto the same router), and `onRouterReady` (optional callback invoked ONCE with the router after it is bonded, e.g. to register guards — bonding via `setRouter` happens regardless).
709
712
 
710
713
  **Returns:** The rendered provider wrapping children with the router context.
711
714
 
@@ -716,9 +719,11 @@ BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider from this
716
719
  package or React Router itself. No MoleculeRouterProvider is required.
717
720
 
718
721
  When MoleculeRouterProvider is mounted, returns its exact router with its named
719
- routes. Otherwise creates a local adapter from React Router's hooks without
720
- bonding it globally. Mount MoleculeRouterProvider for the non-React
721
- `@molecule/app-routing` navigate()/getRouter() bond or onRouterReady.
722
+ routes. Otherwise creates ONE router for the calling component's whole life — its
723
+ location, params and queries follow React Router through every navigation, and
724
+ `subscribe()` hears React Router's own links and the back button — without bonding
725
+ it globally. Mount MoleculeRouterProvider for the non-React `@molecule/app-routing`
726
+ navigate()/getRouter() bond or onRouterReady.
722
727
 
723
728
  ```typescript
724
729
  function useMoleculeRouter(): Router
@@ -811,7 +816,13 @@ function lazyPage<Page extends LazyLoadableComponent>(
811
816
 
812
817
  #### `createReactRouter(config)`
813
818
 
814
- Creates a React Router adapter that implements the molecule Router interface.
819
+ Creates a React Router adapter that implements the molecule Router interface over a
820
+ config snapshot: the `navigate` function, `location` and `params` of one render. The
821
+ snapshot never changes, so every read answers for that render — the hooks
822
+ (`MoleculeRouterProvider`, `useMoleculeRouter`) build the live router instead, one
823
+ that follows React Router for its whole life. Navigation runs React Router's
824
+ `navigate`, falling back to a full-page `window.location` navigation when no
825
+ `navigate` was given (the hook-less `provider`).
815
826
 
816
827
  ```typescript
817
828
  function createReactRouter(config?: ReactRouterConfig): Router
@@ -1011,7 +1022,7 @@ export function setupRoutingReactRouter(): void {
1011
1022
  Peer dependencies:
1012
1023
 
1013
1024
  - `@molecule/app-i18n` ^1.0.1
1014
- - `@molecule/app-routing` ^1.0.1
1025
+ - `@molecule/app-routing` ^1.1.0
1015
1026
  - `react` ^18.0.0 || ^19.0.0
1016
1027
  - `react-dom` ^18.0.0 || ^19.0.0
1017
1028
  - `react-router` ^7.0.0 || ^8.0.0
@@ -0,0 +1,80 @@
1
+ /**
2
+ * The two `RouterHistory` implementations this bond hands to `@molecule/app-routing`'s
3
+ * `createHistoryRouter`: the live history that reads React Router through the hooks of a
4
+ * mounted component (`MoleculeRouterProvider`, `useMoleculeRouter`), and the snapshot
5
+ * history `createReactRouter` builds from its config.
6
+ *
7
+ * @module
8
+ */
9
+ import type { NavigateFunction } from 'react-router';
10
+ import type { NavigationAction, RouterHistory } from '@molecule/app-routing';
11
+ import type { ReactRouterConfig } from './types.js';
12
+ /**
13
+ * The React Router values one render holds, as a {@link ReactRouterHistory} reads them.
14
+ * The component that owns the history replaces this on every render with its latest
15
+ * `useNavigate()`, `useLocation()` and `useParams()` values.
16
+ */
17
+ export interface ReactRouterSnapshot {
18
+ /**
19
+ * The `useNavigate()` function of the render.
20
+ */
21
+ navigate: NavigateFunction;
22
+ /**
23
+ * The `useLocation()` value of the render.
24
+ */
25
+ location: {
26
+ pathname: string;
27
+ search: string;
28
+ hash: string;
29
+ state?: unknown;
30
+ key?: string;
31
+ };
32
+ /**
33
+ * The `useParams()` value of the render; empty above any matched `<Route>`.
34
+ */
35
+ params: Record<string, string | undefined>;
36
+ }
37
+ /**
38
+ * Holds the latest {@link ReactRouterSnapshot}; a component's `useRef` satisfies it.
39
+ */
40
+ export interface ReactRouterSnapshotRef {
41
+ /**
42
+ * The latest render's snapshot, or nothing before the first render.
43
+ */
44
+ current: ReactRouterSnapshot | undefined;
45
+ }
46
+ /**
47
+ * A live {@link RouterHistory} plus the one call a component's commit effect makes:
48
+ * React Router has committed `action`, so every subscriber registered through `listen`
49
+ * hears it once.
50
+ */
51
+ export interface ReactRouterHistory extends RouterHistory {
52
+ /**
53
+ * Reports a committed navigation to every `listen` subscriber.
54
+ *
55
+ * @param action - The action React Router committed the entry with.
56
+ */
57
+ notify(action: NavigationAction): void;
58
+ }
59
+ /**
60
+ * Builds the live history a mounted component owns: it reads the latest
61
+ * {@link ReactRouterSnapshot} the component wrote, navigates through that render's
62
+ * `useNavigate()`, and its `listen` registry is notified by the component's effect after
63
+ * React Router commits a navigation (its own links, the back button, or a navigation
64
+ * this router started).
65
+ *
66
+ * @param snapshot - The component's ref, replaced on every render.
67
+ * @returns The history with its {@link ReactRouterHistory.notify} entry.
68
+ */
69
+ export declare const createReactRouterHistory: (snapshot: ReactRouterSnapshotRef) => ReactRouterHistory;
70
+ /**
71
+ * Builds the history `createReactRouter` runs on: it navigates through the configured
72
+ * React Router `navigate` (falling back to `window.location` for the hook-less
73
+ * `provider`), reads the configured location/params snapshot, and reports each
74
+ * navigation itself — a snapshot has no router that could report back.
75
+ *
76
+ * @param config - The `createReactRouter` config.
77
+ * @returns The history.
78
+ */
79
+ export declare const createReactRouterSnapshotHistory: (config: ReactRouterConfig) => RouterHistory;
80
+ //# sourceMappingURL=history.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAGpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,iBAAiB,EAA8B,MAAM,YAAY,CAAA;AAE/E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAA;IAE1B;;OAEG;IACH,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,GAAG,CAAC,EAAE,MAAM,CAAA;KACb,CAAA;IAED;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAA;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACvC;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,sBAAsB,KAAG,kBA4E3E,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,GAAI,QAAQ,iBAAiB,KAAG,aAyF5E,CAAA"}
@@ -0,0 +1,188 @@
1
+ /**
2
+ * The two `RouterHistory` implementations this bond hands to `@molecule/app-routing`'s
3
+ * `createHistoryRouter`: the live history that reads React Router through the hooks of a
4
+ * mounted component (`MoleculeRouterProvider`, `useMoleculeRouter`), and the snapshot
5
+ * history `createReactRouter` builds from its config.
6
+ *
7
+ * @module
8
+ */
9
+ import { I18nError } from '@molecule/app-i18n';
10
+ const newHistoryKey = () => Math.random().toString(36).slice(2);
11
+ /**
12
+ * Builds the live history a mounted component owns: it reads the latest
13
+ * {@link ReactRouterSnapshot} the component wrote, navigates through that render's
14
+ * `useNavigate()`, and its `listen` registry is notified by the component's effect after
15
+ * React Router commits a navigation (its own links, the back button, or a navigation
16
+ * this router started).
17
+ *
18
+ * @param snapshot - The component's ref, replaced on every render.
19
+ * @returns The history with its {@link ReactRouterHistory.notify} entry.
20
+ */
21
+ export const createReactRouterHistory = (snapshot) => {
22
+ const listeners = new Set();
23
+ const requireSnapshot = () => {
24
+ const current = snapshot.current;
25
+ if (!current) {
26
+ throw new I18nError('routing.error.reactRouterHistoryBeforeRender', undefined, 'The React Router history was used before its component rendered. Mount it inside a React Router router through MoleculeRouterProvider or useMoleculeRouter.');
27
+ }
28
+ return current;
29
+ };
30
+ const matchedParams = () => {
31
+ const matched = {};
32
+ for (const [name, value] of Object.entries(snapshot.current?.params ?? {})) {
33
+ if (value !== undefined)
34
+ matched[name] = value;
35
+ }
36
+ return Object.keys(matched).length > 0 ? matched : undefined;
37
+ };
38
+ // Above any matched `<Route>`, `useParams()` is empty, and it stays empty (or stays
39
+ // readable, inside one) for the component's whole life — a component never moves
40
+ // between positions in the route tree. So whether the history carries native params is
41
+ // decided once, at creation: with an empty `useParams()` it reports none, and
42
+ // `createHistoryRouter` then matches the registered route definitions instead.
43
+ const nativeParams = matchedParams();
44
+ const history = {
45
+ location: () => {
46
+ const current = snapshot.current;
47
+ if (!current)
48
+ return { pathname: '/', search: '', hash: '' };
49
+ return {
50
+ pathname: current.location.pathname,
51
+ search: current.location.search,
52
+ hash: current.location.hash,
53
+ // React Router models "no state" as `null`; the molecule location leaves it
54
+ // `undefined`, so a stateless entry and an absent state read the same.
55
+ state: current.location.state ?? undefined,
56
+ key: current.location.key,
57
+ };
58
+ },
59
+ push: (path, state) => requireSnapshot().navigate(path, { replace: false, state }),
60
+ replace: (path, state) => requireSnapshot().navigate(path, { replace: true, state }),
61
+ go: (delta) => requireSnapshot().navigate(delta),
62
+ listen: (listener) => {
63
+ listeners.add(listener);
64
+ return () => {
65
+ listeners.delete(listener);
66
+ };
67
+ },
68
+ notify: (action) => {
69
+ for (const listener of [...listeners])
70
+ listener(action);
71
+ },
72
+ destroy: () => {
73
+ listeners.clear();
74
+ },
75
+ };
76
+ if (nativeParams) {
77
+ history.params = () => {
78
+ const matched = matchedParams();
79
+ // Presence was decided at creation and cannot flip, so this answers with a match.
80
+ return matched ?? nativeParams;
81
+ };
82
+ }
83
+ return history;
84
+ };
85
+ /**
86
+ * Builds the history `createReactRouter` runs on: it navigates through the configured
87
+ * React Router `navigate` (falling back to `window.location` for the hook-less
88
+ * `provider`), reads the configured location/params snapshot, and reports each
89
+ * navigation itself — a snapshot has no router that could report back.
90
+ *
91
+ * @param config - The `createReactRouter` config.
92
+ * @returns The history.
93
+ */
94
+ export const createReactRouterSnapshotHistory = (config) => {
95
+ const { navigate: navigateFn, location: snapshotLocation, params } = config;
96
+ const listeners = new Set();
97
+ let key = newHistoryKey();
98
+ const location = () => {
99
+ if (snapshotLocation) {
100
+ return {
101
+ pathname: snapshotLocation.pathname,
102
+ search: snapshotLocation.search,
103
+ hash: snapshotLocation.hash,
104
+ // Same normalization as the live history: no state reads as `undefined`.
105
+ state: snapshotLocation.state ?? undefined,
106
+ key: snapshotLocation.key ?? key,
107
+ };
108
+ }
109
+ if (typeof window !== 'undefined') {
110
+ return {
111
+ pathname: window.location.pathname,
112
+ search: window.location.search,
113
+ hash: window.location.hash,
114
+ state: window.history.state ?? undefined,
115
+ key,
116
+ };
117
+ }
118
+ return { pathname: '/', search: '', hash: '', key };
119
+ };
120
+ const paramsOf = () => {
121
+ const normalized = {};
122
+ for (const [name, value] of Object.entries(params ?? {})) {
123
+ if (value !== undefined)
124
+ normalized[name] = value;
125
+ }
126
+ return normalized;
127
+ };
128
+ const report = (action) => {
129
+ key = newHistoryKey();
130
+ for (const listener of [...listeners])
131
+ listener(action);
132
+ };
133
+ const navigateSnapshot = (path, replace, state) => {
134
+ if (navigateFn) {
135
+ navigateFn(path, { replace, state });
136
+ }
137
+ else if (typeof window !== 'undefined') {
138
+ // The hook-less fallback the package has always had: a full-page navigation.
139
+ if (replace)
140
+ window.location.replace(path);
141
+ else
142
+ window.location.href = path;
143
+ }
144
+ };
145
+ const history = {
146
+ location,
147
+ push: (path, state) => {
148
+ navigateSnapshot(path, false, state);
149
+ report('push');
150
+ },
151
+ replace: (path, state) => {
152
+ navigateSnapshot(path, true, state);
153
+ report('replace');
154
+ },
155
+ go: (delta) => {
156
+ if (navigateFn) {
157
+ navigateFn(delta);
158
+ report('pop');
159
+ }
160
+ else if (typeof window !== 'undefined') {
161
+ // The core's back()/forward() arrive as the ±1 moves, which window history
162
+ // names `back` and `forward`; any other delta goes through `go` itself.
163
+ if (delta === -1)
164
+ window.history.back();
165
+ else if (delta === 1)
166
+ window.history.forward();
167
+ else
168
+ window.history.go(delta);
169
+ report('pop');
170
+ }
171
+ },
172
+ listen: (listener) => {
173
+ listeners.add(listener);
174
+ return () => {
175
+ listeners.delete(listener);
176
+ };
177
+ },
178
+ destroy: () => {
179
+ listeners.clear();
180
+ },
181
+ };
182
+ // Without configured params the history reports none, and `createHistoryRouter` falls
183
+ // back to matching the registered route definitions.
184
+ if (params)
185
+ history.params = paramsOf;
186
+ return history;
187
+ };
188
+ //# sourceMappingURL=history.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"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"}
package/dist/hooks.d.ts CHANGED
@@ -23,20 +23,23 @@ export interface MoleculeRouterProviderProps {
23
23
  onRouterReady?: (router: Router) => void;
24
24
  }
25
25
  /**
26
- * Provider component that creates a molecule Router from React Router hooks and
27
- * bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
28
- *
29
- * Bonding happens in an effect on mount (and again whenever the location/params
30
- * change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
31
- * React Router adapter — no manual `setRouter` wiring required. Mount it once inside
32
- * any React Router router when non-React code needs the bond, named routes are
33
- * configured, or `onRouterReady` is needed. The routing hooks work without this provider.
26
+ * Provider component that creates ONE molecule Router over React Router for its whole
27
+ * mounted life and bonds it as the active singleton via `@molecule/app-routing`'s
28
+ * `setRouter`. Subscribers and guards registered on the router survive navigation:
29
+ * `@molecule/app-routing`'s `getRouter()` keeps returning it, `onRouterReady` fires once,
30
+ * and React Router's own links and the back button reach `router.subscribe()`.
31
+ *
32
+ * Bonding happens in an effect on mount, so `@molecule/app-routing`'s
33
+ * `navigate()`/`getRouter()` drive THIS real React Router adapter — no manual `setRouter`
34
+ * wiring required. Mount it once inside any React Router router when non-React code needs
35
+ * the bond, named routes are configured, or `onRouterReady` is needed. The routing hooks
36
+ * work without this provider.
34
37
  *
35
38
  * @param props - The provider props (see {@link MoleculeRouterProviderProps}):
36
39
  * `children` (rendered inside the router context), `routes` (optional named-route
37
- * definitions), and `onRouterReady` (optional callback invoked with the router
38
- * after it is bonded, e.g. to register guards — bonding via `setRouter` happens
39
- * regardless).
40
+ * definitions; pass a stable array — later identities register onto the same router),
41
+ * and `onRouterReady` (optional callback invoked ONCE with the router after it is
42
+ * bonded, e.g. to register guards — bonding via `setRouter` happens regardless).
40
43
  * @returns The rendered provider wrapping children with the router context.
41
44
  * @example
42
45
  * ```tsx
@@ -65,9 +68,11 @@ export declare function MoleculeRouterProvider(props: MoleculeRouterProviderProp
65
68
  * package or React Router itself. No MoleculeRouterProvider is required.
66
69
  *
67
70
  * When MoleculeRouterProvider is mounted, returns its exact router with its named
68
- * routes. Otherwise creates a local adapter from React Router's hooks without
69
- * bonding it globally. Mount MoleculeRouterProvider for the non-React
70
- * `@molecule/app-routing` navigate()/getRouter() bond or onRouterReady.
71
+ * routes. Otherwise creates ONE router for the calling component's whole life — its
72
+ * location, params and queries follow React Router through every navigation, and
73
+ * `subscribe()` hears React Router's own links and the back button — without bonding
74
+ * it globally. Mount MoleculeRouterProvider for the non-React `@molecule/app-routing`
75
+ * navigate()/getRouter() bond or onRouterReady.
71
76
  *
72
77
  * @returns The molecule Router instance
73
78
  * @throws {Error} If used outside a React Router router; mount a router component.
@@ -1 +1 @@
1
- {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAEZ,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EAOpB,MAAM,OAAO,CAAA;AAad,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAOtE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAE1B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAgC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAqB1C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,UAAU,CAAC,CAGxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAK9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CA8ErD"}
1
+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAEZ,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EAOpB,MAAM,OAAO,CAAA;AAkBd,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAOtE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAE1B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAgFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA2B5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAsB1C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,UAAU,CAAC,CAGxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAK9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CA8ErD"}