@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/LICENSE +111 -24
- package/README.md +407 -139
- package/dist/index.d.ts +99 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +99 -0
- package/dist/index.js.map +1 -1
- package/dist/list-types.d.ts +86 -0
- package/dist/list-types.d.ts.map +1 -0
- package/dist/list-types.js +2 -0
- package/dist/list-types.js.map +1 -0
- package/dist/useListRoute.d.ts +14 -0
- package/dist/useListRoute.d.ts.map +1 -0
- package/dist/useListRoute.js +182 -0
- package/dist/useListRoute.js.map +1 -0
- package/package.json +4 -4
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-
|
|
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
|
-
#### `
|
|
192
|
+
#### `ListRouteFilter`
|
|
82
193
|
|
|
83
|
-
|
|
194
|
+
Where a list filter lives in the URL. Path values take precedence over query values.
|
|
84
195
|
|
|
85
196
|
```typescript
|
|
86
|
-
interface
|
|
87
|
-
/**
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
/**
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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
|
-
|
|
682
|
+
### Functions
|
|
438
683
|
|
|
439
|
-
|
|
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
|
-
|
|
695
|
+
function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
|
|
443
696
|
```
|
|
444
697
|
|
|
445
|
-
|
|
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
|
-
|
|
700
|
+
**Returns:** The rendered provider wrapping children with the router context.
|
|
448
701
|
|
|
449
|
-
|
|
702
|
+
#### `useMoleculeRouter()`
|
|
703
|
+
|
|
704
|
+
Hook to get the molecule Router.
|
|
450
705
|
|
|
451
706
|
```typescript
|
|
452
|
-
function
|
|
707
|
+
function useMoleculeRouter(): Router
|
|
453
708
|
```
|
|
454
709
|
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
**Returns:** A molecule `Router` with navigation, guards, query/hash management, and route matching.
|
|
710
|
+
**Returns:** The molecule Router instance
|
|
458
711
|
|
|
459
|
-
#### `
|
|
712
|
+
#### `useIsActive(path, exact)`
|
|
460
713
|
|
|
461
|
-
|
|
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
|
|
717
|
+
function useIsActive(path: string, exact?: boolean): boolean
|
|
466
718
|
```
|
|
467
719
|
|
|
468
|
-
- `
|
|
469
|
-
- `
|
|
720
|
+
- `path` — Path to check
|
|
721
|
+
- `exact` — Whether to require exact match
|
|
470
722
|
|
|
471
|
-
**Returns:**
|
|
723
|
+
**Returns:** Whether the path is active
|
|
472
724
|
|
|
473
|
-
#### `
|
|
725
|
+
#### `useMoleculeNavigate()`
|
|
474
726
|
|
|
475
|
-
|
|
727
|
+
Hook to get a navigate function with molecule Router options.
|
|
476
728
|
|
|
477
729
|
```typescript
|
|
478
|
-
function
|
|
730
|
+
function useMoleculeNavigate(): (path: string, options?: NavigateOptions) => void
|
|
479
731
|
```
|
|
480
732
|
|
|
481
|
-
|
|
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
|
-
|
|
735
|
+
#### `useMoleculeQuery()`
|
|
486
736
|
|
|
487
|
-
|
|
737
|
+
Hook to get current query params as an object.
|
|
488
738
|
|
|
489
|
-
|
|
490
|
-
|
|
739
|
+
```typescript
|
|
740
|
+
function useMoleculeQuery(): QueryParams
|
|
741
|
+
```
|
|
491
742
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
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
|
|
750
|
+
function createReactRouter(config?: ReactRouterConfig): Router
|
|
499
751
|
```
|
|
500
752
|
|
|
501
|
-
- `
|
|
753
|
+
- `config` — Configuration with React Router's `navigate` function, `location`, `params`, and optional `routes`.
|
|
502
754
|
|
|
503
|
-
**Returns:**
|
|
755
|
+
**Returns:** A molecule `Router` with navigation, guards, query/hash management, and route matching.
|
|
504
756
|
|
|
505
|
-
#### `
|
|
757
|
+
#### `useListRoute(options)`
|
|
506
758
|
|
|
507
|
-
|
|
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
|
|
767
|
+
function useListRoute(
|
|
768
|
+
options?: ListRouteOptions<Filter, Selection>,
|
|
769
|
+
): ListRouteResult<Filter, Selection>
|
|
511
770
|
```
|
|
512
771
|
|
|
513
|
-
- `
|
|
772
|
+
- `options` — App-owned filter sources, view paths, pagination and optional auth readiness.
|
|
514
773
|
|
|
515
|
-
**Returns:**
|
|
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
|
-
#### `
|
|
802
|
+
#### `matchPath(pattern, pathname, exact)`
|
|
558
803
|
|
|
559
|
-
|
|
804
|
+
Matches a path pattern (with `:param` segments and `*` wildcards) against a pathname.
|
|
560
805
|
|
|
561
806
|
```typescript
|
|
562
|
-
function
|
|
807
|
+
function matchPath(pattern: string, pathname: string, exact?: boolean): RouteMatch<Params> | null
|
|
563
808
|
```
|
|
564
809
|
|
|
565
|
-
- `
|
|
566
|
-
- `
|
|
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:**
|
|
814
|
+
**Returns:** A `RouteMatch` with extracted params, or `null` if no match.
|
|
569
815
|
|
|
570
|
-
#### `
|
|
816
|
+
#### `generatePath(pattern, params)`
|
|
571
817
|
|
|
572
|
-
|
|
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
|
|
822
|
+
function generatePath(pattern: string, params?: RouteParams): string
|
|
576
823
|
```
|
|
577
824
|
|
|
578
|
-
|
|
825
|
+
- `pattern` — The route pattern (e.g. `'/users/:id'`).
|
|
826
|
+
- `params` — A map of param names to values.
|
|
579
827
|
|
|
580
|
-
|
|
828
|
+
**Returns:** The resolved path string with params URL-encoded.
|
|
581
829
|
|
|
582
|
-
|
|
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
|
|
836
|
+
function resolvePath(to: string, fromPathname: string): string
|
|
586
837
|
```
|
|
587
838
|
|
|
588
|
-
|
|
839
|
+
- `to` — The destination path (absolute or relative).
|
|
840
|
+
- `fromPathname` — The current pathname to resolve against.
|
|
589
841
|
|
|
590
|
-
|
|
842
|
+
**Returns:** The resolved absolute path.
|
|
591
843
|
|
|
592
|
-
|
|
844
|
+
#### `normalizePath(path)`
|
|
845
|
+
|
|
846
|
+
Removes trailing slashes from a path. Returns `'/'` for root/empty paths.
|
|
593
847
|
|
|
594
848
|
```typescript
|
|
595
|
-
function
|
|
849
|
+
function normalizePath(path: string): string
|
|
596
850
|
```
|
|
597
851
|
|
|
598
|
-
|
|
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) —
|