@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 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-10-26T04:27:24.124Z
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 { BrowserRouter, Routes, Route } from 'react-router'
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
- `<BrowserRouter>`.
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 `<BrowserRouter>` (it calls React Router hooks).
930
- - **Import from `'react-router'`, never `'react-router-dom'`.** The `-dom`
931
- package was discontinued after v7 (it was only a re-export shim); every API
932
- (`BrowserRouter`, `Routes`, `Route`, `Link`, hooks) lives in `react-router`.
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
@@ -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
- * `<BrowserRouter>`.
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 { BrowserRouter, Routes, Route } from 'react-router'
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 MoleculeRouterProvider.
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
@@ -1 +1 @@
1
- {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAkC,MAAM,OAAO,CAAA;AAO5F,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAgC5F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAU1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAKlE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,UAAU,CAAC,CAGxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAK9C"}
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"}