@molecule/app-routing-react-router 1.0.1 → 1.1.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,20 +3,26 @@ 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-08-04T01:52:33.701Z
6
+ Generated: 2026-10-22T08:48:47.691Z
7
7
  -->
8
8
 
9
9
  # @molecule/app-routing-react-router
10
10
 
11
- > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
12
- > It is written to be read by coding agents as much as by people, and is generated from this
13
- > package's source — edit `src/index.ts` JSDoc, not this file.
14
-
15
11
  React Router (v7/v8) provider for `@molecule/app-routing`.
16
12
 
17
13
  This package provides a React Router implementation of the molecule Router interface,
18
14
  allowing you to use molecule's routing abstractions with React Router.
19
15
 
16
+ **Paginated or filtered page? Use `useListRoute` for its URL state.** It reads
17
+ page, filters and selected views from the current URL; builds links that retain
18
+ the current path/filters; and resets page when a filter or view changes. Declare
19
+ path variants explicitly instead of translating API filters into browser URLs.
20
+ It works under ordinary `BrowserRouter` without a data router or an extra provider.
21
+
22
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
23
+ > It is written to be read by coding agents as much as by people, and is generated from this
24
+ > package's source — edit `src/index.ts` JSDoc, not this file.
25
+
20
26
  ## Quick Start
21
27
 
22
28
  ```tsx
@@ -40,6 +46,111 @@ function App() {
40
46
  }
41
47
  ```
42
48
 
49
+ A list with query-selected views. The public URL remains public after login;
50
+ a protected view waits for session restoration. Include the signed-in principal
51
+ in the data key so one user's cached response cannot appear for another user.
52
+
53
+ ```tsx
54
+ import { Link } from 'react-router'
55
+ import { useAuth, useHttpClient, useTranslation } from '@molecule/app-react'
56
+ import { unwrapList } from '@molecule/app-http'
57
+ import { useQuery } from '@molecule/app-query-react'
58
+ import { useListRoute } from '@molecule/app-routing-react-router'
59
+
60
+ interface Entry {
61
+ id: string
62
+ title: string
63
+ }
64
+
65
+ function ActivityList() {
66
+ const { status, user } = useAuth<{ id: string }>()
67
+ const http = useHttpClient()
68
+ const { t } = useTranslation()
69
+ const list = useListRoute({
70
+ pageSize: 10,
71
+ filters: { category: { query: 'category' }, sort: { defaultValue: 'recent' } },
72
+ selections: {
73
+ public: { path: '/activity', query: { view: undefined } },
74
+ personal: { path: '/activity', query: { view: 'personal' }, requiresAuth: true },
75
+ },
76
+ auth: { status, redirectTo: '/sign-in' },
77
+ })
78
+ const entries = useQuery(
79
+ list.canLoad
80
+ ? {
81
+ key: ['activity', user?.id ?? 'anonymous', list.selection, list.filters, list.page],
82
+ fetch: async (signal) =>
83
+ unwrapList<Entry>(
84
+ await http.get('/api/activity', {
85
+ signal,
86
+ params: {
87
+ ...list.filters,
88
+ view: list.selection,
89
+ limit: list.pageSize,
90
+ offset: list.offset,
91
+ },
92
+ }),
93
+ ),
94
+ }
95
+ : null,
96
+ )
97
+ return (
98
+ <>
99
+ <Link to={list.href({ selection: 'public' })}>
100
+ {t('activity.public', undefined, { defaultValue: 'Public activity' })}
101
+ </Link>
102
+ {user && (
103
+ <Link to={list.href({ selection: 'personal' })}>
104
+ {t('activity.personal', undefined, { defaultValue: 'Your activity' })}
105
+ </Link>
106
+ )}
107
+ <select
108
+ value={list.filters.sort}
109
+ onChange={(event) => list.setFilters({ sort: event.target.value })}
110
+ >
111
+ <option value="recent">
112
+ {t('activity.recent', undefined, { defaultValue: 'Recent' })}
113
+ </option>
114
+ <option value="oldest">
115
+ {t('activity.oldest', undefined, { defaultValue: 'Oldest' })}
116
+ </option>
117
+ </select>
118
+ {entries.data?.map((entry) => (
119
+ <p key={entry.id}>{entry.title}</p>
120
+ ))}
121
+ <Link to={list.href({ page: list.page + 1 })}>
122
+ {t('activity.next', undefined, { defaultValue: 'Next page' })}
123
+ </Link>
124
+ </>
125
+ )
126
+ }
127
+ ```
128
+
129
+ Path-selected views and path-backed filters use the same hook. The browser route
130
+ contract determines the URL; API filters can be derived separately from `params`.
131
+
132
+ ```tsx
133
+ // Mount the same page on /members/:member and /members/:member/saved.
134
+ const list = useListRoute({
135
+ selections: {
136
+ authored: { path: '/members/:member' },
137
+ saved: { path: '/members/:member/saved' },
138
+ },
139
+ })
140
+ // <Link to={list.href({ selection: 'saved' })}>…</Link> retains :member.
141
+ // list.href({ page: 2 }) stays on /members/:member/saved?page=2.
142
+ // Use list.params.member in the API request; it is not another query key.
143
+
144
+ // On /topics/:topic, changing page keeps the encoded topic in the path.
145
+ const topics = useListRoute({
146
+ path: '/topics/:topic',
147
+ filters: { topic: { param: 'topic' }, sort: { defaultValue: 'recent' } },
148
+ })
149
+ // topics.setFilters({ topic: 'type systems' }) changes the path and resets page.
150
+ // PaginationBar can use page={topics.page}, pageSize={topics.pageSize},
151
+ // onPageChange={topics.setPage}; custom links use topics.href({ page: next }).
152
+ ```
153
+
43
154
  ## Type
