@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 +95 -84
- package/dist/history.d.ts +80 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +188 -0
- package/dist/history.js.map +1 -0
- package/dist/hooks.d.ts +19 -14
- package/dist/hooks.d.ts.map +1 -1
- package/dist/hooks.js +113 -46
- package/dist/hooks.js.map +1 -1
- package/dist/list-types.d.ts +7 -85
- package/dist/list-types.d.ts.map +1 -1
- package/dist/list-types.js +6 -0
- package/dist/list-types.js.map +1 -1
- package/dist/provider.d.ts +12 -3
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +51 -231
- package/dist/provider.js.map +1 -1
- package/dist/useListRoute.d.ts +6 -0
- package/dist/useListRoute.d.ts.map +1 -1
- package/dist/useListRoute.js +16 -162
- package/dist/useListRoute.js.map +1 -1
- package/dist/utilities.js +1 -1
- package/dist/utilities.js.map +1 -1
- package/package.json +10 -3
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-
|
|
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
|
-
|
|
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:
|
|
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
|
|
696
|
-
bonds it as the active singleton via `@molecule/app-routing`'s
|
|
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
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
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
|
|
720
|
-
|
|
721
|
-
|
|
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
|
|
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"}
|
package/dist/history.js
ADDED
|
@@ -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
|
|
27
|
-
* bonds it as the active singleton via `@molecule/app-routing`'s
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
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
|
|
38
|
-
*
|
|
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
|
|
69
|
-
*
|
|
70
|
-
*
|
|
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.
|
package/dist/hooks.d.ts.map
CHANGED
|
@@ -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;
|
|
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"}
|