@molecule/app-routing-react-router 1.2.5 → 1.4.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-16T11:33:37.438Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-routing-react-router
@@ -33,12 +33,44 @@ their order, with page last. Page one omits `page`; unrelated queries and hash
33
33
  survive. Add `path` when changing path params, or `selections` when linking views.
34
34
  It works under ordinary `BrowserRouter` without a data router or an extra provider.
35
35
 
36
+ **URL-selected tabs or filters? Render `ListRouteNav`.** Declare each view's label,
37
+ path and query together. It renders every declared choice on every route, builds
38
+ each destination through `useListRoute`, resets pagination on selection, and derives
39
+ the active link from the URL. Keep this declaration shared by the related routes.
40
+ Use the UI package's `Tabs` for panels whose selection is genuinely local state.
41
+
36
42
  > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
37
43
  > It is written to be read by coding agents as much as by people, and is generated from this
38
44
  > package's source — edit `src/index.ts` JSDoc, not this file.
39
45
 
40
46
  ## Quick Start
41
47
 
48
+ ```tsx
49
+ import { ListRouteNav } from '@molecule/app-routing-react-router'
50
+ import { useTranslation } from '@molecule/app-react'
51
+
52
+ function OrderViews() {
53
+ const { t } = useTranslation()
54
+ return (
55
+ <ListRouteNav
56
+ aria-label={t('orders.views', undefined, { defaultValue: 'Order views' })}
57
+ selections={{
58
+ all: {
59
+ path: '/orders',
60
+ query: { view: undefined },
61
+ label: t('orders.all', undefined, { defaultValue: 'All orders' }),
62
+ },
63
+ open: {
64
+ path: '/orders',
65
+ query: { view: 'open' },
66
+ label: t('orders.open', undefined, { defaultValue: 'Open orders' }),
67
+ },
68
+ }}
69
+ />
70
+ )
71
+ }
72
+ ```
73
+
42
74
  ```tsx
43
75
  import { Routes, Route } from 'react-router'
44
76
  import { BrowserRouter, MoleculeRouterProvider } from '@molecule/app-routing-react-router'
@@ -202,6 +234,60 @@ npm install -D @types/react
202
234
 
203
235
  ### Interfaces
204
236
 
237
+ #### `ListRouteNavItem`
238
+
239
+ A named list view and its navigation label.
240
+
241
+ ```typescript
242
+ interface ListRouteNavItem extends ListRouteSelection {
243
+ /** Translated label, optionally including an icon. */
244
+ label: ReactNode
245
+ /** Path parameters for this destination; current route parameters are otherwise retained. */
246
+ params?: RouteParams
247
+ /** Keep the choice visible but prevent navigation. Authorization still belongs in the route. */
248
+ disabled?: boolean
249
+ }
250
+ ```
251
+
252
+ #### `ListRouteNavItemState`
253
+
254
+ URL-derived state available to the app's link styling.
255
+
256
+ ```typescript
257
+ interface ListRouteNavItemState<Selection extends string = string> {
258
+ /** The app-owned selection key. */
259
+ selection: Selection
260
+ /** Whether the current URL selects this view. */
261
+ active: boolean
262
+ /** Whether navigation is disabled for this choice. */
263
+ disabled: boolean
264
+ }
265
+ ```
266
+
267
+ #### `ListRouteNavProps`
268
+
269
+ Props for URL-backed list navigation; local content panels use the UI package's Tabs instead.
270
+
271
+ ```typescript
272
+ interface ListRouteNavProps<Selection extends string = string> extends Omit<
273
+ ComponentPropsWithoutRef<'nav'>,
274
+ 'children'
275
+ > {
276
+ /** Accessible navigation name, translated by the app. */
277
+ 'aria-label': string
278
+ /** Every declared view stays visible on every route; labels and targets share one declaration. */
279
+ selections: Record<Selection, ListRouteNavItem>
280
+ /** Tie-breaker or fallback, with the same meaning as useListRoute's defaultSelection. */
281
+ defaultSelection?: NoInfer<Selection>
282
+ /** Pagination query key to remove on selection, defaulting to page. */
283
+ pageParam?: string
284
+ /** Required for protected selections, with the same readiness rules as useListRoute. */
285
+ auth?: ListRouteAuth
286
+ /** App-owned styling, resolved from its class map. */
287
+ linkClassName?: string | ((state: ListRouteNavItemState<Selection>) => string | undefined)
288
+ }
289
+ ```
290
+
205
291
  #### `MoleculeRouterProviderProps`
206
292
 
207
293
  Provider props.
@@ -236,6 +322,74 @@ interface LazyPageOptions {
236
322
  }
237
323
  ```