44
155
 
45
156
  `provider`
@@ -78,28 +189,126 @@ interface MoleculeRouterProviderProps {
78
189
  }
79
190
  ```
80
191
 
81
- #### `NavigateOptions`
192
+ #### `ListRouteFilter`
82
193
 
83
- Options for programmatic navigation (replace vs push, carry state, preserve query/hash).
194
+ Where a list filter lives in the URL. Path values take precedence over query values.
84
195
 
85
196
  ```typescript
86
- interface NavigateOptions {
87
- /**
88
- * Replace current history entry instead of pushing.
89
- */
90
- replace?: boolean
91
- /**
92
- * State to pass with navigation.
93
- */
94
- state?: unknown
95
- /**
96
- * Preserve current query params.
97
- */
98
- preserveQuery?: boolean
99
- /**
100
- * Preserve current hash.
101
- */
102
- preserveHash?: boolean
197
+ interface ListRouteFilter {
198
+ /** Query key; defaults to the filter's name when `param` is absent. */
199
+ query?: string
200
+ /** Path parameter supplied by the current route, such as `category` in `/topics/:category`. */
201
+ param?: string
202
+ /** Value returned when neither URL source supplies a value; omitted from generated queries. */
203
+ defaultValue?: string
204
+ }
205
+ ```
206
+
207
+ #### `ListRouteSelection`
208
+
209
+ A selectable list view, expressed in the app's own route contract.
210
+
211
+ ```typescript
212
+ interface ListRouteSelection {
213
+ /** Absolute route pattern, for example `/members/:member/saved`. */
214
+ path: string
215
+ /** Query values identifying this view. An undefined value requires the key to be absent. */
216
+ query?: QueryParams
217
+ /** A protected selection never loads before authentication is confirmed. */
218
+ requiresAuth?: boolean
219
+ }
220
+ ```
221
+
222
+ #### `ListRouteAuth`
223
+
224
+ Authentication readiness for protected list selections.
225
+
226
+ ```typescript
227
+ interface ListRouteAuth {
228
+ /** The auth client's status. Unavailable is distinct from a signed-out session. */
229
+ status: 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable'
230
+ /** App-owned sign-in URL. A signed-out protected visit replaces history with this URL. */
231
+ redirectTo: string
232
+ }
233
+ ```
234
+
235
+ #### `ListRouteOptions`
236
+
237
+ URL-backed list state configuration; it neither invents nor rewrites the app's route contract.
238
+
239
+ ```typescript
240
+ interface ListRouteOptions<Filter extends string = string, Selection extends string = string> {
241
+ /** Fixed number of items per page; defaults to 20. */
242
+ pageSize?: number
243
+ /** Query key for a 1-indexed page; defaults to `page`. Page one omits the key. */
244
+ pageParam?: string
245
+ /** Route pattern for changing path-backed filters when no selections are configured. */
246
+ path?: string
247
+ /** Filters and their URL sources. API-only filters do not belong here. */
248
+ filters?: Record<Filter, ListRouteFilter>
249
+ /** Named views sharing a list. Both path variants and query variants are supported. */
250
+ selections?: Record<Selection, ListRouteSelection>
251
+ /** Tie-breaker when multiple selections match, or fallback when none matches. */
252
+ defaultSelection?: NoInfer<Selection>
253
+ /** Required when a selection is protected. Public views remain public as auth changes. */
254
+ auth?: ListRouteAuth
255
+ }
256
+ ```
257
+
258
+ #### `ListRouteChange`
259
+
260
+ A single atomic list navigation. Filter/selection changes reset page unless explicitly supplied.
261
+
262
+ ```typescript
263
+ interface ListRouteChange<Filter extends string = string, Selection extends string = string> {
264
+ /** Target page, starting at one. */
265
+ page?: number
266
+ /** Patch of URL filter values. Undefined removes a query filter. */
267
+ filters?: Partial<Record<Filter, string | undefined>>
268
+ /** Target view, resolved through its configured path and query values. */
269
+ selection?: Selection
270
+ /** Optional path parameter changes, for example when opening a different member's saved view. */
271
+ params?: RouteParams
272
+ }
273
+ ```
274
+
275
+ #### `ListRouteResult`
276
+
277
+ Reactive list state and navigation, derived directly from React Router's current location.
278
+
279
+ ```typescript
280
+ interface ListRouteResult<Filter extends string = string, Selection extends string = string> {
281
+ /** Current 1-indexed page; malformed and non-positive URL values read as page one. */
282
+ page: number
283
+ /** Configured items per page. */
284
+ pageSize: number
285
+ /** Zero-indexed item offset for an API request. */
286
+ offset: number
287
+ /** Current URL filter values, including values supplied by path parameters. */
288
+ filters: Record<Filter, string | undefined>
289
+ /** Matching view, or the configured fallback. */
290
+ selection: Selection | undefined
291
+ /** Decoded current path parameters, also usable as API-only filters. */
292
+ params: RouteParams
293
+ /** False while a protected selection is awaiting auth, signed out, or unavailable. */
294
+ canLoad: boolean
295
+ /** Readiness for the current view. A public view always stays ready. */
296
+ status: 'ready' | 'loading' | 'unauthenticated' | 'unavailable'
297
+ /** Sign-in destination while a signed-out protected view is being redirected. */
298
+ redirectTo: string | undefined
299
+ /** Build a real link target, preserving the current pathname, unrelated query values and hash. */
300
+ href: (change?: ListRouteChange<Filter, Selection>) => string
301
+ /** Navigate atomically. Location state is preserved unless options explicitly replace it. */
302
+ navigate: (change: ListRouteChange<Filter, Selection>, options?: NavigateOptions) => void
303
+ /** Change only the page, retaining the current filters and view. */
304
+ setPage: (page: number, options?: NavigateOptions) => void
305
+ /** Patch URL filters and return to page one. */
306
+ setFilters: (
307
+ filters: Partial<Record<Filter, string | undefined>>,
308
+ options?: NavigateOptions,
309
+ ) => void
310
+ /** Select a configured view at page one, preserving current route parameters. */
311
+ select: (selection: Selection, options?: NavigateOptions) => void
103
312
  }
104
313
  ```
105
314
 
@@ -171,43 +380,6 @@ interface ReactRouterHooks {
171
380
  }
172
381
  ```
173
382
 
174
- #### `RouteDefinition`
175
-
176
- Route configuration entry (path pattern, name, auth requirements, roles, children).
177
-
178
- ```typescript
179
- interface RouteDefinition {
180
- /**
181
- * Route path pattern.
182
- */
183
- path: string
184
- /**
185
- * Route name (for named routes).
186
- */
187
- name?: string
188
- /**
189
- * Whether the route requires exact matching.
190
- */
191
- exact?: boolean
192
- /**
193
- * Whether the route requires authentication.
194
- */
195
- requiresAuth?: boolean
196
- /**
197
- * Required roles/permissions.
198
- */
199
- roles?: string[]
200
- /**
201
- * Route metadata.
202
- */
203
- meta?: Record<string, unknown>
204
- /**
205
- * Child routes.
206
- */
207
- children?: RouteDefinition[]
208
- }
209
- ```
210
-
211
383
  #### `RouteLocation`
212
384
 
213
385
  Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
@@ -262,6 +434,68 @@ interface RouteMatch<Params extends RouteParams = RouteParams> {
262
434
  }
263
435
  ```
264
436
 
437
+ #### `NavigateOptions`
438
+
439
+ Options for programmatic navigation (replace vs push, carry state, preserve query/hash).
440
+
441
+ ```typescript
442
+ interface NavigateOptions {
443
+ /**
444
+ * Replace current history entry instead of pushing.
445
+ */
446
+ replace?: boolean
447
+ /**
448
+ * State to pass with navigation.
449
+ */
450
+ state?: unknown
451
+ /**
452
+ * Preserve current query params.
453
+ */
454
+ preserveQuery?: boolean
455
+ /**
456
+ * Preserve current hash.
457
+ */
458
+ preserveHash?: boolean
459
+ }
460
+ ```
461
+
462
+ #### `RouteDefinition`
463
+
464
+ Route configuration entry (path pattern, name, auth requirements, roles, children).
465
+
466
+ ```typescript
467
+ interface RouteDefinition {
468
+ /**
469
+ * Route path pattern.
470
+ */
471
+ path: string
472
+ /**
473
+ * Route name (for named routes).
474
+ */
475
+ name?: string
476
+ /**
477
+ * Whether the route requires exact matching.
478
+ */
479
+ exact?: boolean
480
+ /**
481
+ * Whether the route requires authentication.
482
+ */
483
+ requiresAuth?: boolean
484
+ /**
485
+ * Required roles/permissions.
486
+ */
487
+ roles?: string[]
488
+ /**
489
+ * Route metadata.
490
+ */
491
+ meta?: Record<string, unknown>
492
+ /**
493
+ * Child routes.
494
+ */
495
+ children?: RouteDefinition[]
496
+ }
497
+ ```
498
+
265
499
  #### `Router`
266
500
 
267
501
  Client-side router providing navigation, guards, route matching, and history control.
@@ -390,6 +624,22 @@ interface RouterConfig {
390
624
 
391
625
  ### Types
392
626
 
627
+ #### `RouteParams`
628
+
629
+ URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
630
+
631
+ ```typescript
632
+ type RouteParams = Record<string, string>
633
+ ```
634
+
635
+ #### `QueryParams`
636
+
637
+ URL query string parameter map (single values or arrays for repeated keys).
638
+
639
+ ```typescript
640
+ type QueryParams = Record<string, string | string[] | undefined>
641
+ ```
642
+
393
643
  #### `GuardResult`
394
644
 
395
645
  Navigation guard result.
@@ -417,13 +667,8 @@ type NavigationGuard = (
417
667
  ) => GuardResult | Promise<GuardResult>
418
668
  ```
419
669
 
420
- #### `QueryParams`
421
-
422
- URL query string parameter map (single values or arrays for repeated keys).
423
-
424
- ```typescript
425
- type QueryParams = Record<string, string | string[] | undefined>
426
- ```
670
+ - `to` — The target route location being navigated to.
671
+ - `from` — The current route location being navigated away from, or `null` on initial load.
427
672
 
428
673
  #### `RouteChangeListener`
429
674
 
@@ -434,85 +679,99 @@ navigation action that triggered it.
434
679
  type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void
435
680
  ```
436
681
 
437
- #### `RouteParams`
682
+ ### Functions
438
683
 
439
- URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
684
+ #### `MoleculeRouterProvider(props)`
685
+
686
+ Provider component that creates a molecule Router from React Router hooks and
687
+ bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
688
+
689
+ Bonding happens in an effect on mount (and again whenever the location/params
690
+ change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
691
+ React Router adapter — no manual `setRouter` wiring required. Mount it once inside
692
+ `<BrowserRouter>`.
440
693
 
441
694
  ```typescript
442
- type RouteParams = Record<string, string>
695
+ function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
443
696
  ```
444
697
 
445
- ### Functions
698
+ - `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).
446
699
 
