@molecule/app-routing-react-router 1.2.4 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/hooks.js CHANGED
@@ -5,29 +5,98 @@ import { jsx as _jsx } from "react/jsx-runtime";
5
5
  * @module
6
6
  */
7
7
  import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
8
- import { useInRouterContext, useLocation, useNavigate, useParams, useSearchParams, } from 'react-router';
9
- import { t } from '@molecule/app-i18n';
10
- import { setRouter } from '@molecule/app-routing';
11
- import { createReactRouter } from './provider.js';
8
+ import { useInRouterContext, useLocation, useNavigate, useNavigationType, useParams, } from 'react-router';
9
+ import { I18nError } from '@molecule/app-i18n';
10
+ import { createHistoryRouter, setRouter } from '@molecule/app-routing';
11
+ import { createReactRouterHistory, } from './history.js';
12
12
  /**
13
13
  * Context for the molecule Router.
14
14
  */
15
15
  const MoleculeRouterContext = createContext(null);
16
16
  /**
17
- * Provider component that creates a molecule Router from React Router hooks and
18
- * bonds it as the active singleton via `@molecule/app-routing`'s `setRouter`.
17
+ * Maps React Router's navigation type to the molecule action.
19
18
  *
20
- * Bonding happens in an effect on mount (and again whenever the location/params
21
- * change), so `@molecule/app-routing`'s `navigate()`/`getRouter()` drive THIS real
22
- * React Router adapter — no manual `setRouter` wiring required. Mount it once inside
23
- * any React Router router when non-React code needs the bond, named routes are
24
- * configured, or `onRouterReady` is needed. The routing hooks work without this provider.
19
+ * @param navigationType - The `useNavigationType()` value of the committed render.
20
+ * @returns The molecule `NavigationAction` for it.
21
+ */
22
+ const navigationTypeToAction = (navigationType) => {
23
+ if (navigationType === 'POP')
24
+ return 'pop';
25
+ if (navigationType === 'REPLACE')
26
+ return 'replace';
27
+ return 'push';
28
+ };
29
+ /**
30
+ * Notifies the live history's subscribers once after each navigation React Router
31
+ * commits, however it started — a link, the back button, or a navigation through the
32
+ * molecule router. The effect runs when the committed location reaches the component;
33
+ * it is keyed on the location key, so a key React Router already reported (a StrictMode
34
+ * replay) is not reported twice, and the first run — the mount — reports nothing.
35
+ *
36
+ * @param history - The component's live history; `null` skips (a provider's router is already notified by the provider).
37
+ * @param locationKey - The location key of the committed render.
38
+ * @param navigationType - How React Router reached the current entry.
39
+ */
40
+ function useNotifyCommittedNavigation(history, locationKey, navigationType) {
41
+ const lastNotifiedKey = useRef(undefined);
42
+ useEffect(() => {
43
+ if (!history || lastNotifiedKey.current === locationKey)
44
+ return;
45
+ const firstNotification = lastNotifiedKey.current === undefined;
46
+ lastNotifiedKey.current = locationKey;
47
+ if (firstNotification)
48
+ return;
49
+ history.notify(navigationTypeToAction(navigationType));
50
+ }, [history, locationKey, navigationType]);
51
+ }
52
+ /**
53
+ * Builds the component-owned molecule router on the live history: the router is created
54
+ * once for the component's whole life, and the history reads a ref that every render
55
+ * refreshes with the latest `useNavigate()`/`useLocation()`/`useParams()`/
56
+ * `useNavigationType()` values, so its reads always answer for the committed render.
57
+ *
58
+ * @param routes - Route definitions the router is created with; later ones register through `router.registerRoutes`.
59
+ * @returns The router, its live history, and the committed location key with the navigation type of this render.
60
+ */
61
+ function useMoleculeRouterInstance(routes) {
62
+ const navigate = useNavigate();
63
+ const location = useLocation();
64
+ const params = useParams();
65
+ const navigationType = useNavigationType();
66
+ const snapshot = useRef(undefined);
67
+ snapshot.current = {
68
+ navigate,
69
+ location: {
70
+ pathname: location.pathname,
71
+ search: location.search,
72
+ hash: location.hash,
73
+ state: location.state,
74
+ key: location.key,
75
+ },
76
+ params,
77
+ };
78
+ const [history] = useState(() => createReactRouterHistory(snapshot));
79
+ const [router] = useState(() => createHistoryRouter(history, { routes }));
80
+ return { router, history, locationKey: location.key, navigationType };
81
+ }
82
+ /**
83
+ * Provider component that creates ONE molecule Router over React Router for its whole
84
+ * mounted life and bonds it as the active singleton via `@molecule/app-routing`'s
85
+ * `setRouter`. Subscribers and guards registered on the router survive navigation:
86
+ * `@molecule/app-routing`'s `getRouter()` keeps returning it, `onRouterReady` fires once,
87
+ * and React Router's own links and the back button reach `router.subscribe()`.
88
+ *
89
+ * Bonding happens in an effect on mount, so `@molecule/app-routing`'s
90
+ * `navigate()`/`getRouter()` drive THIS real React Router adapter — no manual `setRouter`
91
+ * wiring required. Mount it once inside any React Router router when non-React code needs
92
+ * the bond, named routes are configured, or `onRouterReady` is needed. The routing hooks
93
+ * work without this provider.
25
94
  *
26
95
  * @param props - The provider props (see {@link MoleculeRouterProviderProps}):
27
96
  * `children` (rendered inside the router context), `routes` (optional named-route
28
- * definitions), and `onRouterReady` (optional callback invoked with the router
29
- * after it is bonded, e.g. to register guards — bonding via `setRouter` happens
30
- * regardless).
97
+ * definitions; pass a stable array — later identities register onto the same router),
98
+ * and `onRouterReady` (optional callback invoked ONCE with the router after it is
99
+ * bonded, e.g. to register guards — bonding via `setRouter` happens regardless).
31
100
  * @returns The rendered provider wrapping children with the router context.
32
101
  * @example
33
102
  * ```tsx
@@ -51,28 +120,26 @@ const MoleculeRouterContext = createContext(null);
51
120
  */