238
324
 
325
+ #### `ReactRouterConfig`
326
+
327
+ React Router-specific configuration.
328
+
329
+ ```typescript
330
+ interface ReactRouterConfig {
331
+ /**
332
+ * React Router navigate function (from useNavigate).
333
+ */
334
+ navigate?: NavigateFunction
335
+
336
+ /**
337
+ * Current location (from useLocation).
338
+ */
339
+ location?: {
340
+ pathname: string
341
+ search: string
342
+ hash: string
343
+ state?: unknown
344
+ key?: string
345
+ }
346
+
347
+ /**
348
+ * Current params (from useParams).
349
+ */
350
+ params?: Record<string, string | undefined>
351
+
352
+ /**
353
+ * Initial route definitions.
354
+ */
355
+ routes?: RouteDefinition[]
356
+ }
357
+ ```
358
+
359
+ #### `ReactRouterHooks`
360
+
361
+ React Router hooks adapter.
362
+
363
+ ```typescript
364
+ interface ReactRouterHooks {
365
+ /**
366
+ * The navigate function from useNavigate.
367
+ */
368
+ navigate: NavigateFunction
369
+
370
+ /**
371
+ * Location from useLocation.
372
+ */
373
+ location: {
374
+ pathname: string
375
+ search: string
376
+ hash: string
377
+ state?: unknown
378
+ key?: string
379
+ }
380
+
381
+ /**
382
+ * Params from useParams.
383
+ */
384
+ params: Record<string, string | undefined>
385
+
386
+ /**
387
+ * Search params from useSearchParams.
388
+ */
389
+ searchParams: URLSearchParams
390
+ }
391
+ ```
392
+
239
393
  #### `ListRouteFilter`
240
394
 
241
395
  Where a list filter lives in the URL. Path values take precedence over query values.
@@ -321,7 +475,7 @@ interface ListRouteChange<Filter extends string = string, Selection extends stri
321
475
 
322
476
  #### `ListRouteResult`
323
477
 
324
- Reactive list state and navigation, derived directly from React Router's current location.
478
+ List state and navigation, derived directly from the current location.
325
479
 
326
480
  ```typescript
327
481
  interface ListRouteResult<Filter extends string = string, Selection extends string = string> {
@@ -359,74 +513,6 @@ interface ListRouteResult<Filter extends string = string, Selection extends stri
359
513
  }
360
514
  ```
361
515
 
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
516
  #### `RouteLocation`
431
517
 
432
518
  Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
@@ -685,27 +771,52 @@ Callback invoked on each route change with the new location and the
685
771
  navigation action that triggered it.
686
772
 
687
773
  ```typescript
688
- type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void
774
+ type RouteChangeListener = (location: RouteLocation, action: NavigationAction) => void
689
775
  ```
690
776
 
691
777
  ### Functions
692
778
 
779
+ #### `ListRouteNav(props)`
780
+
781
+ Render every declared list view as a router link. The URL selects the active choice, and
782
+ selecting any view resets pagination through useListRoute. Native link behavior (new-tab
783
+ clicks, keyboard activation and history) is preserved. This is a navigation landmark,
784
+ not an ARIA tablist with local panels. No active-value state or change handler is needed.
785
+
786
+ ```typescript
787
+ function ListRouteNav<Selection extends string>({
788
+ selections,
789
+ defaultSelection,
790
+ pageParam,
791
+ auth,
792
+ linkClassName,
793
+ ...rest
794
+ }: ListRouteNavProps<Selection>): JSX.Element
795
+ ```
796
+
797
+ - `props` — Named destinations, translated labels, optional auth and native nav attributes.
798
+
799
+ **Returns:** The navigation landmark and all its declared choices.
800
+
693
801
  #### `MoleculeRouterProvider(props)`