447
- #### `createReactRouter(config)`
700
+ **Returns:** The rendered provider wrapping children with the router context.
448
701
 
449
- Creates a React Router adapter that implements the molecule Router interface.
702
+ #### `useMoleculeRouter()`
703
+
704
+ Hook to get the molecule Router.
450
705
 
451
706
  ```typescript
452
- function createReactRouter(config?: ReactRouterConfig): Router
707
+ function useMoleculeRouter(): Router
453
708
  ```
454
709
 
455
- - `config` — Configuration with React Router's `navigate` function, `location`, `params`, and optional `routes`.
456
-
457
- **Returns:** A molecule `Router` with navigation, guards, query/hash management, and route matching.
710
+ **Returns:** The molecule Router instance
458
711
 
459
- #### `generatePath(pattern, params)`
712
+ #### `useIsActive(path, exact)`
460
713
 
461
- Generates a concrete path from a route pattern by replacing `:param` segments with values.
462
- Throws if a required param is missing.
714
+ Hook to check if a path is currently active.
463
715
 
464
716
  ```typescript
465
- function generatePath(pattern: string, params?: RouteParams): string
717
+ function useIsActive(path: string, exact?: boolean): boolean
466
718
  ```
467
719
 
468
- - `pattern` — The route pattern (e.g. `'/users/:id'`).
469
- - `params` — A map of param names to values.
720
+ - `path` — Path to check
721
+ - `exact` — Whether to require exact match
470
722
 