52
121
  export function MoleculeRouterProvider(props) {
53
122
  const { children, routes = [], onRouterReady } = props;
54
- const navigate = useNavigate();
55
- const location = useLocation();
56
- const params = useParams();
57
- useSearchParams(); // Subscribe to search param changes
58
- const router = useMemo(() => createReactRouter({
59
- navigate,
60
- location: {
61
- pathname: location.pathname,
62
- search: location.search,
63
- hash: location.hash,
64
- state: location.state,
65
- key: location.key,
66
- },
67
- params,
68
- routes,
69
- }), [navigate, location, params, routes]);
123
+ const { router, history, locationKey, navigationType } = useMoleculeRouterInstance(routes);
124
+ const readyCallback = useRef(onRouterReady);
125
+ readyCallback.current = onRouterReady;
70
126
  useEffect(() => {
71
- // Bond THIS adapter so @molecule/app-routing's navigate()/getRouter() drive the
72
- // real React Router instead of the core's auto-created fallback browser router.
127
+ // Bonded once per router: `@molecule/app-routing`'s navigate()/getRouter() drive THIS
128
+ // real React Router adapter for the provider's whole life, and `onRouterReady` fires
129
+ // once instead of on every navigation.
73
130
  setRouter(router);
74
- onRouterReady?.(router);
75
- }, [router, onRouterReady]);
131
+ readyCallback.current?.(router);
132
+ }, [router]);
133
+ const registeredRoutes = useRef(routes);
134
+ useEffect(() => {
135
+ // The routes the router was created with are already registered; a later array
136
+ // registers onto THIS router instead of replacing it.
137
+ if (registeredRoutes.current === routes)
138
+ return;
139
+ registeredRoutes.current = routes;
140
+ router.registerRoutes(routes);
141
+ }, [routes, router]);
142
+ useNotifyCommittedNavigation(history, locationKey, navigationType);
76
143
  return _jsx(MoleculeRouterContext.Provider, { value: router, children: children });
77
144
  }
