@molecule/app-routing-react-router 1.2.4 → 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-09T07:07:09.138Z
6
+ Generated: 2026-11-13T19:22:37.386Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-routing-react-router
@@ -23,8 +23,14 @@ so multiple consumers cannot overwrite the global router bond.
23
23
 
24
24
  **Paginated or filtered page? Use `useListRoute` for its URL state.** It reads
25
25
  page, filters and selected views from the current URL; builds links that retain
26
- the current path/filters; and resets page when a filter or view changes. Declare
27
- path variants explicitly instead of translating API filters into browser URLs.
26
+ the current path/filters; and resets page when a filter or view changes.
27
+ Start with `const pages = useListRoute()`; `filters` and `selections` are optional.
28
+ On `/category/books` matched by `/category/:slug`, `pages.href({ page: 2 })` is
29
+ `/category/books?page=2` and `pages.params.slug` is `'books'`. The route's path
30
+ params need no extra config and never become duplicate query filters. On
31
+ `/?view=mine`, the same call is `/?view=mine&page=2`: existing query keys keep
32
+ their order, with page last. Page one omits `page`; unrelated queries and hash
33
+ survive. Add `path` when changing path params, or `selections` when linking views.
28
34
  It works under ordinary `BrowserRouter` without a data router or an extra provider.
29
35
 
30
36
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
@@ -230,6 +236,74 @@ interface LazyPageOptions {
230
236
  }
231
237
  ```
232
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
+
233
307
  #### `ListRouteFilter`
234
308
 
235
309
  Where a list filter lives in the URL. Path values take precedence over query values.
@@ -315,7 +389,7 @@ interface ListRouteChange<Filter extends string = string, Selection extends stri
315
389
 
316
390
  #### `ListRouteResult`
317
391
 
318
- Reactive list state and navigation, derived directly from React Router's current location.
392
+ List state and navigation, derived directly from the current location.
319
393
 
320
394
  ```typescript
321
395
  interface ListRouteResult<Filter extends string = string, Selection extends string = string> {
@@ -353,74 +427,6 @@ interface ListRouteResult<Filter extends string = string, Selection extends stri
353
427
  }
354
428
  ```
355
429
 
356
- #### `ReactRouterConfig`
357
-
358
- React Router-specific configuration.
359
-
360
- ```typescript
361
- interface ReactRouterConfig {
362
- /**
363
- * React Router navigate function (from useNavigate).
364
- */
365
- navigate?: NavigateFunction
366
-
367
- /**
368
- * Current location (from useLocation).
369
- */
370
- location?: {
371
- pathname: string
372
- search: string
373
- hash: string
374
- state?: unknown
375
- key?: string
376
- }
377
-
378
- /**
379
- * Current params (from useParams).
380
- */
381
- params?: Record<string, string | undefined>
382
-
383
- /**
384
- * Initial route definitions.
385
- */
386
- routes?: RouteDefinition[]
387
- }
388
- ```
389
-
390
- #### `ReactRouterHooks`
391
-
392
- React Router hooks adapter.
393
-
394
- ```typescript
395
- interface ReactRouterHooks {
396
- /**
397
- * The navigate function from useNavigate.
398
- */
399
- navigate: NavigateFunction
400
-
401
- /**
402
- * Location from useLocation.
403
- */
404
- location: {
405
- pathname: string
406
- search: string
407
- hash: string
408
- state?: unknown
409
- key?: string
410
- }
411
-
412
- /**
413
- * Params from useParams.
414
- */
415
- params: Record<string, string | undefined>
416
-
417
- /**
418
- * Search params from useSearchParams.
419
- */
420
- searchParams: URLSearchParams
421
- }
422
- ```
423
-
424
430
  #### `RouteLocation`
425
431
 
426
432
  Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
@@ -679,27 +685,30 @@ Callback invoked on each route change with the new location and the
679
685
  navigation action that triggered it.
680
686
 
681
687
  ```typescript
682
- type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void
688
+ type RouteChangeListener = (location: RouteLocation, action: NavigationAction) => void
683
689
  ```
684
690
 
685
691
  ### Functions
686
692
 
687
693
  #### `MoleculeRouterProvider(props)`
688
694
 
689
- Provider component that creates a molecule Router from React Router hooks and
690
- 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()`.
691
700
 
692
- Bonding happens in an effect on mount (and again whenever the location/params
693
- change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
694
- React Router adapter — no manual `setRouter` wiring required. Mount it once inside
695
- any React Router router when non-React code needs the bond, named routes are
696
- 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.
697
706
 
698
707
  ```typescript
699
708
  function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
700
709
  ```
701
710
 
702
- - `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).
703
712
 
704
713
  **Returns:** The rendered provider wrapping children with the router context.
705
714
 
@@ -710,9 +719,11 @@ BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider from this
710
719
  package or React Router itself. No MoleculeRouterProvider is required.
711
720
 
712
721
  When MoleculeRouterProvider is mounted, returns its exact router with its named
713
- routes. Otherwise creates a local adapter from React Router's hooks without
714
- bonding it globally. Mount MoleculeRouterProvider for the non-React
715
- `@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.
716
727
 
717
728
  ```typescript
718
729
  function useMoleculeRouter(): Router
@@ -805,7 +816,13 @@ function lazyPage<Page extends LazyLoadableComponent>(
805
816
 
806
817
  #### `createReactRouter(config)`
807
818
 
808
- 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`).
809
826
 
810
827
  ```typescript
811
828
  function createReactRouter(config?: ReactRouterConfig): Router
@@ -1005,7 +1022,7 @@ export function setupRoutingReactRouter(): void {
1005
1022
  Peer dependencies:
1006
1023
 
1007
1024
  - `@molecule/app-i18n` ^1.0.1
1008
- - `@molecule/app-routing` ^1.0.1
1025
+ - `@molecule/app-routing` ^1.1.0
1009
1026
  - `react` ^18.0.0 || ^19.0.0
1010
1027
  - `react-dom` ^18.0.0 || ^19.0.0
1011
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"}