@molecule/app-routing-react-router 1.1.3 → 1.2.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 +208 -118
- package/dist/dom.d.ts +50 -0
- package/dist/dom.d.ts.map +1 -0
- package/dist/dom.js +37 -0
- package/dist/dom.js.map +1 -0
- package/dist/hooks.d.ts +42 -9
- package/dist/hooks.d.ts.map +1 -1
- package/dist/hooks.js +110 -14
- package/dist/hooks.js.map +1 -1
- package/dist/index.d.ts +25 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +24 -7
- package/dist/index.js.map +1 -1
- package/dist/lazyPage.d.ts +57 -0
- package/dist/lazyPage.d.ts.map +1 -0
- package/dist/lazyPage.js +62 -0
- package/dist/lazyPage.js.map +1 -0
- package/dist/routers.d.ts +102 -0
- package/dist/routers.d.ts.map +1 -0
- package/dist/routers.js +86 -0
- package/dist/routers.js.map +1 -0
- package/package.json +27 -2
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-
|
|
6
|
+
Generated: 2026-11-05T21:31:18.760Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/app-routing-react-router
|
|
@@ -13,6 +13,14 @@ React Router (v7/v8) provider for `@molecule/app-routing`.
|
|
|
13
13
|
This package provides a React Router implementation of the molecule Router interface,
|
|
14
14
|
allowing you to use molecule's routing abstractions with React Router.
|
|
15
15
|
|
|
16
|
+
`useMoleculeRouter`, `useMoleculeQuery`, `useMoleculeNavigate`, and `useIsActive`
|
|
17
|
+
work inside any React Router router (BrowserRouter, HashRouter, MemoryRouter,
|
|
18
|
+
Router, or RouterProvider), from this package or React Router itself. No
|
|
19
|
+
MoleculeRouterProvider is required for these hooks. Mount MoleculeRouterProvider
|
|
20
|
+
only to bond the adapter for non-React `@molecule/app-routing` navigate()/getRouter(),
|
|
21
|
+
supply named routes, or receive onRouterReady. Hook-created adapters remain local
|
|
22
|
+
so multiple consumers cannot overwrite the global router bond.
|
|
23
|
+
|
|
16
24
|
**Paginated or filtered page? Use `useListRoute` for its URL state.** It reads
|
|
17
25
|
page, filters and selected views from the current URL; builds links that retain
|
|
18
26
|
the current path/filters; and resets page when a filter or view changes. Declare
|
|
@@ -26,10 +34,11 @@ It works under ordinary `BrowserRouter` without a data router or an extra provid
|
|
|
26
34
|
## Quick Start
|
|
27
35
|
|
|
28
36
|
```tsx
|
|
29
|
-
import {
|
|
30
|
-
import { MoleculeRouterProvider } from '@molecule/app-routing-react-router'
|
|
37
|
+
import { Routes, Route } from 'react-router'
|
|
38
|
+
import { BrowserRouter, MoleculeRouterProvider } from '@molecule/app-routing-react-router'
|
|
31
39
|
|
|
32
40
|
function App() {
|
|
41
|
+
// Optional: include this provider for non-React navigation or named routes.
|
|
33
42
|
// MoleculeRouterProvider bonds the adapter automatically (calls setRouter in an
|
|
34
43
|
// effect on mount), so @molecule/app-routing's navigate()/getRouter() drive THIS
|
|
35
44
|
// real React Router — no manual setRouter wiring needed.
|
|
@@ -160,7 +169,7 @@ const topics = useListRoute({
|
|
|
160
169
|
## Installation
|
|
161
170
|
|
|
162
171
|
```bash
|
|
163
|
-
npm install @molecule/app-routing-react-router @molecule/app-i18n @molecule/app-routing react react-router
|
|
172
|
+
npm install @molecule/app-routing-react-router @molecule/app-i18n @molecule/app-routing react react-dom react-router
|
|
164
173
|
npm install -D @types/react
|
|
165
174
|
```
|
|
166
175
|
|
|
@@ -191,6 +200,17 @@ interface MoleculeRouterProviderProps {
|
|
|
191
200
|
}
|
|
192
201
|
```
|
|
193
202
|
|
|
203
|
+
#### `LazyPageOptions`
|
|
204
|
+
|
|
205
|
+
Options for {@link lazyPage}.
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
interface LazyPageOptions {
|
|
209
|
+
/** What the page's area shows while its code loads. Defaults to nothing. */
|
|
210
|
+
fallback?: ReactNode
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
194
214
|
#### `ListRouteFilter`
|
|
195
215
|
|
|
196
216
|
Where a list filter lives in the URL. Path values take precedence over query values.
|
|
@@ -498,111 +518,6 @@ interface RouteDefinition {
|
|
|
498
518
|
}
|
|
499
519
|
```
|
|
500
520
|
|
|
501
|
-
#### `Router`
|
|
502
|
-
|
|
503
|
-
Client-side router providing navigation, guards, route matching, and history control.
|
|
504
|
-
|
|
505
|
-
All routing providers must implement this interface.
|
|
506
|
-
|
|
507
|
-
```typescript
|
|
508
|
-
interface Router {
|
|
509
|
-
/**
|
|
510
|
-
* Returns the current route location (pathname, search, hash, state).
|
|
511
|
-
*/
|
|
512
|
-
getLocation(): RouteLocation
|
|
513
|
-
/**
|
|
514
|
-
* Gets the current route params.
|
|
515
|
-
*/
|
|
516
|
-
getParams<T extends RouteParams = RouteParams>(): T
|
|
517
|
-
/**
|
|
518
|
-
* Gets the current query params.
|
|
519
|
-
*/
|
|
520
|
-
getQuery(): QueryParams
|
|
521
|
-
/**
|
|
522
|
-
* Gets a specific query parameter.
|
|
523
|
-
*/
|
|
524
|
-
getQueryParam(key: string): string | undefined
|
|
525
|
-
/**
|
|
526
|
-
* Gets the current hash.
|
|
527
|
-
*/
|
|
528
|
-
getHash(): string
|
|
529
|
-
/**
|
|
530
|
-
* Navigates to a path.
|
|
531
|
-
*/
|
|
532
|
-
navigate(path: string, options?: NavigateOptions): void
|
|
533
|
-
/**
|
|
534
|
-
* Navigates to a named route.
|
|
535
|
-
*/
|
|
536
|
-
navigateTo(
|
|
537
|
-
name: string,
|
|
538
|
-
params?: RouteParams,
|
|
539
|
-
query?: QueryParams,
|
|
540
|
-
options?: NavigateOptions,
|
|
541
|
-
): void
|
|
542
|
-
/**
|
|
543
|
-
* Goes back in history.
|
|
544
|
-
*/
|
|
545
|
-
back(): void
|
|
546
|
-
/**
|
|
547
|
-
* Goes forward in history.
|
|
548
|
-
*/
|
|
549
|
-
forward(): void
|
|
550
|
-
/**
|
|
551
|
-
* Goes to a specific point in history.
|
|
552
|
-
*/
|
|
553
|
-
go(delta: number): void
|
|
554
|
-
/**
|
|
555
|
-
* Updates the current query params.
|
|
556
|
-
*/
|
|
557
|
-
setQuery(params: QueryParams, options?: NavigateOptions): void
|
|
558
|
-
/**
|
|
559
|
-
* Updates a specific query parameter.
|
|
560
|
-
*/
|
|
561
|
-
setQueryParam(key: string, value: string | undefined, options?: NavigateOptions): void
|
|
562
|
-
/**
|
|
563
|
-
* Updates the current hash.
|
|
564
|
-
*/
|
|
565
|
-
setHash(hash: string, options?: NavigateOptions): void
|
|
566
|
-
/**
|
|
567
|
-
* Checks if a path matches the current location.
|
|
568
|
-
*
|
|
569
|
-
* @returns `true` if the path matches the current route.
|
|
570
|
-
*/
|
|
571
|
-
isActive(path: string, exact?: boolean): boolean
|
|
572
|
-
/**
|
|
573
|
-
* Matches a path pattern against a pathname.
|
|
574
|
-
*/
|
|
575
|
-
matchPath<Params extends RouteParams = RouteParams>(
|
|
576
|
-
pattern: string,
|
|
577
|
-
pathname: string,
|
|
578
|
-
): RouteMatch<Params> | null
|
|
579
|
-
/**
|
|
580
|
-
* Generates a URL from a named route.
|
|
581
|
-
*/
|
|
582
|
-
generatePath(name: string, params?: RouteParams, query?: QueryParams): string
|
|
583
|
-
/**
|
|
584
|
-
* Subscribes to route changes.
|
|
585
|
-
*/
|
|
586
|
-
subscribe(listener: RouteChangeListener): () => void
|
|
587
|
-
/**
|
|
588
|
-
* Adds a navigation guard.
|
|
589
|
-
*/
|
|
590
|
-
addGuard(guard: NavigationGuard): () => void
|
|
591
|
-
/**
|
|
592
|
-
* Registers route definitions.
|
|
593
|
-
*/
|
|
594
|
-
registerRoutes(routes: RouteDefinition[]): void
|
|
595
|
-
/**
|
|
596
|
-
* Gets all registered routes.
|
|
597
|
-
*/
|
|
598
|
-
getRoutes(): RouteDefinition[]
|
|
599
|
-
/**
|
|
600
|
-
* Destroys the router.
|
|
601
|
-
*/
|
|
602
|
-
destroy(): void
|
|
603
|
-
}
|
|
604
|
-
```
|
|
605
|
-
|
|
606
521
|
#### `RouterConfig`
|
|
607
522
|
|
|
608
523
|
Configuration options for creating a router instance.
|
|
@@ -626,6 +541,62 @@ interface RouterConfig {
|
|
|
626
541
|
|
|
627
542
|
### Types
|
|
628
543
|
|
|
544
|
+
#### `LazyLoadableComponent`
|
|
545
|
+
|
|
546
|
+
Any component `React.lazy` can load.
|
|
547
|
+
|
|
548
|
+
```typescript
|
|
549
|
+
type LazyLoadableComponent = Awaited<ReturnType<Parameters<typeof lazy>[0]>>['default']
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
#### `BrowserRouterProps`
|
|
553
|
+
|
|
554
|
+
Props for {@link BrowserRouter}, with transitions permanently disabled.
|
|
555
|
+
|
|
556
|
+
```typescript
|
|
557
|
+
type BrowserRouterProps = Omit<ReactRouterBrowserRouterProps, 'useTransitions'>
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
#### `HashRouterProps`
|
|
561
|
+
|
|
562
|
+
Props for {@link HashRouter}, with transitions permanently disabled.
|
|
563
|
+
|
|
564
|
+
```typescript
|
|
565
|
+
type HashRouterProps = Omit<ReactRouterHashRouterProps, 'useTransitions'>
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
#### `MemoryRouterProps`
|
|
569
|
+
|
|
570
|
+
Props for {@link MemoryRouter}, with transitions permanently disabled.
|
|
571
|
+
|
|
572
|
+
```typescript
|
|
573
|
+
type MemoryRouterProps = Omit<ReactRouterMemoryRouterProps, 'useTransitions'>
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
#### `HistoryRouterProps`
|
|
577
|
+
|
|
578
|
+
Props for {@link unstable_HistoryRouter}, with transitions permanently disabled.
|
|
579
|
+
|
|
580
|
+
```typescript
|
|
581
|
+
type HistoryRouterProps = Omit<ReactRouterHistoryRouterProps, 'useTransitions'>
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
#### `RouterProps`
|
|
585
|
+
|
|
586
|
+
Props for {@link Router}, with transitions permanently disabled.
|
|
587
|
+
|
|
588
|
+
```typescript
|
|
589
|
+
type RouterProps = Omit<ReactRouterProps, 'useTransitions'>
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
#### `RouterProviderProps`
|
|
593
|
+
|
|
594
|
+
Props for {@link RouterProvider}, with transitions permanently disabled.
|
|
595
|
+
|
|
596
|
+
```typescript
|
|
597
|
+
type RouterProviderProps = Omit<ReactRouterProviderProps, 'useTransitions'>
|
|
598
|
+
```
|
|
599
|
+
|
|
629
600
|
#### `RouteParams`
|
|
630
601
|
|
|
631
602
|
URL path parameter key-value map extracted from dynamic route segments (e.g. `{ id: '123' }`).
|
|
@@ -691,7 +662,8 @@ bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
|
|
|
691
662
|
Bonding happens in an effect on mount (and again whenever the location/params
|
|
692
663
|
change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
|
|
693
664
|
React Router adapter — no manual `setRouter` wiring required. Mount it once inside
|
|
694
|
-
|
|
665
|
+
any React Router router when non-React code needs the bond, named routes are
|
|
666
|
+
configured, or `onRouterReady` is needed. The routing hooks work without this provider.
|
|
695
667
|
|
|
696
668
|
```typescript
|
|
697
669
|
function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element
|
|
@@ -703,7 +675,14 @@ function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.E
|
|
|
703
675
|
|
|
704
676
|
#### `useMoleculeRouter()`
|
|
705
677
|
|
|
706
|
-
Hook to get the molecule Router
|
|
678
|
+
Hook to get the molecule Router inside any React Router router, including
|
|
679
|
+
BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider from this
|
|
680
|
+
package or React Router itself. No MoleculeRouterProvider is required.
|
|
681
|
+
|
|
682
|
+
When MoleculeRouterProvider is mounted, returns its exact router with its named
|
|
683
|
+
routes. Otherwise creates a local adapter from React Router's hooks without
|
|
684
|
+
bonding it globally. Mount MoleculeRouterProvider for the non-React
|
|
685
|
+
`@molecule/app-routing` navigate()/getRouter() bond or onRouterReady.
|
|
707
686
|
|
|
708
687
|
```typescript
|
|
709
688
|
function useMoleculeRouter(): Router
|
|
@@ -713,7 +692,9 @@ function useMoleculeRouter(): Router
|
|
|
713
692
|
|
|
714
693
|
#### `useIsActive(path, exact)`
|
|
715
694
|
|
|
716
|
-
Hook to check if a path is currently active.
|
|
695
|
+
Hook to check if a path is currently active inside any React Router router.
|
|
696
|
+
MoleculeRouterProvider is optional; mount it only for named routes, the
|
|
697
|
+
non-React navigate()/getRouter() bond, or onRouterReady.
|
|
717
698
|
|
|
718
699
|
```typescript
|
|
719
700
|
function useIsActive(path: string, exact?: boolean): boolean
|
|
@@ -726,7 +707,9 @@ function useIsActive(path: string, exact?: boolean): boolean
|
|
|
726
707
|
|
|
727
708
|
#### `useMoleculeNavigate()`
|
|
728
709
|
|
|
729
|
-
Hook to get a navigate function with molecule Router options
|
|
710
|
+
Hook to get a navigate function with molecule Router options inside any React
|
|
711
|
+
Router router. MoleculeRouterProvider is optional; mount it only for named
|
|
712
|
+
routes, the non-React navigate()/getRouter() bond, or onRouterReady.
|
|
730
713
|
|
|
731
714
|
```typescript
|
|
732
715
|
function useMoleculeNavigate(): Router['navigate']
|
|
@@ -736,7 +719,9 @@ function useMoleculeNavigate(): Router['navigate']
|
|
|
736
719
|
|
|
737
720
|
#### `useMoleculeQuery()`
|
|
738
721
|
|
|
739
|
-
Hook to get current query params as an object.
|
|
722
|
+
Hook to get current query params as an object inside any React Router router.
|
|
723
|
+
MoleculeRouterProvider is optional; mount it only for named routes, the
|
|
724
|
+
non-React navigate()/getRouter() bond, or onRouterReady.
|
|
740
725
|
|
|
741
726
|
```typescript
|
|
742
727
|
function useMoleculeQuery(): QueryParams
|
|
@@ -744,6 +729,50 @@ function useMoleculeQuery(): QueryParams
|
|
|
744
729
|
|
|
745
730
|
**Returns:** Query params object
|
|
746
731
|
|
|
732
|
+
#### `useConsumedSearchParam(name)`
|
|
733
|
+
|
|
734
|
+
Consume a credential query parameter into component state and remove only that parameter from
|
|
735
|
+
the address through React Router. The value survives local rerenders, StrictMode, failed-submit
|
|
736
|
+
retries and later query-only navigation; a newly arriving value on the same mounted route is
|
|
737
|
+
consumed too. Path, hash, unrelated query values and router location state are retained.
|
|
738
|
+
|
|
739
|
+
React Router owns the URL replacement, so `useLocation()` and `window.location` agree. A
|
|
740
|
+
metadata-only history merge retains unrelated pre-existing top-level state fields that React
|
|
741
|
+
Router does not model; it never changes the URL or the router's `usr`/`key`/`idx` fields.
|
|
742
|
+
|
|
743
|
+
```typescript
|
|
744
|
+
function useConsumedSearchParam(name: string): readonly [string, Dispatch<SetStateAction<string>>]
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
- `name` — The credential query key to consume, for example `token` or `code`.
|
|
748
|
+
|
|
749
|
+
**Returns:** The consumed value and its state setter; the value is empty before first consumption.
|
|
750
|
+
|
|
751
|
+
#### `lazyPage(load, options)`
|
|
752
|
+
|
|
753
|
+
Load a route's page on demand, inside a Suspense boundary that belongs to the page.
|
|
754
|
+
|
|
755
|
+
Use it instead of `React.lazy` for every page a `<Route>` renders. Navigating to a
|
|
756
|
+
page whose code has not loaded yet then replaces the previous page at once: the
|
|
757
|
+
previous page unmounts and the new page's own boundary shows `fallback` until its
|
|
758
|
+
code arrives. With `React.lazy` under one shared `<Suspense>` around `<Routes>`,
|
|
759
|
+
React keeps the previous page mounted (hidden) behind that boundary's fallback, so
|
|
760
|
+
the URL already names the new page while the old page's content is still in the
|
|
761
|
+
DOM, and a check such as `getByRole('heading')` finds the old page's headings.
|
|
762
|
+
Layout routes (an app shell around `<Outlet />`) stay mounted either way.
|
|
763
|
+
|
|
764
|
+
```typescript
|
|
765
|
+
function lazyPage<Page extends LazyLoadableComponent>(
|
|
766
|
+
load: () => Promise<{ default: Page }>,
|
|
767
|
+
options?: LazyPageOptions,
|
|
768
|
+
): ComponentType<NonNullable<ComponentProps<Page>>>
|
|
769
|
+
```
|
|
770
|
+
|
|
771
|
+
- `load` — Loads the page module, as for `React.lazy`: `() => import('./pages/Article.js').then((m) => ({ default: m.Article }))`.
|
|
772
|
+
- `options` — Optional `fallback` shown in the page's area while its code loads.
|
|
773
|
+
|
|
774
|
+
**Returns:** A component to use as a route's element: `<Route path="/article/:slug" element={<Article />} />`. Its props are the page's own, without the `undefined` an optional props parameter (`function Draft({ initial }: DraftProps = {})`) adds: a component type carrying it is not a valid JSX element type wherever React's types resolve from a second copy.
|
|
775
|
+
|
|
747
776
|
#### `createReactRouter(config)`
|
|
748
777
|
|
|
749
778
|
Creates a React Router adapter that implements the molecule Router interface.
|
|
@@ -756,6 +785,58 @@ function createReactRouter(config?: ReactRouterConfig): Router
|
|
|
756
785
|
|
|
757
786
|
**Returns:** A molecule `Router` with navigation, guards, query/hash management, and route matching.
|
|
758
787
|
|
|
788
|
+
#### `BrowserRouter(props)`
|
|
789
|
+
|
|
790
|
+
Browser router that commits the URL and rendered page together.
|
|
791
|
+
|
|
792
|
+
```typescript
|
|
793
|
+
function BrowserRouter(props: BrowserRouterProps): JSX.Element
|
|
794
|
+
```
|
|
795
|
+
|
|
796
|
+
#### `HashRouter(props)`
|
|
797
|
+
|
|
798
|
+
Hash router that commits the URL and rendered page together.
|
|
799
|
+
|
|
800
|
+
```typescript
|
|
801
|
+
function HashRouter(props: HashRouterProps): JSX.Element
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
#### `MemoryRouter(props)`
|
|
805
|
+
|
|
806
|
+
In-memory router that commits its location and rendered page together.
|
|
807
|
+
|
|
808
|
+
```typescript
|
|
809
|
+
function MemoryRouter(props: MemoryRouterProps): JSX.Element
|
|
810
|
+
```
|
|
811
|
+
|
|
812
|
+
#### `Router(props)`
|
|
813
|
+
|
|
814
|
+
Low-level router that commits its location and rendered page together.
|
|
815
|
+
|
|
816
|
+
```typescript
|
|
817
|
+
function Router(props: RouterProps): JSX.Element
|
|
818
|
+
```
|
|
819
|
+
|
|
820
|
+
#### `RouterProvider(props)`
|
|
821
|
+
|
|
822
|
+
Data-router provider that commits the URL and rendered page together.
|
|
823
|
+
|
|
824
|
+
This is React Router's renderer-neutral provider. In a DOM app, import
|
|
825
|
+
`RouterProvider` from `@molecule/app-routing-react-router/dom` instead, which
|
|
826
|
+
supplies `react-dom`'s `flushSync` the way `react-router/dom` does.
|
|
827
|
+
|
|
828
|
+
```typescript
|
|
829
|
+
function RouterProvider(props: RouterProviderProps): JSX.Element
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
#### `unstable_HistoryRouter(props)`
|
|
833
|
+
|
|
834
|
+
History router that commits the URL and rendered page together.
|
|
835
|
+
|
|
836
|
+
```typescript
|
|
837
|
+
function unstable_HistoryRouter(props: HistoryRouterProps): JSX.Element
|
|
838
|
+
```
|
|
839
|
+
|
|
759
840
|
#### `useListRoute(options)`
|
|
760
841
|
|
|
761
842
|
Own URL-backed pagination, filters and selected views without mirrored state or navigation effects.
|
|
@@ -896,6 +977,7 @@ Peer dependencies:
|
|
|
896
977
|
- `@molecule/app-i18n` ^1.0.1
|
|
897
978
|
- `@molecule/app-routing` ^1.0.1
|
|
898
979
|
- `react` ^18.0.0 || ^19.0.0
|
|
980
|
+
- `react-dom` ^18.0.0 || ^19.0.0
|
|
899
981
|
- `react-router` ^7.0.0 || ^8.0.0
|
|
900
982
|
|
|
901
983
|
### Runtime Dependencies
|
|
@@ -903,6 +985,7 @@ Peer dependencies:
|
|
|
903
985
|
- `@molecule/app-i18n`
|
|
904
986
|
- `@molecule/app-routing`
|
|
905
987
|
- `react`
|
|
988
|
+
- `react-dom`
|
|
906
989
|
- `react-router`
|
|
907
990
|
|
|
908
991
|
- `useListRoute` derives state from the URL on every render, including Back/Forward.
|
|
@@ -926,7 +1009,14 @@ Peer dependencies:
|
|
|
926
1009
|
- **Do NOT wire the exported `provider` const** in a React Router app — it is a
|
|
927
1010
|
no-hooks fallback (empty params, `window.location.href` navigation). Use
|
|
928
1011
|
`MoleculeRouterProvider` (or `createReactRouter` with hook values) instead.
|
|
929
|
-
- The provider must live INSIDE
|
|
930
|
-
- **Import from
|
|
931
|
-
|
|
932
|
-
(`
|
|
1012
|
+
- The provider must live INSIDE a React Router router (it calls React Router hooks).
|
|
1013
|
+
- **Import router components from this bond, never directly from React Router.**
|
|
1014
|
+
Its wrappers turn transitions off, so a navigation renders the new route in the
|
|
1015
|
+
same commit as the URL change. Import non-router APIs (`Routes`, `Route`, `Link`,
|
|
1016
|
+
hooks) from `'react-router'`. A DOM data router's `RouterProvider` and the
|
|
1017
|
+
framework-mode `HydratedRouter` come from `@molecule/app-routing-react-router/dom`.
|
|
1018
|
+
- **Declare pages loaded on demand with `lazyPage`, not `React.lazy`.** Each page then
|
|
1019
|
+
has a Suspense boundary of its own, so navigating to a page whose code is still
|
|
1020
|
+
loading removes the previous page at once. Under one shared `<Suspense>` around
|
|
1021
|
+
`<Routes>`, React keeps the previous page mounted (hidden) until the new code
|
|
1022
|
+
arrives, while the URL already names the new page.
|
package/dist/dom.d.ts
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DOM routers with transitions turned off: the data-router provider and the
|
|
3
|
+
* framework-mode hydrated router.
|
|
4
|
+
*
|
|
5
|
+
* Imported from `@molecule/app-routing-react-router/dom`, kept apart from the main
|
|
6
|
+
* entry because `react-router/dom` needs `react-dom`, which the main entry does not.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import type { ComponentProps, JSX } from 'react';
|
|
11
|
+
import { HydratedRouter as ReactRouterHydratedRouter, type RouterProviderProps as ReactRouterDomProviderProps } from 'react-router/dom';
|
|
12
|
+
/** Props for the DOM {@link RouterProvider}, with transitions permanently disabled. */
|
|
13
|
+
export type RouterProviderProps = Omit<ReactRouterDomProviderProps, 'useTransitions'>;
|
|
14
|
+
/**
|
|
15
|
+
* Props for {@link HydratedRouter}, with transitions permanently disabled. Read from the
|
|
16
|
+
* component itself because `react-router/dom` 7.0.0 exports no `HydratedRouterProps`
|
|
17
|
+
* type, and this package supports every 7.x release.
|
|
18
|
+
*/
|
|
19
|
+
export type HydratedRouterProps = Omit<ComponentProps<typeof ReactRouterHydratedRouter>, 'useTransitions'>;
|
|
20
|
+
/**
|
|
21
|
+
* DOM data-router provider (`react-router/dom`'s, which supplies `react-dom`'s
|
|
22
|
+
* `flushSync`) that renders each navigation in the same commit as the URL change.
|
|
23
|
+
*
|
|
24
|
+
* @param props - The provider's props, without `useTransitions`.
|
|
25
|
+
* @returns React Router's DOM provider with `useTransitions={false}`.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```tsx
|
|
29
|
+
* import { createBrowserRouter } from 'react-router'
|
|
30
|
+
* import { RouterProvider } from '@molecule/app-routing-react-router/dom'
|
|
31
|
+
*
|
|
32
|
+
* const app = <RouterProvider router={createBrowserRouter(routes)} />
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
export declare function RouterProvider(props: RouterProviderProps): JSX.Element;
|
|
36
|
+
/**
|
|
37
|
+
* Framework-mode hydrated router that commits the URL and rendered page together.
|
|
38
|
+
*
|
|
39
|
+
* @param props - The hydrated router's props, without `useTransitions`.
|
|
40
|
+
* @returns React Router's `HydratedRouter` with `useTransitions={false}`.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* ```tsx
|
|
44
|
+
* import { HydratedRouter } from '@molecule/app-routing-react-router/dom'
|
|
45
|
+
*
|
|
46
|
+
* const app = <HydratedRouter />
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
export declare function HydratedRouter(props: HydratedRouterProps): JSX.Element;
|
|
50
|
+
//# sourceMappingURL=dom.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChD,OAAO,EACL,cAAc,IAAI,yBAAyB,EAE3C,KAAK,mBAAmB,IAAI,2BAA2B,EACxD,MAAM,kBAAkB,CAAA;AAEzB,uFAAuF;AACvF,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,2BAA2B,EAAE,gBAAgB,CAAC,CAAA;AAErF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,cAAc,CAAC,OAAO,yBAAyB,CAAC,EAChD,gBAAgB,CACjB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,GAAG,CAAC,OAAO,CAEtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,GAAG,CAAC,OAAO,CAEtE"}
|
package/dist/dom.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
+
import { HydratedRouter as ReactRouterHydratedRouter, RouterProvider as ReactRouterDomProvider, } from 'react-router/dom';
|
|
3
|
+
/**
|
|
4
|
+
* DOM data-router provider (`react-router/dom`'s, which supplies `react-dom`'s
|
|
5
|
+
* `flushSync`) that renders each navigation in the same commit as the URL change.
|
|
6
|
+
*
|
|
7
|
+
* @param props - The provider's props, without `useTransitions`.
|
|
8
|
+
* @returns React Router's DOM provider with `useTransitions={false}`.
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```tsx
|
|
12
|
+
* import { createBrowserRouter } from 'react-router'
|
|
13
|
+
* import { RouterProvider } from '@molecule/app-routing-react-router/dom'
|
|
14
|
+
*
|
|
15
|
+
* const app = <RouterProvider router={createBrowserRouter(routes)} />
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
export function RouterProvider(props) {
|
|
19
|
+
return _jsx(ReactRouterDomProvider, { ...props, useTransitions: false });
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Framework-mode hydrated router that commits the URL and rendered page together.
|
|
23
|
+
*
|
|
24
|
+
* @param props - The hydrated router's props, without `useTransitions`.
|
|
25
|
+
* @returns React Router's `HydratedRouter` with `useTransitions={false}`.
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```tsx
|
|
29
|
+
* import { HydratedRouter } from '@molecule/app-routing-react-router/dom'
|
|
30
|
+
*
|
|
31
|
+
* const app = <HydratedRouter />
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
export function HydratedRouter(props) {
|
|
35
|
+
return _jsx(ReactRouterHydratedRouter, { ...props, useTransitions: false });
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=dom.js.map
|
package/dist/dom.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dom.js","sourceRoot":"","sources":["../src/dom.tsx"],"names":[],"mappings":";AAWA,OAAO,EACL,cAAc,IAAI,yBAAyB,EAC3C,cAAc,IAAI,sBAAsB,GAEzC,MAAM,kBAAkB,CAAA;AAezB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,OAAO,KAAC,sBAAsB,OAAK,KAAK,EAAE,cAAc,EAAE,KAAK,GAAI,CAAA;AACrE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,OAAO,KAAC,yBAAyB,OAAK,KAAK,EAAE,cAAc,EAAE,KAAK,GAAI,CAAA;AACxE,CAAC"}
|
package/dist/hooks.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* @module
|
|
5
5
|
*/
|
|
6
|
-
import React, { type ReactNode } from 'react';
|
|
6
|
+
import React, { type Dispatch, type ReactNode, type SetStateAction } from 'react';
|
|
7
7
|
import type { QueryParams, RouteDefinition, Router } from './types.js';
|
|
8
8
|
/**
|
|
9
9
|
* Provider props.
|
|
@@ -29,7 +29,8 @@ export interface MoleculeRouterProviderProps {
|
|
|
29
29
|
* Bonding happens in an effect on mount (and again whenever the location/params
|
|
30
30
|
* change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
|
|
31
31
|
* React Router adapter — no manual `setRouter` wiring required. Mount it once inside
|
|
32
|
-
*
|
|
32
|
+
* any React Router router when non-React code needs the bond, named routes are
|
|
33
|
+
* configured, or `onRouterReady` is needed. The routing hooks work without this provider.
|
|
33
34
|
*
|
|
34
35
|
* @param props - The provider props (see {@link MoleculeRouterProviderProps}):
|
|
35
36
|
* `children` (rendered inside the router context), `routes` (optional named-route
|
|
@@ -39,8 +40,8 @@ export interface MoleculeRouterProviderProps {
|
|
|
39
40
|
* @returns The rendered provider wrapping children with the router context.
|
|
40
41
|
* @example
|
|
41
42
|
* ```tsx
|
|
42
|
-
* import {
|
|
43
|
-
* import { MoleculeRouterProvider } from '@molecule/app-routing-react-router'
|
|
43
|
+
* import { Routes, Route } from 'react-router'
|
|
44
|
+
* import { BrowserRouter, MoleculeRouterProvider } from '@molecule/app-routing-react-router'
|
|
44
45
|
*
|
|
45
46
|
* function App() {
|
|
46
47
|
* // Bonds automatically — molecule packages' navigate() now drive React Router.
|
|
@@ -59,10 +60,17 @@ export interface MoleculeRouterProviderProps {
|
|
|
59
60
|
*/
|
|
60
61
|
export declare function MoleculeRouterProvider(props: MoleculeRouterProviderProps): React.JSX.Element;
|
|
61
62
|
/**
|
|
62
|
-
* Hook to get the molecule Router
|
|
63
|
+
* Hook to get the molecule Router inside any React Router router, including
|
|
64
|
+
* BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider from this
|
|
65
|
+
* package or React Router itself. No MoleculeRouterProvider is required.
|
|
66
|
+
*
|
|
67
|
+
* When MoleculeRouterProvider is mounted, returns its exact router with its named
|
|
68
|
+
* routes. Otherwise creates a local adapter from React Router's hooks without
|
|
69
|
+
* bonding it globally. Mount MoleculeRouterProvider for the non-React
|
|
70
|
+
* `@molecule/app-routing` navigate()/getRouter() bond or onRouterReady.
|
|
63
71
|
*
|
|
64
72
|
* @returns The molecule Router instance
|
|
65
|
-
* @throws {Error} If used outside
|
|
73
|
+
* @throws {Error} If used outside a React Router router; mount a router component.
|
|
66
74
|
*
|
|
67
75
|
* @example
|
|
68
76
|
* ```tsx
|
|
@@ -79,7 +87,9 @@ export declare function MoleculeRouterProvider(props: MoleculeRouterProviderProp
|
|
|
79
87
|
*/
|
|
80
88
|
export declare function useMoleculeRouter(): Router;
|
|
81
89
|
/**
|
|
82
|
-
* Hook to check if a path is currently active.
|
|
90
|
+
* Hook to check if a path is currently active inside any React Router router.
|
|
91
|
+
* MoleculeRouterProvider is optional; mount it only for named routes, the
|
|
92
|
+
* non-React navigate()/getRouter() bond, or onRouterReady.
|
|
83
93
|
*
|
|
84
94
|
* @param path - Path to check
|
|
85
95
|
* @param exact - Whether to require exact match
|
|
@@ -99,7 +109,9 @@ export declare function useMoleculeRouter(): Router;
|
|
|
99
109
|
*/
|
|
100
110
|
export declare function useIsActive(path: string, exact?: boolean): boolean;
|
|
101
111
|
/**
|
|
102
|
-
* Hook to get a navigate function with molecule Router options
|
|
112
|
+
* Hook to get a navigate function with molecule Router options inside any React
|
|
113
|
+
* Router router. MoleculeRouterProvider is optional; mount it only for named
|
|
114
|
+
* routes, the non-React navigate()/getRouter() bond, or onRouterReady.
|
|
103
115
|
*
|
|
104
116
|
* @returns Navigate function
|
|
105
117
|
*
|
|
@@ -117,7 +129,9 @@ export declare function useIsActive(path: string, exact?: boolean): boolean;
|
|
|
117
129
|
*/
|
|
118
130
|
export declare function useMoleculeNavigate(): Router['navigate'];
|
|
119
131
|
/**
|
|
120
|
-
* Hook to get current query params as an object.
|
|
132
|
+
* Hook to get current query params as an object inside any React Router router.
|
|
133
|
+
* MoleculeRouterProvider is optional; mount it only for named routes, the
|
|
134
|
+
* non-React navigate()/getRouter() bond, or onRouterReady.
|
|
121
135
|
*
|
|
122
136
|
* @returns Query params object
|
|
123
137
|
*
|
|
@@ -130,4 +144,23 @@ export declare function useMoleculeNavigate(): Router['navigate'];
|
|
|
130
144
|
* ```
|
|
131
145
|
*/
|
|
132
146
|
export declare function useMoleculeQuery(): QueryParams;
|
|
147
|
+
/**
|
|
148
|
+
* Consume a credential query parameter into component state and remove only that parameter from
|
|
149
|
+
* the address through React Router. The value survives local rerenders, StrictMode, failed-submit
|
|
150
|
+
* retries and later query-only navigation; a newly arriving value on the same mounted route is
|
|
151
|
+
* consumed too. Path, hash, unrelated query values and router location state are retained.
|
|
152
|
+
*
|
|
153
|
+
* React Router owns the URL replacement, so `useLocation()` and `window.location` agree. A
|
|
154
|
+
* metadata-only history merge retains unrelated pre-existing top-level state fields that React
|
|
155
|
+
* Router does not model; it never changes the URL or the router's `usr`/`key`/`idx` fields.
|
|
156
|
+
*
|
|
157
|
+
* @param name - The credential query key to consume, for example `token` or `code`.
|
|
158
|
+
* @returns The consumed value and its state setter; the value is empty before first consumption.
|
|
159
|
+
* @example
|
|
160
|
+
* ```tsx
|
|
161
|
+
* const [resetToken] = useConsumedSearchParam('token')
|
|
162
|
+
* // The form submits resetToken after the address no longer contains it.
|
|
163
|
+
* ```
|
|
164
|
+
*/
|
|
165
|
+
export declare function useConsumedSearchParam(name: string): readonly [string, Dispatch<SetStateAction<string>>];
|
|
133
166
|
//# sourceMappingURL=hooks.d.ts.map
|
package/dist/hooks.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAEZ,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,cAAc,EAOpB,MAAM,OAAO,CAAA;AAad,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAOtE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAE1B;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAgC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAqB1C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,UAAU,CAAC,CAGxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAK9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CA8ErD"}
|