@molecule/app-routing-react-router 1.0.0 → 1.0.2
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 +657 -0
- package/package.json +8 -7
package/README.md
ADDED
|
@@ -0,0 +1,657 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:52:33.701Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/app-routing-react-router
|
|
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
|
+
React Router (v7/v8) provider for `@molecule/app-routing`.
|
|
16
|
+
|
|
17
|
+
This package provides a React Router implementation of the molecule Router interface,
|
|
18
|
+
allowing you to use molecule's routing abstractions with React Router.
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { BrowserRouter, Routes, Route } from 'react-router'
|
|
24
|
+
import { MoleculeRouterProvider } from '@molecule/app-routing-react-router'
|
|
25
|
+
|
|
26
|
+
function App() {
|
|
27
|
+
// MoleculeRouterProvider bonds the adapter automatically (calls setRouter in an
|
|
28
|
+
// effect on mount), so @molecule/app-routing's navigate()/getRouter() drive THIS
|
|
29
|
+
// real React Router — no manual setRouter wiring needed.
|
|
30
|
+
return (
|
|
31
|
+
<BrowserRouter>
|
|
32
|
+
<MoleculeRouterProvider>
|
|
33
|
+
<Routes>
|
|
34
|
+
<Route path="/" element={<Home />} />
|
|
35
|
+
<Route path="/users/:id" element={<UserProfile />} />
|
|
36
|
+
</Routes>
|
|
37
|
+
</MoleculeRouterProvider>
|
|
38
|
+
</BrowserRouter>
|
|
39
|
+
)
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Type
|
|
44
|
+
|
|
45
|
+
`provider`
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
npm install @molecule/app-routing-react-router @molecule/app-i18n @molecule/app-routing react react-router
|
|
51
|
+
npm install -D @types/react
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## API
|
|
55
|
+
|
|
56
|
+
### Interfaces
|
|
57
|
+
|
|
58
|
+
#### `MoleculeRouterProviderProps`
|
|
59
|
+
|
|
60
|
+
Provider props.
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
interface MoleculeRouterProviderProps {
|
|
64
|
+
/**
|
|
65
|
+
* Child components.
|
|
66
|
+
*/
|
|
67
|
+
children: ReactNode
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Optional route definitions for named routes.
|
|
71
|
+
*/
|
|
72
|
+
routes?: RouteDefinition[]
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Callback when router is ready.
|
|
76
|
+
*/
|
|
77
|
+
onRouterReady?: (router: Router) => void
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
#### `NavigateOptions`
|
|
82
|
+
|
|
83
|
+
Options for programmatic navigation (replace vs push, carry state, preserve query/hash).
|
|
84
|
+
|
|
85
|
+
```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
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
#### `ReactRouterConfig`
|
|
107
|
+
|
|
108
|
+
React Router-specific configuration.
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
interface ReactRouterConfig {
|
|
112
|
+
/**
|
|
113
|
+
* React Router navigate function (from useNavigate).
|
|
114
|
+
*/
|
|
115
|
+
navigate?: NavigateFunction
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Current location (from useLocation).
|
|
119
|
+
*/
|
|
120
|
+
location?: {
|
|
121
|
+
pathname: string
|
|
122
|
+
search: string
|
|
123
|
+
hash: string
|
|
124
|
+
state?: unknown
|
|
125
|
+
key?: string
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Current params (from useParams).
|
|
130
|
+
*/
|
|
131
|
+
params?: Record<string, string | undefined>
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Initial route definitions.
|
|
135
|
+
*/
|
|
136
|
+
routes?: RouteDefinition[]
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### `ReactRouterHooks`
|
|
141
|
+
|
|
142
|
+
React Router hooks adapter.
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
interface ReactRouterHooks {
|
|
146
|
+
/**
|
|
147
|
+
* The navigate function from useNavigate.
|
|
148
|
+
*/
|
|
149
|
+
navigate: NavigateFunction
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Location from useLocation.
|
|
153
|
+
*/
|
|
154
|
+
location: {
|
|
155
|
+
pathname: string
|
|
156
|
+
search: string
|
|
157
|
+
hash: string
|
|
158
|
+
state?: unknown
|
|
159
|
+
key?: string
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Params from useParams.
|
|
164
|
+
*/
|
|
165
|
+
params: Record<string, string | undefined>
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Search params from useSearchParams.
|
|
169
|
+
*/
|
|
170
|
+
searchParams: URLSearchParams
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
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
|
+
#### `RouteLocation`
|
|
212
|
+
|
|
213
|
+
Current URL decomposed into pathname, search string, hash, navigation state, and unique key.
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
interface RouteLocation {
|
|
217
|
+
/**
|
|
218
|
+
* Current pathname.
|
|
219
|
+
*/
|
|
220
|
+
pathname: string
|
|
221
|
+
/**
|
|
222
|
+
* Query string (including leading ?).
|
|
223
|
+
*/
|
|
224
|
+
search: string
|
|
225
|
+
/**
|
|
226
|
+
* Hash (including leading #).
|
|
227
|
+
*/
|
|
228
|
+
hash: string
|
|
229
|
+
/**
|
|
230
|
+
* State data passed with navigation.
|
|
231
|
+
*/
|
|
232
|
+
state?: unknown
|
|
233
|
+
/**
|
|
234
|
+
* Unique key for this location.
|
|
235
|
+
*/
|
|
236
|
+
key?: string
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
#### `RouteMatch`
|
|
241
|
+
|
|
242
|
+
Result of matching a URL against a route pattern (path, params, query string).
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
interface RouteMatch<Params extends RouteParams = RouteParams> {
|
|
246
|
+
/**
|
|
247
|
+
* Route path pattern.
|
|
248
|
+
*/
|
|
249
|
+
path: string
|
|
250
|
+
/**
|
|
251
|
+
* Matched URL pathname.
|
|
252
|
+
*/
|
|
253
|
+
pathname: string
|
|
254
|
+
/**
|
|
255
|
+
* Route parameters.
|
|
256
|
+
*/
|
|
257
|
+
params: Params
|
|
258
|
+
/**
|
|
259
|
+
* Whether this is an exact match.
|
|
260
|
+
*/
|
|
261
|
+
isExact: boolean
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
#### `Router`
|
|
266
|
+
|
|
267
|
+
Client-side router providing navigation, guards, route matching, and history control.
|
|
268
|
+
|
|
269
|
+
All routing providers must implement this interface.
|
|
270
|
+
|
|
271
|
+
```typescript
|
|
272
|
+
interface Router {
|
|
273
|
+
/**
|
|
274
|
+
* Returns the current route location (pathname, search, hash, state).
|
|
275
|
+
*/
|
|
276
|
+
getLocation(): RouteLocation
|
|
277
|
+
/**
|
|
278
|
+
* Gets the current route params.
|
|
279
|
+
*/
|
|
280
|
+
getParams<T extends RouteParams = RouteParams>(): T
|
|
281
|
+
/**
|
|
282
|
+
* Gets the current query params.
|
|
283
|
+
*/
|
|
284
|
+
getQuery(): QueryParams
|
|
285
|
+
/**
|
|
286
|
+
* Gets a specific query parameter.
|
|
287
|
+
*/
|
|
288
|
+
getQueryParam(key: string): string | undefined
|
|
289
|
+
/**
|
|
290
|
+
* Gets the current hash.
|
|
291
|
+
*/
|
|
292
|
+
getHash(): string
|
|
293
|
+
/**
|
|
294
|
+
* Navigates to a path.
|
|
295
|
+
*/
|
|
296
|
+
navigate(path: string, options?: NavigateOptions): void
|
|
297
|
+
/**
|
|
298
|
+
* Navigates to a named route.
|
|
299
|
+
*/
|
|
300
|
+
navigateTo(
|
|
301
|
+
name: string,
|
|
302
|
+
params?: RouteParams,
|
|
303
|
+
query?: QueryParams,
|
|
304
|
+
options?: NavigateOptions,
|
|
305
|
+
): void
|
|
306
|
+
/**
|
|
307
|
+
* Goes back in history.
|
|
308
|
+
*/
|
|
309
|
+
back(): void
|
|
310
|
+
/**
|
|
311
|
+
* Goes forward in history.
|
|
312
|
+
*/
|
|
313
|
+
forward(): void
|
|
314
|
+
/**
|
|
315
|
+
* Goes to a specific point in history.
|
|
316
|
+
*/
|
|
317
|
+
go(delta: number): void
|
|
318
|
+
/**
|
|
319
|
+
* Updates the current query params.
|
|
320
|
+
*/
|
|
321
|
+
setQuery(params: QueryParams, options?: NavigateOptions): void
|
|
322
|
+
/**
|
|
323
|
+
* Updates a specific query parameter.
|
|
324
|
+
*/
|
|
325
|
+
setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
|
|
326
|
+
/**
|
|
327
|
+
* Updates the current hash.
|
|
328
|
+
*/
|
|
329
|
+
setHash(hash: string, options?: NavigateOptions): void
|
|
330
|
+
/**
|
|
331
|
+
* Checks if a path matches the current location.
|
|
332
|
+
*
|
|
333
|
+
* @returns `true` if the path matches the current route.
|
|
334
|
+
*/
|
|
335
|
+
isActive(path: string, exact?: boolean): boolean
|
|
336
|
+
/**
|
|
337
|
+
* Matches a path pattern against a pathname.
|
|
338
|
+
*/
|
|
339
|
+
matchPath<Params extends RouteParams = RouteParams>(
|
|
340
|
+
pattern: string,
|
|
341
|
+
pathname: string,
|
|
342
|
+
): RouteMatch<Params> | null
|
|
343
|
+
/**
|
|
344
|
+
* Generates a URL from a named route.
|
|
345
|
+
*/
|
|
346
|
+
generatePath(name: string, params?: RouteParams, query?: QueryParams): string
|
|
347
|
+
/**
|
|
348
|
+
* Subscribes to route changes.
|
|
349
|
+
*/
|
|
350
|
+
subscribe(listener: RouteChangeListener): () => void
|
|
351
|
+
/**
|
|
352
|
+
* Adds a navigation guard.
|
|
353
|
+
*/
|
|
354
|
+
addGuard(guard: NavigationGuard): () => void
|
|
355
|
+
/**
|
|
356
|
+
* Registers route definitions.
|
|
357
|
+
*/
|
|
358
|
+
registerRoutes(routes: RouteDefinition[]): void
|
|
359
|
+
/**
|
|
360
|
+
* Gets all registered routes.
|
|
361
|
+
*/
|
|
362
|
+
getRoutes(): RouteDefinition[]
|
|
363
|
+
/**
|
|
364
|
+
* Destroys the router.
|
|
365
|
+
*/
|
|
366
|
+
destroy(): void
|
|
367
|
+
}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
#### `RouterConfig`
|
|
371
|
+
|
|
372
|
+
Configuration options for creating a router instance.
|
|
373
|
+
|
|
374
|
+
```typescript
|
|
375
|
+
interface RouterConfig {
|
|
376
|
+
/**
|
|
377
|
+
* Router mode.
|
|
378
|
+
*/
|
|
379
|
+
mode?: 'history' | 'hash' | 'memory'
|
|
380
|
+
/**
|
|
381
|
+
* Base path.
|
|
382
|
+
*/
|
|
383
|
+
basePath?: string
|
|
384
|
+
/**
|
|
385
|
+
* Initial routes.
|
|
386
|
+
*/
|
|
387
|
+
routes?: RouteDefinition[]
|
|
388
|
+
}
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
### Types
|
|
392
|
+
|
|
393
|
+
#### `GuardResult`
|
|
394
|
+
|
|
395
|
+
Navigation guard result.
|
|
396
|
+
|
|
397
|
+
```typescript
|
|
398
|
+
type GuardResult =
|
|
399
|
+
| boolean
|
|
400
|
+
| string
|
|
401
|
+
| {
|
|
402
|
+
path: string
|
|
403
|
+
replace?: boolean
|
|
404
|
+
}
|
|
405
|
+
| void
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
#### `NavigationGuard`
|
|
409
|
+
|
|
410
|
+
Navigation guard function invoked before each navigation.
|
|
411
|
+
Return `false` to cancel, a string/path to redirect, or void to allow.
|
|
412
|
+
|
|
413
|
+
```typescript
|
|
414
|
+
type NavigationGuard = (
|
|
415
|
+
to: RouteLocation,
|
|
416
|
+
from: RouteLocation | null,
|
|
417
|
+
) => GuardResult | Promise<GuardResult>
|
|
418
|
+
```
|
|
419
|
+
|
|
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
|
+
```
|
|
427
|
+
|
|
428
|
+
#### `RouteChangeListener`
|
|
429
|
+
|
|
430
|
+
Callback invoked on each route change with the new location and the
|
|
431
|
+
navigation action that triggered it.
|
|
432
|
+
|
|
433
|
+
```typescript
|
|
434
|
+
type RouteChangeListener = (location: RouteLocation, action: 'push' | 'replace' | 'pop') => void
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
#### `RouteParams`
|
|
438
|
+
|
|
439
|
+
URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
|
|
440
|
+
|
|
441
|
+
```typescript
|
|
442
|
+
type RouteParams = Record<string, string>
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
### Functions
|
|
446
|
+
|
|
447
|
+
#### `createReactRouter(config)`
|
|
448
|
+
|
|
449
|
+
Creates a React Router adapter that implements the molecule Router interface.
|
|
450
|
+
|
|
451
|
+
```typescript
|
|
452
|
+
function createReactRouter(config?: ReactRouterConfig): Router
|
|
453
|
+
```
|
|
454
|
+
|
|
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.
|
|
458
|
+
|
|
459
|
+
#### `generatePath(pattern, params)`
|
|
460
|
+
|
|
461
|
+
Generates a concrete path from a route pattern by replacing `:param` segments with values.
|
|
462
|
+
Throws if a required param is missing.
|
|
463
|
+
|
|
464
|
+
```typescript
|
|
465
|
+
function generatePath(pattern: string, params?: RouteParams): string
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
- `pattern` — The route pattern (e.g. `'/users/:id'`).
|
|
469
|
+
- `params` — A map of param names to values.
|
|
470
|
+
|
|
471
|
+
**Returns:** The resolved path string with params URL-encoded.
|
|
472
|
+
|
|
473
|
+
#### `matchPath(pattern, pathname, exact)`
|
|
474
|
+
|
|
475
|
+
Matches a path pattern (with `:param` segments and `*` wildcards) against a pathname.
|
|
476
|
+
|
|
477
|
+
```typescript
|
|
478
|
+
function matchPath(pattern: string, pathname: string, exact?: boolean): RouteMatch<Params> | null
|
|
479
|
+
```
|
|
480
|
+
|
|
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.
|
|
484
|
+
|
|
485
|
+
**Returns:** A `RouteMatch` with extracted params, or `null` if no match.
|
|
486
|
+
|
|
487
|
+
#### `MoleculeRouterProvider(props)`
|
|
488
|
+
|
|
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`.
|
|
491
|
+
|
|
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>`.
|
|
496
|
+
|
|
497
|
+
```typescript
|
|
498
|
+
function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
|
|
499
|
+
```
|
|
500
|
+
|
|
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).
|
|
502
|
+
|
|
503
|
+
**Returns:** The rendered provider wrapping children with the router context.
|
|
504
|
+
|
|
505
|
+
#### `normalizePath(path)`
|
|
506
|
+
|
|
507
|
+
Removes trailing slashes from a path. Returns `'/'` for root/empty paths.
|
|
508
|
+
|
|
509
|
+
```typescript
|
|
510
|
+
function normalizePath(path: string): string
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
- `path` — The URL path to normalize.
|
|
514
|
+
|
|
515
|
+
**Returns:** The path without trailing slashes.
|
|
516
|
+
|
|
517
|
+
#### `parseSearchParams(searchParams)`
|
|
518
|
+
|
|
519
|
+
Parses `URLSearchParams` into a molecule `QueryParams` object. Duplicate keys
|
|
520
|
+
are collected into arrays.
|
|
521
|
+
|
|
522
|
+
```typescript
|
|
523
|
+
function parseSearchParams(searchParams: URLSearchParams): QueryParams
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
- `searchParams` — The `URLSearchParams` instance (e.g. from `useSearchParams()`).
|
|
527
|
+
|
|
528
|
+
**Returns:** A `QueryParams` map where duplicate keys become string arrays.
|
|
529
|
+
|
|
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
|
+
#### `stringifyQuery(params)`
|
|
545
|
+
|
|
546
|
+
Converts a molecule `QueryParams` object to a URL search string (e.g. `?key=val&arr=1&arr=2`).
|
|
547
|
+
Omits keys with `undefined` values. Returns empty string if no params.
|
|
548
|
+
|
|
549
|
+
```typescript
|
|
550
|
+
function stringifyQuery(params: QueryParams): string
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
- `params` — The query parameters to stringify.
|
|
554
|
+
|
|
555
|
+
**Returns:** A URL search string starting with `?`, or empty string if no params.
|
|
556
|
+
|
|
557
|
+
#### `useIsActive(path, exact)`
|
|
558
|
+
|
|
559
|
+
Hook to check if a path is currently active.
|
|
560
|
+
|
|
561
|
+
```typescript
|
|
562
|
+
function useIsActive(path: string, exact?: boolean): boolean
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
- `path` — Path to check
|
|
566
|
+
- `exact` — Whether to require exact match
|
|
567
|
+
|
|
568
|
+
**Returns:** Whether the path is active
|
|
569
|
+
|
|
570
|
+
#### `useMoleculeNavigate()`
|
|
571
|
+
|
|
572
|
+
Hook to get a navigate function with molecule Router options.
|
|
573
|
+
|
|
574
|
+
```typescript
|
|
575
|
+
function useMoleculeNavigate(): (path: string, options?: NavigateOptions) => void
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
**Returns:** Navigate function
|
|
579
|
+
|
|
580
|
+
#### `useMoleculeQuery()`
|
|
581
|
+
|
|
582
|
+
Hook to get current query params as an object.
|
|
583
|
+
|
|
584
|
+
```typescript
|
|
585
|
+
function useMoleculeQuery(): QueryParams
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
**Returns:** Query params object
|
|
589
|
+
|
|
590
|
+
#### `useMoleculeRouter()`
|
|
591
|
+
|
|
592
|
+
Hook to get the molecule Router.
|
|
593
|
+
|
|
594
|
+
```typescript
|
|
595
|
+
function useMoleculeRouter(): Router
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
**Returns:** The molecule Router instance
|
|
599
|
+
|
|
600
|
+
### Constants
|
|
601
|
+
|
|
602
|
+
#### `provider`
|
|
603
|
+
|
|
604
|
+
Default React Router provider (basic, no hooks). For full functionality, use
|
|
605
|
+
`createReactRouter` with `useNavigate`/`useLocation`/`useParams`.
|
|
606
|
+
|
|
607
|
+
```typescript
|
|
608
|
+
const provider: Router
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
## Core Interface
|
|
612
|
+
|
|
613
|
+
Implements `@molecule/app-routing` interface.
|
|
614
|
+
|
|
615
|
+
## Bond Wiring
|
|
616
|
+
|
|
617
|
+
Setup function to register this provider with the core interface:
|
|
618
|
+
|
|
619
|
+
```typescript
|
|
620
|
+
import { setRouter } from '@molecule/app-routing'
|
|
621
|
+
import { provider } from '@molecule/app-routing-react-router'
|
|
622
|
+
|
|
623
|
+
export function setupRoutingReactRouter(): void {
|
|
624
|
+
setRouter(provider)
|
|
625
|
+
}
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
## Injection Notes
|
|
629
|
+
|
|
630
|
+
### Requirements
|
|
631
|
+
|
|
632
|
+
Peer dependencies:
|
|
633
|
+
|
|
634
|
+
- `@molecule/app-i18n` ^1.0.1
|
|
635
|
+
- `@molecule/app-routing` ^1.0.1
|
|
636
|
+
- `react` ^18.0.0 || ^19.0.0
|
|
637
|
+
- `react-router` ^7.0.0 || ^8.0.0
|
|
638
|
+
|
|
639
|
+
### Runtime Dependencies
|
|
640
|
+
|
|
641
|
+
- `@molecule/app-i18n`
|
|
642
|
+
- `@molecule/app-routing`
|
|
643
|
+
- `react`
|
|
644
|
+
- `react-router`
|
|
645
|
+
|
|
646
|
+
- **`MoleculeRouterProvider` bonds the router for you.** On mount it calls
|
|
647
|
+
`@molecule/app-routing`'s `setRouter` with the live adapter, so other molecule
|
|
648
|
+
packages' `navigate()`/`getRouter()` drive React Router (real SPA navigation) —
|
|
649
|
+
no manual wiring. Pass `onRouterReady` only if you also need the router instance
|
|
650
|
+
(e.g. to register guards); bonding happens either way.
|
|
651
|
+
- **Do NOT wire the exported `provider` const** in a React Router app — it is a
|
|
652
|
+
no-hooks fallback (empty params, `window.location.href` navigation). Use
|
|
653
|
+
`MoleculeRouterProvider` (or `createReactRouter` with hook values) instead.
|
|
654
|
+
- The provider must live INSIDE `<BrowserRouter>` (it calls React Router hooks).
|
|
655
|
+
- **Import from `'react-router'`, never `'react-router-dom'`.** The `-dom`
|
|
656
|
+
package was discontinued after v7 (it was only a re-export shim); every API
|
|
657
|
+
(`BrowserRouter`, `Routes`, `Route`, `Link`, hooks) lives in `react-router`.
|
package/package.json
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-routing-react-router",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "React Router v7 provider for @molecule/app-routing",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
8
8
|
"files": [
|
|
9
|
-
"dist"
|
|
9
|
+
"dist",
|
|
10
|
+
"README.md"
|
|
10
11
|
],
|
|
11
12
|
"scripts": {
|
|
12
13
|
"build": "tsc",
|
|
@@ -20,26 +21,26 @@
|
|
|
20
21
|
"node": ">=20"
|
|
21
22
|
},
|
|
22
23
|
"peerDependencies": {
|
|
23
|
-
"@molecule/app-i18n": "^1.0.
|
|
24
|
-
"@molecule/app-routing": "^1.0.
|
|
24
|
+
"@molecule/app-i18n": "^1.0.1",
|
|
25
|
+
"@molecule/app-routing": "^1.0.1",
|
|
25
26
|
"react": "^18.0.0 || ^19.0.0",
|
|
26
27
|
"react-router": "^7.0.0 || ^8.0.0"
|
|
27
28
|
},
|
|
28
29
|
"devDependencies": {
|
|
29
|
-
"@molecule/app-i18n": "1.0.
|
|
30
|
+
"@molecule/app-i18n": "1.0.2",
|
|
30
31
|
"@types/node": "26.1.2",
|
|
31
32
|
"@types/react": "19.2.17",
|
|
32
33
|
"react": "19.2.8",
|
|
33
34
|
"react-router": "8.3.0",
|
|
34
35
|
"typescript": "6.0.3",
|
|
35
|
-
"vitest": "4.1.
|
|
36
|
+
"vitest": "4.1.11"
|
|
36
37
|
},
|
|
37
38
|
"repository": {
|
|
38
39
|
"type": "git",
|
|
39
40
|
"url": "https://github.com/molecule-dev/molecule.git",
|
|
40
41
|
"directory": "packages/app/bonds/routing/react-router"
|
|
41
42
|
},
|
|
42
|
-
"homepage": "https://
|
|
43
|
+
"homepage": "https://www.molecule.dev/packages/app-routing-react-router",
|
|
43
44
|
"bugs": "https://github.com/molecule-dev/molecule/issues",
|
|
44
45
|
"publishConfig": {
|
|
45
46
|
"access": "public"
|