471
- **Returns:** The resolved path string with params URL-encoded.
723
+ **Returns:** Whether the path is active
472
724
 
473
- #### `matchPath(pattern, pathname, exact)`
725
+ #### `useMoleculeNavigate()`
474
726
 
475
- Matches a path pattern (with `:param` segments and `*` wildcards) against a pathname.
727
+ Hook to get a navigate function with molecule Router options.
476
728
 
477
729
  ```typescript
478
- function matchPath(pattern: string, pathname: string, exact?: boolean): RouteMatch<Params> | null
730
+ function useMoleculeNavigate(): (path: string, options?: NavigateOptions) => void
479
731
  ```
480
732
 
481
- - `pattern` — The route pattern (e.g. `'/users/:id'`).
482
- - `pathname` — The actual URL pathname to test.
483
- - `exact` — Whether to require an exact match (default `true`). Set to `false` for prefix matching.
733
+ **Returns:** Navigate function
484
734
 
485
- **Returns:** A `RouteMatch` with extracted params, or `null` if no match.
735
+ #### `useMoleculeQuery()`
486
736
 
487
- #### `MoleculeRouterProvider(props)`
737
+ Hook to get current query params as an object.
488
738
 
489
- Provider component that creates a molecule Router from React Router hooks and
490
- bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
739
+ ```typescript
740
+ function useMoleculeQuery(): QueryParams
741
+ ```
491
742
 