694
802
 
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`.
803
+ Provider component that creates ONE molecule Router over React Router for its whole
804
+ mounted life and bonds it as the active singleton via `@molecule/app-routing`'s
805
+ `setRouter`. Subscribers and guards registered on the router survive navigation:
806
+ `@molecule/app-routing`'s `getRouter()` keeps returning it, `onRouterReady` fires once,
807
+ and React Router's own links and the back button reach `router.subscribe()`.
697
808
 
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.
809
+ Bonding happens in an effect on mount, so `@molecule/app-routing`'s
810
+ `navigate()`/`getRouter()` drive THIS real React Router adapter — no manual `setRouter`
811
+ wiring required. Mount it once inside any React Router router when non-React code needs
812
+ the bond, named routes are configured, or `onRouterReady` is needed. The routing hooks
813
+ work without this provider.
703
814
 
704
815
  ```typescript
705
816
  function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
706
817
  ```
707
818
 
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).
819
+ - `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
820
 
710
821
  **Returns:** The rendered provider wrapping children with the router context.
711
822
 
@@ -716,9 +827,11 @@ BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider from this
716
827
  package or React Router itself. No MoleculeRouterProvider is required.
717
828
 
718
829
  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.
830
+ routes. Otherwise creates ONE router for the calling component's whole life — its
831
+ location, params and queries follow React Router through every navigation, and
832
+ `subscribe()` hears React Router's own links and the back button — without bonding
833
+ it globally. Mount MoleculeRouterProvider for the non-React `@molecule/app-routing`
834
+ navigate()/getRouter() bond or onRouterReady.
722
835
 
723
836
  ```typescript
724
837
  function useMoleculeRouter(): Router
@@ -811,7 +924,13 @@ function lazyPage<Page extends LazyLoadableComponent>(
811
924
 
812
925
  #### `createReactRouter(config)`
813
926
 
814
- Creates a React Router adapter that implements the molecule Router interface.
927
+ Creates a React Router adapter that implements the molecule Router interface over a
928
+ config snapshot: the `navigate` function, `location` and `params` of one render. The
929
+ snapshot never changes, so every read answers for that render — the hooks
930
+ (`MoleculeRouterProvider`, `useMoleculeRouter`) build the live router instead, one
931
+ that follows React Router for its whole life. Navigation runs React Router's
932
+ `navigate`, falling back to a full-page `window.location` navigation when no
933
+ `navigate` was given (the hook-less `provider`).
815
934
 
816
935
  ```typescript
817
936
  function createReactRouter(config?: ReactRouterConfig): Router
