@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.
Files changed (2) hide show
  1. package/README.md +657 -0
  2. 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.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.0",
24
- "@molecule/app-routing": "^1.0.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.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.10"
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://github.com/molecule-dev/molecule/tree/main/packages/app/bonds/routing/react-router",
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"