492
- Bonding happens in an effect on mount (and again whenever the location/params
493
- change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
494
- React Router adapter — no manual `setRouter` wiring required. Mount it once inside
495
- `<BrowserRouter>`.
743
+ **Returns:** Query params object
744
+
745
+ #### `createReactRouter(config)`
746
+
747
+ Creates a React Router adapter that implements the molecule Router interface.
496
748
 
497
749
  ```typescript
498
- function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
750
+ function createReactRouter(config?: ReactRouterConfig): Router
499
751
  ```
500
752
 
501
- - `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).
753
+ - `config` — Configuration with React Router's `navigate` function, `location`, `params`, and optional `routes`.
502
754
 
503
- **Returns:** The rendered provider wrapping children with the router context.
755
+ **Returns:** A molecule `Router` with navigation, guards, query/hash management, and route matching.
504
756
 
505
- #### `normalizePath(path)`
757
+ #### `useListRoute(options)`
506
758
 
507
- Removes trailing slashes from a path. Returns `'/'` for root/empty paths.
759
+ Own URL-backed pagination, filters and selected views without mirrored state or navigation effects.
760
+ Works inside `BrowserRouter`, `MemoryRouter` and data routers; no data-router-only
761
+ `useNavigation` call or MoleculeRouterProvider is needed. Ordinary links, direct visits,
762
+ and Back/Forward all read the same URL. Page links retain path parameters and unrelated
763
+ queries; changing filters or views resets the page atomically. Protected views wait for
764
+ auth and redirect only a confirmed signed-out session, with `state.returnTo` set.
508
765
 
509
766
  ```typescript
510
- function normalizePath(path: string): string
767
+ function useListRoute(
768
+ options?: ListRouteOptions<Filter, Selection>,
769
+ ): ListRouteResult<Filter, Selection>
511
770
  ```
512
771
 
513
- - `path` — The URL path to normalize.
772
+ - `options` — App-owned filter sources, view paths, pagination and optional auth readiness.
514
773
 
515
- **Returns:** The path without trailing slashes.
774
+ **Returns:** Reactive list state plus link builders and navigation actions. Gate data queries with `canLoad`.
516
775
 
517
776
  #### `parseSearchParams(searchParams)`
518
777
 
@@ -527,20 +786,6 @@ function parseSearchParams(searchParams: URLSearchParams): QueryParams
527
786
 
528
787
  **Returns:** A `QueryParams` map where duplicate keys become string arrays.
529
788
 
530
- #### `resolvePath(to, fromPathname)`
531
-
532
- Resolves a relative path against a base pathname. Absolute paths (starting with `/`) are
533
- returned as-is. Relative paths handle `..` (parent) and `.` (current) segments.
534
-
535
- ```typescript
536
- function resolvePath(to: string, fromPathname: string): string
537
- ```
538
-
539
- - `to` — The destination path (absolute or relative).
540
- - `fromPathname` — The current pathname to resolve against.
541
-
542
- **Returns:** The resolved absolute path.
543
-
544
789
  #### `stringifyQuery(params)`
545
790
 
546
791
  Converts a molecule `QueryParams` object to a URL search string (e.g. `?key=val&arr=1&arr=2`).
@@ -554,48 +799,59 @@ function stringifyQuery(params: QueryParams): string
554
799
 
555
800
  **Returns:** A URL search string starting with `?`, or empty string if no params.
556
801
 
557
- #### `useIsActive(path, exact)`
802
+ #### `matchPath(pattern, pathname, exact)`
558
803
 
559
- Hook to check if a path is currently active.
804
+ Matches a path pattern (with `:param` segments and `*` wildcards) against a pathname.
560
805
 
561
806
  ```typescript
562
- function useIsActive(path: string, exact?: boolean): boolean
807
+ function matchPath(pattern: string, pathname: string, exact?: boolean): RouteMatch<Params> | null
563
808
  ```
564
809
 
565
- - `path` — Path to check
566
- - `exact` — Whether to require exact match
810
+ - `pattern` — The route pattern (e.g. `'/users/:id'`).
811
+ - `pathname` — The actual URL pathname to test.
812
+ - `exact` — Whether to require an exact match (default `true`). Set to `false` for prefix matching.
567
813
 
568
- **Returns:** Whether the path is active
814
+ **Returns:** A `RouteMatch` with extracted params, or `null` if no match.
569
815
 
570
- #### `useMoleculeNavigate()`
816
+ #### `generatePath(pattern, params)`
571
817
 
572
- Hook to get a navigate function with molecule Router options.
818
+ Generates a concrete path from a route pattern by replacing `:param` segments with values.
819
+ Throws if a required param is missing.
573
820
 
574
821
  ```typescript
575
- function useMoleculeNavigate(): (path: string, options?: NavigateOptions) => void
822
+ function generatePath(pattern: string, params?: RouteParams): string
576
823
  ```
577
824
 
578
- **Returns:** Navigate function
825
+ - `pattern` — The route pattern (e.g. `'/users/:id'`).
826
+ - `params` — A map of param names to values.
579
827
 
580
- #### `useMoleculeQuery()`
828
+ **Returns:** The resolved path string with params URL-encoded.
581
829
 
582
- Hook to get current query params as an object.
830
+ #### `resolvePath(to, fromPathname)`
831
+
832
+ Resolves a relative path against a base pathname. Absolute paths (starting with `/`) are
833
+ returned as-is. Relative paths handle `..` (parent) and `.` (current) segments.
583
834
 
584
835
  ```typescript
585
- function useMoleculeQuery(): QueryParams
836
+ function resolvePath(to: string, fromPathname: string): string
586
837
  ```
587
838
 
588
- **Returns:** Query params object
839
+ - `to` — The destination path (absolute or relative).
840
+ - `fromPathname` — The current pathname to resolve against.
589
841
 
590
- #### `useMoleculeRouter()`
842
+ **Returns:** The resolved absolute path.
591
843
 
592
- Hook to get the molecule Router.
844
+ #### `normalizePath(path)`
845
+
846
+ Removes trailing slashes from a path. Returns `'/'` for root/empty paths.
593
847
 
594
848
  ```typescript
595
- function useMoleculeRouter(): Router
849
+ function normalizePath(path: string): string
596
850
  ```
597
851
 
598
- **Returns:** The molecule Router instance
852
+ - `path` — The URL path to normalize.
853
+
854
+ **Returns:** The path without trailing slashes.
599
855
 
600
856
  ### Constants
601
857
 
@@ -643,6 +899,18 @@ Peer dependencies:
643
899
  - `react`
644
900
  - `react-router`
645
901
 
902
+ - `useListRoute` derives state from the URL on every render, including Back/Forward.
903
+ Do not mirror selection/page in local state or rewrite an explicit public view
904
+ when auth changes. Auth redirects replace the protected history entry only after
905
+ a confirmed `unauthenticated` status; `loading` and `unavailable` remain in place.
906
+ - Pass `null` to `useQuery` when `list.canLoad` is false. Public views stay ready;
907
+ protected views do not fall back to a public request while auth is unresolved.
908
+ - A selection's `query` owns only its configured keys. `undefined` means absent;
909
+ unrelated query values and the hash survive pagination and selection changes.
910
+ Filter/selection changes reset page one atomically, unless `page` is explicit.
911
+ - `useListRoute` does not call React Router's `useNavigation`: that hook needs a
912
+ data router and throws under `BrowserRouter`. Use the data query's `isFetching`
913
+ for list loading. No UI library, CSS class map, or data cache is required by the hook.
646
914
  - **`MoleculeRouterProvider` bonds the router for you.** On mount it calls
647
915
  `@molecule/app-routing`'s `setRouter` with the live adapter, so other molecule
648
916
  packages' `navigate()`/`getRouter()` drive React Router (real SPA navigation) —