@@ -1011,7 +1130,7 @@ export function setupRoutingReactRouter(): void {
1011
1130
  Peer dependencies:
1012
1131
 
1013
1132
  - `@molecule/app-i18n` ^1.0.1
1014
- - `@molecule/app-routing` ^1.0.1
1133
+ - `@molecule/app-routing` ^1.1.0
1015
1134
  - `react` ^18.0.0 || ^19.0.0
1016
1135
  - `react-dom` ^18.0.0 || ^19.0.0
1017
1136
  - `react-router` ^7.0.0 || ^8.0.0
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Navigation between URL-backed list views, using the same declaration for labels and destinations.
3
+ *
4
+ * @module
5
+ */
6
+ import type { ComponentPropsWithoutRef, JSX, ReactNode } from 'react';
7
+ import type { RouteParams } from '@molecule/app-routing';
8
+ import type { ListRouteAuth, ListRouteSelection } from './list-types.js';
9
+ /** A named list view and its navigation label. */
10
+ export interface ListRouteNavItem extends ListRouteSelection {
11
+ /** Translated label, optionally including an icon. */
12
+ label: ReactNode;
13
+ /** Path parameters for this destination; current route parameters are otherwise retained. */
14
+ params?: RouteParams;
15
+ /** Keep the choice visible but prevent navigation. Authorization still belongs in the route. */
16
+ disabled?: boolean;
17
+ }
18
+ /** URL-derived state available to the app's link styling. */
19
+ export interface ListRouteNavItemState<Selection extends string = string> {
20
+ /** The app-owned selection key. */
21
+ selection: Selection;
22
+ /** Whether the current URL selects this view. */
23
+ active: boolean;
24
+ /** Whether navigation is disabled for this choice. */
25
+ disabled: boolean;
26
+ }
27
+ /** Props for URL-backed list navigation; local content panels use the UI package's Tabs instead. */
28
+ export interface ListRouteNavProps<Selection extends string = string> extends Omit<ComponentPropsWithoutRef<'nav'>, 'children'> {
29
+ /** Accessible navigation name, translated by the app. */
30
+ 'aria-label': string;
31
+ /** Every declared view stays visible on every route; labels and targets share one declaration. */
32
+ selections: Record<Selection, ListRouteNavItem>;
33
+ /** Tie-breaker or fallback, with the same meaning as useListRoute's defaultSelection. */
34
+ defaultSelection?: NoInfer<Selection>;
35
+ /** Pagination query key to remove on selection, defaulting to page. */
36
+ pageParam?: string;
37
+ /** Required for protected selections, with the same readiness rules as useListRoute. */
38
+ auth?: ListRouteAuth;
39
+ /** App-owned styling, resolved from its class map. */
40
+ linkClassName?: string | ((state: ListRouteNavItemState<Selection>) => string | undefined);
41
+ }
42
+ /**
43
+ * Render every declared list view as a router link. The URL selects the active choice, and
44
+ * selecting any view resets pagination through useListRoute. Native link behavior (new-tab
45
+ * clicks, keyboard activation and history) is preserved. This is a navigation landmark,
46
+ * not an ARIA tablist with local panels. No active-value state or change handler is needed.
47
+ *
48
+ * @param props - Named destinations, translated labels, optional auth and native nav attributes.
49
+ * @returns The navigation landmark and all its declared choices.
50
+ */
51
+ export declare function ListRouteNav<Selection extends string>({ selections, defaultSelection, pageParam, auth, linkClassName, ...rest }: ListRouteNavProps<Selection>): JSX.Element;
52
+ //# sourceMappingURL=ListRouteNav.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ListRouteNav.d.ts","sourceRoot":"","sources":["../src/ListRouteNav.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGxE,kDAAkD;AAClD,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,sDAAsD;IACtD,KAAK,EAAE,SAAS,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IACtE,mCAAmC;IACnC,SAAS,EAAE,SAAS,CAAA;IACpB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAA;IACf,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,oGAAoG;AACpG,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,IAAI,CAChF,wBAAwB,CAAC,KAAK,CAAC,EAC/B,UAAU,CACX;IACC,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAA;IACpB,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAA;IAC/C,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IACrC,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,qBAAqB,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,CAAA;CAC3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,SAAS,MAAM,EAAE,EACrD,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,IAAI,EACJ,aAAa,EACb,GAAG,IAAI,EACR,EAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,OAAO,CA+C5C"}
@@ -0,0 +1,48 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { Link, useParams } from 'react-router';
3
+ import { generatePath } from '@molecule/app-routing';
4
+ import { useListRoute } from './useListRoute.js';
5
+ /**
6
+ * Render every declared list view as a router link. The URL selects the active choice, and
7
+ * selecting any view resets pagination through useListRoute. Native link behavior (new-tab
8
+ * clicks, keyboard activation and history) is preserved. This is a navigation landmark,
9
+ * not an ARIA tablist with local panels. No active-value state or change handler is needed.
10
+ *
11
+ * @param props - Named destinations, translated labels, optional auth and native nav attributes.
12
+ * @returns The navigation landmark and all its declared choices.
13
+ */
14
+ export function ListRouteNav({ selections, defaultSelection, pageParam, auth, linkClassName, ...rest }) {
15
+ const routeParams = useParams();
16
+ const currentParams = {};
17
+ for (const [name, value] of Object.entries(routeParams)) {
18
+ if (value !== undefined)
19
+ currentParams[name] = value;
20
+ }
21
+ // Resolve per-choice params before matching as well as before building links:
22
+ // two choices can share /folders/:folder while naming different folders.
23
+ const destinations = { ...selections };
24
+ for (const [selection, item] of Object.entries(selections)) {
25
+ if (item.params) {
26
+ destinations[selection] = {
27
+ ...item,
28
+ path: generatePath(item.path, { ...currentParams, ...item.params }),
29
+ };
30
+ }
31
+ }
32
+ const list = useListRoute({ selections: destinations, defaultSelection, pageParam, auth });
33
+ return (_jsx("nav", { ...rest, children: Object.entries(selections).map(([selection, item]) => {
34
+ const active = list.selection === selection;
35
+ const disabled = item.disabled === true;
36
+ const className = typeof linkClassName === 'function'
37
+ ? linkClassName({ selection, active, disabled })
38
+ : linkClassName;
39
+ const attrs = {
40
+ className,
41
+ 'data-state': active ? 'active' : 'inactive',
42
+ 'data-mol-id': `list-route-${selection}`,
43
+ 'aria-current': active ? 'page' : undefined,
44
+ };
45
+ return disabled ? (_jsx("span", { ...attrs, role: "link", "aria-disabled": "true", children: item.label }, selection)) : (_jsx(Link, { ...attrs, to: list.href({ selection }), children: item.label }, selection));
46
+ }) }));
47
+ }
48
+ //# sourceMappingURL=ListRouteNav.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ListRouteNav.js","sourceRoot":"","sources":["../src/ListRouteNav.tsx"],"names":[],"mappings":";AAOA,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAyChD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAA2B,EACrD,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,IAAI,EACJ,aAAa,EACb,GAAG,IAAI,EACsB;IAC7B,MAAM,WAAW,GAAG,SAAS,EAAE,CAAA;IAC/B,MAAM,aAAa,GAAgB,EAAE,CAAA;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS;YAAE,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IACtD,CAAC;IACD,8EAA8E;IAC9E,yEAAyE;IACzE,MAAM,YAAY,GAAG,EAAE,GAAG,UAAU,EAAE,CAAA;IACtC,KAAK,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAoC,EAAE,CAAC;QAC9F,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,YAAY,CAAC,SAAS,CAAC,GAAG;gBACxB,GAAG,IAAI;gBACP,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,aAAa,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;aACpE,CAAA;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE1F,OAAO,CACL,iBAAS,IAAI,YACT,MAAM,CAAC,OAAO,CAAC,UAAU,CAAqC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE;YACzF,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,KAAK,SAAS,CAAA;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAA;YACvC,MAAM,SAAS,GACb,OAAO,aAAa,KAAK,UAAU;gBACjC,CAAC,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAChD,CAAC,CAAC,aAAa,CAAA;YACnB,MAAM,KAAK,GAAG;gBACZ,SAAS;gBACT,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;gBAC5C,aAAa,EAAE,cAAc,SAAS,EAAE;gBACxC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAE,MAAgB,CAAC,CAAC,CAAC,SAAS;aACvD,CAAA;YAED,OAAO,QAAQ,CAAC,CAAC,CAAC,CAChB,kBAA0B,KAAK,EAAE,IAAI,EAAC,MAAM,mBAAe,MAAM,YAC9D,IAAI,CAAC,KAAK,IADF,SAAS,CAEb,CACR,CAAC,CAAC,CAAC,CACF,KAAC,IAAI,OAAqB,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,YAC1D,IAAI,CAAC,KAAK,IADF,SAAS,CAEb,CACR,CAAA;QACH,CAAC,CAAC,GACE,CACP,CAAA;AACH,CAAC"}
@@ -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"}