78
145
  /**
@@ -81,9 +148,11 @@ export function MoleculeRouterProvider(props) {
81
148
  * package or React Router itself. No MoleculeRouterProvider is required.
82
149
  *
83
150
  * When MoleculeRouterProvider is mounted, returns its exact router with its named
84
- * routes. Otherwise creates a local adapter from React Router's hooks without
85
- * bonding it globally. Mount MoleculeRouterProvider for the non-React
86
- * `@molecule/app-routing` navigate()/getRouter() bond or onRouterReady.
151
+ * routes. Otherwise creates ONE router for the calling component's whole life — its
152
+ * location, params and queries follow React Router through every navigation, and
153
+ * `subscribe()` hears React Router's own links and the back button — without bonding
154
+ * it globally. Mount MoleculeRouterProvider for the non-React `@molecule/app-routing`
155
+ * navigate()/getRouter() bond or onRouterReady.
87
156
  *
88
157
  * @returns The molecule Router instance
89
158
  * @throws {Error} If used outside a React Router router; mount a router component.
@@ -105,16 +174,14 @@ export function useMoleculeRouter() {
105
174
  const router = useContext(MoleculeRouterContext);
106
175
  const inRouter = useInRouterContext();
107
176
  if (!inRouter) {
108
- throw new Error(t('routing.error.useMoleculeRouterOutsideRouter', undefined, {
109
- defaultValue: 'useMoleculeRouter must be used within a React Router router. Mount BrowserRouter, HashRouter, MemoryRouter, Router, or RouterProvider.',
110
- }));
177
+ // Thrown like the package's other errors: the key travels with the English message
178
+ // and is translated wherever the error is shown.
179
+ throw new I18nError('routing.error.useMoleculeRouterOutsideRouter', undefined, '`useMoleculeRouter` must be used within a React Router router. Mount `BrowserRouter`, `HashRouter`, `MemoryRouter`, `Router`, or `RouterProvider`.');
111
180
  }
112
- // Always call the React Router hooks, including when the provider supplies the
113
- // adapter. The guard above throws only for an invalid render outside any router.
114
- const navigate = useNavigate();
115
- const location = useLocation();
116
- const params = useParams();
117
- return useMemo(() => router ?? createReactRouter({ navigate, location, params }), [router, navigate, location, params]);
181
+ const { router: localRouter, history, locationKey, navigationType, } = useMoleculeRouterInstance([]);
182
+ // The provider's router notifies through the provider; a locally created one is idle.
183
+ useNotifyCommittedNavigation(router ? null : history, locationKey, navigationType);
184
+ return router ?? localRouter;
118
185
  }
119
186
  /**
120
187
  * Hook to check if a path is currently active inside any React Router router.
package/dist/hooks.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.tsx"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -14,8 +14,14 @@
14
14
  *
15
15
  * **Paginated or filtered page? Use `useListRoute` for its URL state.** It reads
16
16
  * page, filters and selected views from the current URL; builds links that retain
17
- * the current path/filters; and resets page when a filter or view changes. Declare
18
- * path variants explicitly instead of translating API filters into browser URLs.
17
+ * the current path/filters; and resets page when a filter or view changes.
18
+ * Start with `const pages = useListRoute()`; `filters` and `selections` are optional.
19
+ * On `/category/books` matched by `/category/:slug`, `pages.href({ page: 2 })` is
20
+ * `/category/books?page=2` and `pages.params.slug` is `'books'`. The route's path
21
+ * params need no extra config and never become duplicate query filters. On
22
+ * `/?view=mine`, the same call is `/?view=mine&page=2`: existing query keys keep
23
+ * their order, with page last. Page one omits `page`; unrelated queries and hash
24
+ * survive. Add `path` when changing path params, or `selections` when linking views.
19
25
  * It works under ordinary `BrowserRouter` without a data router or an extra provider.
20
26
  *
21
27
  * @example
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmLG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,YAAY,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyLG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,YAAY,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAA;AACnB,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
package/dist/index.js CHANGED
@@ -14,8 +14,14 @@
14
14
  *
15
15
  * **Paginated or filtered page? Use `useListRoute` for its URL state.** It reads
16
16
  * page, filters and selected views from the current URL; builds links that retain
17
- * the current path/filters; and resets page when a filter or view changes. Declare
18
- * path variants explicitly instead of translating API filters into browser URLs.
17
+ * the current path/filters; and resets page when a filter or view changes.
18
+ * Start with `const pages = useListRoute()`; `filters` and `selections` are optional.
19
+ * On `/category/books` matched by `/category/:slug`, `pages.href({ page: 2 })` is
20
+ * `/category/books?page=2` and `pages.params.slug` is `'books'`. The route's path
21
+ * params need no extra config and never become duplicate query filters. On
22
+ * `/?view=mine`, the same call is `/?view=mine&page=2`: existing query keys keep
23
+ * their order, with page last. Page one omits `page`; unrelated queries and hash
24
+ * survive. Add `path` when changing path params, or `selections` when linking views.
19
25
  * It works under ordinary `BrowserRouter` without a data router or an extra provider.
20
26
  *
21
27
  * @example
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmLG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAe5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyLG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAe5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA"}
@@ -1,86 +1,8 @@
1
- import type { NavigateOptions, QueryParams, RouteParams } from './types.js';
2
- /** Where a list filter lives in the URL. Path values take precedence over query values. */
3
- export interface ListRouteFilter {
4
- /** Query key; defaults to the filter's name when `param` is absent. */
5
- query?: string;
6
- /** Path parameter supplied by the current route, such as `category` in `/topics/:category`. */
7
- param?: string;
8
- /** Value returned when neither URL source supplies a value; omitted from generated queries. */
9
- defaultValue?: string;
10
- }
11
- /** A selectable list view, expressed in the app's own route contract. */
12
- export interface ListRouteSelection {
13
- /** Absolute route pattern, for example `/members/:member/saved`. */
14
- path: string;
15
- /** Query values identifying this view. An undefined value requires the key to be absent. */
16
- query?: QueryParams;
17
- /** A protected selection never loads before authentication is confirmed. */
18
- requiresAuth?: boolean;
19
- }
20
- /** Authentication readiness for protected list selections. */
21
- export interface ListRouteAuth {
22
- /** The auth client's status. Unavailable is distinct from a signed-out session. */
23
- status: 'loading' | 'authenticated' | 'unauthenticated' | 'unavailable';
24
- /** App-owned sign-in URL. A signed-out protected visit replaces history with this URL. */
25
- redirectTo: string;
26
- }
27
- /** URL-backed list state configuration; it neither invents nor rewrites the app's route contract. */
28
- export interface ListRouteOptions<Filter extends string = string, Selection extends string = string> {
29
- /** Fixed number of items per page; defaults to 20. */
30
- pageSize?: number;
31
- /** Query key for a 1-indexed page; defaults to `page`. Page one omits the key. */
32
- pageParam?: string;
33
- /** Route pattern for changing path-backed filters when no selections are configured. */
34
- path?: string;
35
- /** Filters and their URL sources. API-only filters do not belong here. */
36
- filters?: Record<Filter, ListRouteFilter>;
37
- /** Named views sharing a list. Both path variants and query variants are supported. */
38
- selections?: Record<Selection, ListRouteSelection>;
39
- /** Tie-breaker when multiple selections match, or fallback when none matches. */
40
- defaultSelection?: NoInfer<Selection>;
41
- /** Required when a selection is protected. Public views remain public as auth changes. */
42
- auth?: ListRouteAuth;
43
- }
44
- /** A single atomic list navigation. Filter/selection changes reset page unless explicitly supplied. */
45
- export interface ListRouteChange<Filter extends string = string, Selection extends string = string> {
46
- /** Target page, starting at one. */
47
- page?: number;
48
- /** Patch of URL filter values. Undefined removes a query filter. */
49
- filters?: Partial<Record<Filter, string | undefined>>;
50
- /** Target view, resolved through its configured path and query values. */
51
- selection?: Selection;
52
- /** Optional path parameter changes, for example when opening a different member's saved view. */
53
- params?: RouteParams;
54
- }
55
- /** Reactive list state and navigation, derived directly from React Router's current location. */
56
- export interface ListRouteResult<Filter extends string = string, Selection extends string = string> {
57
- /** Current 1-indexed page; malformed and non-positive URL values read as page one. */
58
- page: number;
59
- /** Configured items per page. */
60
- pageSize: number;
61
- /** Zero-indexed item offset for an API request. */
62
- offset: number;
63
- /** Current URL filter values, including values supplied by path parameters. */
64
- filters: Record<Filter, string | undefined>;
65
- /** Matching view, or the configured fallback. */
66
- selection: Selection | undefined;
67
- /** Decoded current path parameters, also usable as API-only filters. */
68
- params: RouteParams;
69
- /** False while a protected selection is awaiting auth, signed out, or unavailable. */
70
- canLoad: boolean;
71
- /** Readiness for the current view. A public view always stays ready. */
72
- status: 'ready' | 'loading' | 'unauthenticated' | 'unavailable';
73
- /** Sign-in destination while a signed-out protected view is being redirected. */
74
- redirectTo: string | undefined;
75
- /** Build a real link target, preserving the current pathname, unrelated query values and hash. */
76
- href: (change?: ListRouteChange<Filter, Selection>) => string;
77
- /** Navigate atomically. Location state is preserved unless options explicitly replace it. */
78
- navigate: (change: ListRouteChange<Filter, Selection>, options?: NavigateOptions) => void;
79
- /** Change only the page, retaining the current filters and view. */
80
- setPage: (page: number, options?: NavigateOptions) => void;
81
- /** Patch URL filters and return to page one. */
82
- setFilters: (filters: Partial<Record<Filter, string | undefined>>, options?: NavigateOptions) => void;
83
- /** Select a configured view at page one, preserving current route parameters. */
84
- select: (selection: Selection, options?: NavigateOptions) => void;
85
- }
1
+ /**
2
+ * Types for URL-backed lists ({@link useListRoute}): the same types every framework's
3
+ * `useListRoute` uses, from `@molecule/app-routing`.
4
+ *
5
+ * @module
6
+ */
7
+ export type { ListRouteAuth, ListRouteChange, ListRouteFilter, ListRouteOptions, ListRouteResult, ListRouteSelection, } from '@molecule/app-routing';
86
8
  //# sourceMappingURL=list-types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"list-types.d.ts","sourceRoot":"","sources":["../src/list-types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"list-types.d.ts","sourceRoot":"","sources":["../src/list-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAA"}
@@ -1,2 +1,8 @@
1
+ /**
2
+ * Types for URL-backed lists ({@link useListRoute}): the same types every framework's
3
+ * `useListRoute` uses, from `@molecule/app-routing`.
4
+ *
5
+ * @module
6
+ */
1
7
  export {};
2
8
  //# sourceMappingURL=list-types.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"list-types.js","sourceRoot":"","sources":["../src/list-types.ts"],"names":[],"mappings":""}
1
+ {"version":3,"file":"list-types.js","sourceRoot":"","sources":["../src/list-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
@@ -1,15 +1,25 @@
1
1
  /**
2
2
  * React Router (v7/v8) provider implementation.
3
3
  *
4
+ * `createReactRouter` is `@molecule/app-routing`'s `createHistoryRouter` over the config
5
+ * snapshot: navigation, guards, query/hash helpers, named routes and matching all come
6
+ * from the shared core, so this bond behaves like every other routing bond.
7
+ *
4
8
  * @module
5
9
  */
6
10
  import type { ReactRouterConfig, Router } from './types.js';
7
11
  /**
8
- * Creates a React Router adapter that implements the molecule Router interface.
12
+ * Creates a React Router adapter that implements the molecule Router interface over a
13
+ * config snapshot: the `navigate` function, `location` and `params` of one render. The
14
+ * snapshot never changes, so every read answers for that render — the hooks
15
+ * (`MoleculeRouterProvider`, `useMoleculeRouter`) build the live router instead, one
16
+ * that follows React Router for its whole life. Navigation runs React Router's
17
+ * `navigate`, falling back to a full-page `window.location` navigation when no
18
+ * `navigate` was given (the hook-less `provider`).
9
19
  *
10
20
  * @example
11
21
  * ```tsx
12
- * import { useNavigate, useLocation, useParams, useSearchParams } from 'react-router'
22
+ * import { useNavigate, useLocation, useParams } from 'react-router'
13
23
  * import { createReactRouter, setRouter } from '@molecule/app-routing-react-router'
14
24
  * import { useEffect, useMemo } from 'react'
15
25
  *
@@ -17,7 +27,6 @@ import type { ReactRouterConfig, Router } from './types.js';
17
27
  * const navigate = useNavigate()
18
28
  * const location = useLocation()
19
29
  * const params = useParams()
20
- * const [searchParams] = useSearchParams()
21
30
  *
22
31
  * const router = useMemo(() => createReactRouter({
23
32
  * navigate,
@@ -1 +1 @@
1
- {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAIV,iBAAiB,EAMjB,MAAM,EACP,MAAM,YAAY,CAAA;AAGnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,iBAAsB,KAAG,MA6QlE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAsB,CAAA"}
1
+ {"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAkD3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,iBAAsB,KAAG,MAGhE,CAAA;AAEH;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAsB,CAAA"}