@oomfware/stacker 0.1.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/LICENSE +14 -0
- package/README.md +286 -0
- package/dist/index.d.mts +548 -0
- package/dist/index.mjs +1102 -0
- package/dist/testing.d.mts +33 -0
- package/dist/testing.mjs +121 -0
- package/dist/types-Dj7Al7f8.d.mts +129 -0
- package/dist/url-CoOVqRk_.mjs +37 -0
- package/package.json +74 -0
- package/src/build.ts +53 -0
- package/src/cache.ts +53 -0
- package/src/codec.ts +182 -0
- package/src/history/memory.ts +155 -0
- package/src/history/navigation.ts +213 -0
- package/src/history/types.ts +133 -0
- package/src/index.ts +52 -0
- package/src/keys.ts +41 -0
- package/src/match.ts +180 -0
- package/src/react/context.ts +18 -0
- package/src/react/hooks.ts +178 -0
- package/src/react/link.tsx +61 -0
- package/src/react/outlet.tsx +18 -0
- package/src/react/router-view.tsx +79 -0
- package/src/router.ts +397 -0
- package/src/routes.ts +325 -0
- package/src/testing.ts +2 -0
- package/src/url.ts +41 -0
- package/src/view-model.ts +78 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,548 @@
|
|
|
1
|
+
import { a as HistoryLocation, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryUpdate, t as History } from "./types-Dj7Al7f8.mjs";
|
|
2
|
+
import { AnchorHTMLAttributes, ComponentType, EffectCallback, ReactElement, ReactNode } from "react";
|
|
3
|
+
//#region src/codec.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* a bidirectional codec for a single route parameter.
|
|
6
|
+
*
|
|
7
|
+
* returning `undefined` from `decode` signals validation failure, which causes the matcher to skip the
|
|
8
|
+
* candidate route.
|
|
9
|
+
*/
|
|
10
|
+
interface Codec<T> {
|
|
11
|
+
/**
|
|
12
|
+
* parses a raw URL segment.
|
|
13
|
+
*
|
|
14
|
+
* @param raw the percent-decoded path segment or query value
|
|
15
|
+
* @returns the decoded value, or `undefined` if the segment is invalid
|
|
16
|
+
*/
|
|
17
|
+
decode(raw: string): T | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* serializes a value to a raw URL segment.
|
|
20
|
+
*
|
|
21
|
+
* @param value the value to serialize
|
|
22
|
+
* @returns the raw string value
|
|
23
|
+
*/
|
|
24
|
+
encode(value: T): string;
|
|
25
|
+
}
|
|
26
|
+
declare const OPTIONAL: unique symbol;
|
|
27
|
+
declare const DEFAULT: unique symbol;
|
|
28
|
+
/** a codec whose parameter may be absent. */
|
|
29
|
+
interface OptionalCodec<T> extends Codec<T> {
|
|
30
|
+
readonly [OPTIONAL]: true;
|
|
31
|
+
}
|
|
32
|
+
/** a codec whose parameter has a default fallback. */
|
|
33
|
+
interface DefaultedCodec<T> extends Codec<T> {
|
|
34
|
+
readonly [DEFAULT]: T;
|
|
35
|
+
}
|
|
36
|
+
/** extracts the value type a codec decodes to. */
|
|
37
|
+
type Infer<C> = C extends Codec<infer T> ? T : never;
|
|
38
|
+
type CodecRecord = {
|
|
39
|
+
readonly [name: string]: Codec<any>;
|
|
40
|
+
};
|
|
41
|
+
type Prettify$1<T> = { [K in keyof T]: T[K]; } & {};
|
|
42
|
+
type AnyOptional = {
|
|
43
|
+
readonly [OPTIONAL]: true;
|
|
44
|
+
};
|
|
45
|
+
type AnyDefaulted = {
|
|
46
|
+
readonly [DEFAULT]: unknown;
|
|
47
|
+
};
|
|
48
|
+
type OptionalKeys<P extends CodecRecord> = { [K in keyof P]: P[K] extends AnyOptional ? K : never; }[keyof P];
|
|
49
|
+
type DefaultedKeys<P extends CodecRecord> = { [K in keyof P]: P[K] extends AnyDefaulted ? K : never; }[keyof P];
|
|
50
|
+
type DecodeShape<P extends CodecRecord> = Prettify$1<{ [K in Exclude<keyof P, OptionalKeys<P>>]: Infer<P[K]>; } & { [K in OptionalKeys<P>]?: Infer<P[K]>; }>;
|
|
51
|
+
type BuildShape<P extends CodecRecord> = Prettify$1<{ [K in Exclude<keyof P, DefaultedKeys<P> | OptionalKeys<P>>]: Infer<P[K]>; } & { [K in DefaultedKeys<P> | OptionalKeys<P>]?: Infer<P[K]>; }>;
|
|
52
|
+
/**
|
|
53
|
+
* creates a codec for a string segment.
|
|
54
|
+
*
|
|
55
|
+
* @returns the string codec
|
|
56
|
+
*/
|
|
57
|
+
declare const string: () => Codec<string>;
|
|
58
|
+
/**
|
|
59
|
+
* creates a codec for a safe integer.
|
|
60
|
+
*
|
|
61
|
+
* @returns the integer codec
|
|
62
|
+
*/
|
|
63
|
+
declare const integer: () => Codec<number>;
|
|
64
|
+
/**
|
|
65
|
+
* creates a codec for a boolean value.
|
|
66
|
+
*
|
|
67
|
+
* @returns the boolean codec
|
|
68
|
+
*/
|
|
69
|
+
declare const boolean: () => Codec<boolean>;
|
|
70
|
+
/**
|
|
71
|
+
* creates a codec for a fixed set of string values.
|
|
72
|
+
*
|
|
73
|
+
* @param values the allowed string values
|
|
74
|
+
* @returns the enum codec
|
|
75
|
+
*/
|
|
76
|
+
declare const enumOf: <const V extends readonly string[]>(values: V) => Codec<V[number]>;
|
|
77
|
+
/**
|
|
78
|
+
* wraps a codec to allow its parameter to be absent.
|
|
79
|
+
*
|
|
80
|
+
* @param codec the inner codec
|
|
81
|
+
* @returns the optional codec
|
|
82
|
+
*/
|
|
83
|
+
declare const optional: <T>(codec: Codec<T>) => OptionalCodec<T>;
|
|
84
|
+
/**
|
|
85
|
+
* wraps a codec with a default value.
|
|
86
|
+
*
|
|
87
|
+
* @param codec the inner codec
|
|
88
|
+
* @param fallback the default value
|
|
89
|
+
* @returns the defaulted codec
|
|
90
|
+
*/
|
|
91
|
+
declare const withDefault: <T>(codec: Codec<T>, fallback: T) => DefaultedCodec<T>;
|
|
92
|
+
//#endregion
|
|
93
|
+
//#region src/routes.d.ts
|
|
94
|
+
type Empty = Record<never, never>;
|
|
95
|
+
/**
|
|
96
|
+
* defines how a leaf route instance is keyed.
|
|
97
|
+
*
|
|
98
|
+
* - `page` — one instance per history entry.
|
|
99
|
+
* - `singleton` — one instance per distinct set of path parameters, shared across entries.
|
|
100
|
+
*/
|
|
101
|
+
type LeafType = 'page' | 'singleton';
|
|
102
|
+
/**
|
|
103
|
+
* application-defined metadata attached to routes or layouts.
|
|
104
|
+
*
|
|
105
|
+
* stacker does not read these values, and declares no fields of its own. an application declares the ones it
|
|
106
|
+
* needs and reads them back off the active chain with `resolveMeta`.
|
|
107
|
+
*
|
|
108
|
+
* ```ts
|
|
109
|
+
* declare module '@oomfware/stacker' {
|
|
110
|
+
* interface RouteMeta {
|
|
111
|
+
* readonly requireAuth?: boolean;
|
|
112
|
+
* }
|
|
113
|
+
* }
|
|
114
|
+
* ```
|
|
115
|
+
*/
|
|
116
|
+
interface RouteMeta {}
|
|
117
|
+
/** a read-only view of {@link URLSearchParams} that omits its mutating members. */
|
|
118
|
+
type ReadonlyURLSearchParams = Omit<URLSearchParams, 'append' | 'delete' | 'set' | 'sort'>;
|
|
119
|
+
/** context passed to a route `when` predicate. */
|
|
120
|
+
interface WhenContext {
|
|
121
|
+
readonly hash: string;
|
|
122
|
+
readonly pathname: string;
|
|
123
|
+
readonly rawSearch: ReadonlyURLSearchParams;
|
|
124
|
+
readonly search: string;
|
|
125
|
+
}
|
|
126
|
+
interface LeafShared<Params extends CodecRecord, Query extends CodecRecord> {
|
|
127
|
+
/** component to render. */
|
|
128
|
+
readonly component: ComponentType;
|
|
129
|
+
/** suspense fallback component. */
|
|
130
|
+
readonly fallback?: ReactNode;
|
|
131
|
+
/** application metadata. */
|
|
132
|
+
readonly meta?: RouteMeta;
|
|
133
|
+
/** path parameter codecs. */
|
|
134
|
+
readonly params?: Params;
|
|
135
|
+
/** absolute URL path pattern. */
|
|
136
|
+
readonly path: string;
|
|
137
|
+
/** query parameter codecs. */
|
|
138
|
+
readonly query?: Query;
|
|
139
|
+
/** instance-keying strategy. */
|
|
140
|
+
readonly type?: LeafType;
|
|
141
|
+
/** dynamic predicate for route matching. */
|
|
142
|
+
readonly when?: (ctx: WhenContext) => boolean;
|
|
143
|
+
}
|
|
144
|
+
/** configuration for a navigable leaf route. */
|
|
145
|
+
type RouteConfig<Params extends CodecRecord, Query extends CodecRecord> = LeafShared<Params, Query>;
|
|
146
|
+
/** a navigable leaf route node. */
|
|
147
|
+
interface RouteLeaf<Params extends CodecRecord = Empty, Query extends CodecRecord = Empty> extends LeafShared<Params, Query> {
|
|
148
|
+
readonly kind: 'route';
|
|
149
|
+
}
|
|
150
|
+
/** configuration for an interior layout node. */
|
|
151
|
+
interface LayoutConfig<Children extends RouteChildren, Params extends CodecRecord> {
|
|
152
|
+
/** nested child nodes. */
|
|
153
|
+
readonly children: Children;
|
|
154
|
+
/** layout component rendering an outlet. */
|
|
155
|
+
readonly component: ComponentType;
|
|
156
|
+
/** suspense fallback component. */
|
|
157
|
+
readonly fallback?: ReactNode;
|
|
158
|
+
/** application metadata. */
|
|
159
|
+
readonly meta?: RouteMeta;
|
|
160
|
+
/**
|
|
161
|
+
* codecs for layout parameters. parameter names must appear in all descendant leaf paths, allowing layouts
|
|
162
|
+
* to decode their own values.
|
|
163
|
+
*/
|
|
164
|
+
readonly params?: Params;
|
|
165
|
+
}
|
|
166
|
+
/** an interior layout node. */
|
|
167
|
+
type LayoutNode<Children extends RouteChildren = RouteChildren, Params extends CodecRecord = Empty> = {
|
|
168
|
+
readonly kind: 'layout';
|
|
169
|
+
} & LayoutConfig<Children, Params>;
|
|
170
|
+
/** a layout or leaf route node. */
|
|
171
|
+
type RouteNode = LayoutNode | RouteLeaf;
|
|
172
|
+
/** a record of child nodes. */
|
|
173
|
+
interface RouteChildren {
|
|
174
|
+
readonly [name: string]: RouteNode;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* defines a navigable leaf route.
|
|
178
|
+
*
|
|
179
|
+
* @param config the route configuration
|
|
180
|
+
* @returns the route leaf node
|
|
181
|
+
*/
|
|
182
|
+
declare const route: <const Params extends CodecRecord = Empty, const Query extends CodecRecord = Empty>(config: RouteConfig<Params, Query>) => RouteLeaf<Params, Query>;
|
|
183
|
+
/**
|
|
184
|
+
* defines an interior layout node.
|
|
185
|
+
*
|
|
186
|
+
* @param config the layout configuration
|
|
187
|
+
* @returns the layout node
|
|
188
|
+
*/
|
|
189
|
+
declare const layout: <const Children extends RouteChildren, const Params extends CodecRecord = Empty>(config: LayoutConfig<Children, Params>) => LayoutNode<Children, Params>;
|
|
190
|
+
/** a node resolved with an id and normalized parameters. */
|
|
191
|
+
interface ResolvedNode {
|
|
192
|
+
/** unique dot-separated node path. */
|
|
193
|
+
readonly id: string;
|
|
194
|
+
/** key name within the parent record. */
|
|
195
|
+
readonly key: string;
|
|
196
|
+
readonly kind: 'layout' | 'route';
|
|
197
|
+
readonly node: RouteNode;
|
|
198
|
+
/** local parameter codecs. */
|
|
199
|
+
readonly params: CodecRecord;
|
|
200
|
+
/** absolute path pattern if a route. */
|
|
201
|
+
readonly path: string | undefined;
|
|
202
|
+
}
|
|
203
|
+
/** a leaf node resolved with its ancestors and metadata. */
|
|
204
|
+
interface ResolvedLeaf {
|
|
205
|
+
/** ancestors list from root to leaf. */
|
|
206
|
+
readonly chain: readonly ResolvedNode[];
|
|
207
|
+
readonly leaf: RouteLeaf;
|
|
208
|
+
/** unique route name. */
|
|
209
|
+
readonly name: string;
|
|
210
|
+
/** path parameter codecs. */
|
|
211
|
+
readonly params: CodecRecord;
|
|
212
|
+
/** absolute path pattern. */
|
|
213
|
+
readonly path: string;
|
|
214
|
+
/** query parameter codecs. */
|
|
215
|
+
readonly query: CodecRecord;
|
|
216
|
+
}
|
|
217
|
+
/** a compiled registry of routes and nodes. */
|
|
218
|
+
interface RouteRegistry<T> {
|
|
219
|
+
/** resolved leaves in matching order. */
|
|
220
|
+
readonly leaves: ReadonlyMap<string, ResolvedLeaf>;
|
|
221
|
+
readonly tree: T;
|
|
222
|
+
}
|
|
223
|
+
type ValidRoutes<T> = { readonly [K in keyof T]: T[K] extends RouteNode ? T[K] : never; };
|
|
224
|
+
/**
|
|
225
|
+
* compiles a route tree, validating keys, paths, and parameter codecs.
|
|
226
|
+
*
|
|
227
|
+
* @param tree the route tree configuration
|
|
228
|
+
* @returns the compiled registry
|
|
229
|
+
* @throws when route definitions violate nesting, unique names, or codec constraints
|
|
230
|
+
*/
|
|
231
|
+
declare const defineRoutes: <const T>(tree: T & ValidRoutes<T>) => RouteRegistry<T>;
|
|
232
|
+
type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
|
|
233
|
+
type FlattenChildren<C> = UnionToIntersection<{ [K in keyof C]: C[K] extends {
|
|
234
|
+
readonly children: infer GC;
|
|
235
|
+
readonly kind: 'layout';
|
|
236
|
+
} ? FlattenChildren<GC> : C[K] extends {
|
|
237
|
+
readonly kind: 'route';
|
|
238
|
+
} ? { readonly [P in K]: C[K]; } : never; }[keyof C]>;
|
|
239
|
+
type LeavesMap<R> = R extends RouteRegistry<infer T> ? FlattenChildren<T> : never;
|
|
240
|
+
type Prettify<T> = { [K in keyof T]: T[K]; } & {};
|
|
241
|
+
type PathShape<P extends CodecRecord> = { -readonly [K in keyof P]: Infer<P[K]>; };
|
|
242
|
+
type LeafDecode<L> = L extends RouteLeaf<infer P, infer Q> ? Prettify<DecodeShape<Q> & PathShape<P>> : never;
|
|
243
|
+
type LeafBuild<L> = L extends RouteLeaf<infer P, infer Q> ? Prettify<BuildShape<Q> & PathShape<P>> : never;
|
|
244
|
+
type LeafQueryPatch<L> = L extends RouteLeaf<infer _P, infer Q> ? Prettify<{ readonly [P in keyof Q]?: Infer<Q[P]> | undefined; }> : never;
|
|
245
|
+
/** a union of all navigable route names. */
|
|
246
|
+
type RouteName<R> = keyof LeavesMap<R> & string;
|
|
247
|
+
/** the decoded parameter shape for a route name. */
|
|
248
|
+
type ParamsOf<R, K extends RouteName<R>> = LeafDecode<LeavesMap<R>[K]>;
|
|
249
|
+
/** the parameter shape required to build a URL or navigate to a route. */
|
|
250
|
+
type BuildParamsOf<R, K extends RouteName<R>> = LeafBuild<LeavesMap<R>[K]>;
|
|
251
|
+
/**
|
|
252
|
+
* the patch shape accepted by a route's query setter: every query codec, all optional, each value accepting
|
|
253
|
+
* `undefined` to delete the parameter. path parameters are excluded — they are not settable in place.
|
|
254
|
+
*/
|
|
255
|
+
type QueryPatchOf<R, K extends RouteName<R>> = LeafQueryPatch<LeavesMap<R>[K]>;
|
|
256
|
+
//#endregion
|
|
257
|
+
//#region src/match.d.ts
|
|
258
|
+
/** a node on a matched chain paired with its instance parameters. */
|
|
259
|
+
interface MatchedNode {
|
|
260
|
+
/** parameters used for instance keying. */
|
|
261
|
+
readonly params: Readonly<Record<string, unknown>>;
|
|
262
|
+
readonly node: ResolvedNode;
|
|
263
|
+
}
|
|
264
|
+
/** the result of matching a URL, containing the chain, leaf, name, and parameters. */
|
|
265
|
+
interface RouteMatch {
|
|
266
|
+
readonly chain: readonly MatchedNode[];
|
|
267
|
+
readonly leaf: ResolvedLeaf;
|
|
268
|
+
readonly name: string;
|
|
269
|
+
/** leaf parameters, combining path and query. */
|
|
270
|
+
readonly params: Readonly<Record<string, unknown>>;
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* looks up the nearest metadata value for a key on a matched chain, searching leaf-first.
|
|
274
|
+
*
|
|
275
|
+
* @param match the route match chain
|
|
276
|
+
* @param key the metadata key to resolve
|
|
277
|
+
* @returns the nearest metadata value, or undefined if none is found
|
|
278
|
+
*/
|
|
279
|
+
declare const resolveMeta: <K extends keyof RouteMeta>(match: RouteMatch, key: K) => RouteMeta[K] | undefined;
|
|
280
|
+
//#endregion
|
|
281
|
+
//#region src/history/navigation.d.ts
|
|
282
|
+
/** options for navigation-api history. */
|
|
283
|
+
interface NavigationHistoryOptions {
|
|
284
|
+
/**
|
|
285
|
+
* same-origin destinations the server owns, which the browser should load as a real page rather than the
|
|
286
|
+
* router rendering in-app — an OAuth entry point, a server-rendered admin area, a static file. without this
|
|
287
|
+
* every same-origin URL is handled in-app, since the browser offers to intercept a navigation whenever the
|
|
288
|
+
* origin matches, whatever the destination is.
|
|
289
|
+
*
|
|
290
|
+
* consulted for pushes and replaces only. a traversal is always handled: declining one loads nothing, it
|
|
291
|
+
* just moves the browser to an entry this document never rendered.
|
|
292
|
+
*
|
|
293
|
+
* @param url destination URL
|
|
294
|
+
* @returns true to leave the navigation to the browser
|
|
295
|
+
*/
|
|
296
|
+
readonly ignore?: (url: URL) => boolean;
|
|
297
|
+
/** window instance to bind to; defaults to global window. */
|
|
298
|
+
readonly window?: Window;
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* history implementation backed by the web navigation API.
|
|
302
|
+
*
|
|
303
|
+
* intercepting same-document navigations converts standard page loads into in-app renders. per-revision
|
|
304
|
+
* metadata and indices are managed natively by the browser.
|
|
305
|
+
*/
|
|
306
|
+
declare class NavigationHistory implements History {
|
|
307
|
+
#private;
|
|
308
|
+
constructor(options?: NavigationHistoryOptions);
|
|
309
|
+
get location(): HistoryLocation;
|
|
310
|
+
get canGoBack(): boolean;
|
|
311
|
+
get canGoForward(): boolean;
|
|
312
|
+
entries(): readonly HistoryEntry[];
|
|
313
|
+
push(to: string, options?: HistoryNavigateOptions): void;
|
|
314
|
+
replace(to: string, options?: HistoryNavigateOptions): void;
|
|
315
|
+
traverseTo(key: string): void;
|
|
316
|
+
go(delta: number): void;
|
|
317
|
+
back(): void;
|
|
318
|
+
forward(): void;
|
|
319
|
+
listen(listener: HistoryListener): () => void;
|
|
320
|
+
dispose(): void;
|
|
321
|
+
}
|
|
322
|
+
//#endregion
|
|
323
|
+
//#region src/view-model.d.ts
|
|
324
|
+
/** an instance node within the layout tree structure. */
|
|
325
|
+
interface InstanceNode {
|
|
326
|
+
readonly children: InstanceNode[];
|
|
327
|
+
readonly instanceKey: string;
|
|
328
|
+
readonly node: ResolvedNode;
|
|
329
|
+
readonly params: Readonly<Record<string, unknown>>;
|
|
330
|
+
}
|
|
331
|
+
/** the computed rendering view configuration. */
|
|
332
|
+
interface View {
|
|
333
|
+
/** instance keys along the active chain from root to leaf. */
|
|
334
|
+
readonly activePath: readonly string[];
|
|
335
|
+
/** the top-level pool (instances at the root outlet). */
|
|
336
|
+
readonly roots: readonly InstanceNode[];
|
|
337
|
+
}
|
|
338
|
+
//#endregion
|
|
339
|
+
//#region src/build.d.ts
|
|
340
|
+
type BuildArgs<R, K extends RouteName<R>> = Record<never, never> extends BuildParamsOf<R, K> ? [params?: BuildParamsOf<R, K>] : [params: BuildParamsOf<R, K>];
|
|
341
|
+
//#endregion
|
|
342
|
+
//#region src/router.d.ts
|
|
343
|
+
/** options for the router constructor. */
|
|
344
|
+
interface RouterOptions<R extends RouteRegistry<unknown>> {
|
|
345
|
+
/** default fallback component shown during lazy chunk loading. */
|
|
346
|
+
readonly defaultFallback?: ReactNode;
|
|
347
|
+
/** backing history instance. */
|
|
348
|
+
readonly history: History;
|
|
349
|
+
/** maximum number of backward entries to keep warm. */
|
|
350
|
+
readonly max?: number;
|
|
351
|
+
/** component rendered when no route matches. */
|
|
352
|
+
readonly notFound?: ComponentType;
|
|
353
|
+
/** route names of pathless singleton routes to keep warm for the router's lifetime once first visited. */
|
|
354
|
+
readonly pins?: readonly string[];
|
|
355
|
+
/** compiled route registry. */
|
|
356
|
+
readonly routes: R;
|
|
357
|
+
}
|
|
358
|
+
/**
|
|
359
|
+
* manages navigation state, history subscriptions, and active views.
|
|
360
|
+
*
|
|
361
|
+
* this class acts as the store for the React router view, maintaining and caching active matched nodes and
|
|
362
|
+
* coordinates scrolling and focus.
|
|
363
|
+
*/
|
|
364
|
+
declare class Router<R extends RouteRegistry<unknown>> {
|
|
365
|
+
#private;
|
|
366
|
+
constructor(options: RouterOptions<R>);
|
|
367
|
+
/** current view structure. */
|
|
368
|
+
get view(): View;
|
|
369
|
+
/** active history location. */
|
|
370
|
+
get location(): HistoryLocation;
|
|
371
|
+
/** active route match details. */
|
|
372
|
+
get route(): RouteMatch;
|
|
373
|
+
/** whether backward history is available. */
|
|
374
|
+
get canGoBack(): boolean;
|
|
375
|
+
/** whether forward history is available. */
|
|
376
|
+
get canGoForward(): boolean;
|
|
377
|
+
/** default suspense fallback component. */
|
|
378
|
+
get defaultFallback(): ReactNode;
|
|
379
|
+
/** the compiled registry this router was constructed with. */
|
|
380
|
+
get routes(): R;
|
|
381
|
+
/**
|
|
382
|
+
* subscribes to view updates.
|
|
383
|
+
*
|
|
384
|
+
* bound to the instance, so it keeps one identity for the router's lifetime and can be handed straight to
|
|
385
|
+
* `useSyncExternalStore` — which re-subscribes whenever the function it is given changes.
|
|
386
|
+
*
|
|
387
|
+
* @param listener change callback
|
|
388
|
+
* @returns unsubscribe function
|
|
389
|
+
*/
|
|
390
|
+
readonly subscribe: (listener: () => void) => (() => void);
|
|
391
|
+
/** pushes a new location onto the history stack. */
|
|
392
|
+
push(to: string): void;
|
|
393
|
+
/** replaces the current location on the history stack. */
|
|
394
|
+
replace(to: string): void;
|
|
395
|
+
/**
|
|
396
|
+
* generates a URL for a route.
|
|
397
|
+
*
|
|
398
|
+
* @param name route name
|
|
399
|
+
* @param args route parameters
|
|
400
|
+
* @returns relative URL
|
|
401
|
+
*/
|
|
402
|
+
build<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): string;
|
|
403
|
+
/**
|
|
404
|
+
* navigates to a route.
|
|
405
|
+
*
|
|
406
|
+
* @param name route name
|
|
407
|
+
* @param args route parameters
|
|
408
|
+
*/
|
|
409
|
+
navigate<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): void;
|
|
410
|
+
/**
|
|
411
|
+
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
412
|
+
*
|
|
413
|
+
* @param name route name
|
|
414
|
+
* @param args route parameters
|
|
415
|
+
*/
|
|
416
|
+
popTo<K extends RouteName<R>>(name: K, ...args: BuildArgs<R, K>): void;
|
|
417
|
+
/**
|
|
418
|
+
* updates query parameters in-place without pushing a new entry.
|
|
419
|
+
*
|
|
420
|
+
* @param patch query parameter changes
|
|
421
|
+
*/
|
|
422
|
+
setParams(patch: Readonly<Record<string, unknown>>): void;
|
|
423
|
+
/** navigates back one entry. */
|
|
424
|
+
back(): void;
|
|
425
|
+
/** navigates forward one entry. */
|
|
426
|
+
forward(): void;
|
|
427
|
+
/** navigates by a delta offset on the stack. */
|
|
428
|
+
go(delta: number): void;
|
|
429
|
+
/**
|
|
430
|
+
* attaches a router view to coordinate transition commits.
|
|
431
|
+
*
|
|
432
|
+
* @returns detach function
|
|
433
|
+
*/
|
|
434
|
+
attachView(): () => void;
|
|
435
|
+
/** resolves pending navigation transitions after a view commits. */
|
|
436
|
+
notifyCommit(): void;
|
|
437
|
+
/** detaches history listeners and disposes resources. */
|
|
438
|
+
dispose(): void;
|
|
439
|
+
}
|
|
440
|
+
//#endregion
|
|
441
|
+
//#region src/react/router-view.d.ts
|
|
442
|
+
/**
|
|
443
|
+
* renders the current view tree of the router.
|
|
444
|
+
*
|
|
445
|
+
* off-chain branches stay mounted with their state intact, hidden with `display: none` rather than unmounted,
|
|
446
|
+
* so a back-traversal returns to the instance you left. their effects keep running; a branch that wants to
|
|
447
|
+
* pause background work while stacked can gate it on `useIsFocused`.
|
|
448
|
+
*
|
|
449
|
+
* @param props.router router instance
|
|
450
|
+
* @returns rendered component tree
|
|
451
|
+
*/
|
|
452
|
+
declare const RouterView: <R extends RouteRegistry<unknown>>({ router }: {
|
|
453
|
+
readonly router: Router<R>;
|
|
454
|
+
}) => ReactElement;
|
|
455
|
+
//#endregion
|
|
456
|
+
//#region src/react/outlet.d.ts
|
|
457
|
+
/**
|
|
458
|
+
* renders the child branch pool within a layout component.
|
|
459
|
+
*
|
|
460
|
+
* @returns rendered outlet child pool or null if outside a layout
|
|
461
|
+
*/
|
|
462
|
+
declare const Outlet: () => ReactElement | null;
|
|
463
|
+
//#endregion
|
|
464
|
+
//#region src/react/hooks.d.ts
|
|
465
|
+
/**
|
|
466
|
+
* gets the active router instance.
|
|
467
|
+
*
|
|
468
|
+
* @returns router instance
|
|
469
|
+
* @throws when used outside a router view context
|
|
470
|
+
*/
|
|
471
|
+
declare const useRouter: () => Router<RouteRegistry<unknown>>;
|
|
472
|
+
/**
|
|
473
|
+
* gets the active history location.
|
|
474
|
+
*
|
|
475
|
+
* @returns history location
|
|
476
|
+
*/
|
|
477
|
+
declare const useLocation: () => HistoryLocation;
|
|
478
|
+
/**
|
|
479
|
+
* gets the active route match information.
|
|
480
|
+
*
|
|
481
|
+
* @returns active route match
|
|
482
|
+
*/
|
|
483
|
+
declare const useRoute: () => RouteMatch;
|
|
484
|
+
/**
|
|
485
|
+
* gets the untyped parameter map of the nearest enclosing route node.
|
|
486
|
+
*
|
|
487
|
+
* @returns decoded parameters
|
|
488
|
+
* @throws when used outside a route tree context
|
|
489
|
+
*/
|
|
490
|
+
declare const useParams: () => Readonly<Record<string, unknown>>;
|
|
491
|
+
/**
|
|
492
|
+
* gets whether the enclosing branch is focused (on screen).
|
|
493
|
+
*
|
|
494
|
+
* @returns true if focused
|
|
495
|
+
*/
|
|
496
|
+
declare const useIsFocused: () => boolean;
|
|
497
|
+
/**
|
|
498
|
+
* runs an effect callback only while the branch is focused.
|
|
499
|
+
*
|
|
500
|
+
* the effect re-runs whenever its identity changes, the way `useEffect` does, so wrap it in `useCallback` to
|
|
501
|
+
* control when that happens. an effect built fresh on every render re-runs on every render.
|
|
502
|
+
*
|
|
503
|
+
* @param effect effect callback
|
|
504
|
+
*/
|
|
505
|
+
declare const useFocusEffect: (effect: EffectCallback) => void;
|
|
506
|
+
/** typed hooks bound to a specific route registry. */
|
|
507
|
+
interface RouterHooks<R extends RouteRegistry<unknown>> {
|
|
508
|
+
/** returns a function to build URLs. */
|
|
509
|
+
useBuild(): Router<R>['build'];
|
|
510
|
+
/** gets the current location. */
|
|
511
|
+
useLocation(): HistoryLocation;
|
|
512
|
+
/** returns a function to navigate to routes. */
|
|
513
|
+
useNavigate(): Router<R>['navigate'];
|
|
514
|
+
/** gets a route's parameters and a setter that patches its query in place. */
|
|
515
|
+
useParams<K extends RouteName<R>>(name: K): readonly [ParamsOf<R, K>, (patch: QueryPatchOf<R, K>) => void];
|
|
516
|
+
/** gets the active route match. */
|
|
517
|
+
useRoute(): RouteMatch;
|
|
518
|
+
/** gets the typed router instance. */
|
|
519
|
+
useRouter(): Router<R>;
|
|
520
|
+
}
|
|
521
|
+
/**
|
|
522
|
+
* generates typed hooks bound to a specific route registry.
|
|
523
|
+
*
|
|
524
|
+
* @param routes the compiled registry the hooks are typed against
|
|
525
|
+
* @returns typed hooks record
|
|
526
|
+
* @throws when used with a router built from a different registry
|
|
527
|
+
*/
|
|
528
|
+
declare const createRouterHooks: <R extends RouteRegistry<unknown>>(routes: R) => RouterHooks<R>;
|
|
529
|
+
//#endregion
|
|
530
|
+
//#region src/react/link.d.ts
|
|
531
|
+
/** properties for the link component. */
|
|
532
|
+
interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
|
|
533
|
+
/** replace the current history entry. */
|
|
534
|
+
readonly replace?: boolean;
|
|
535
|
+
/** target relative URL path. */
|
|
536
|
+
readonly to: string;
|
|
537
|
+
}
|
|
538
|
+
/**
|
|
539
|
+
* anchor element that intercepts clicks for in-app navigation.
|
|
540
|
+
*
|
|
541
|
+
* a destination on another origin, or under a scheme like `mailto:`, is left to the browser.
|
|
542
|
+
*
|
|
543
|
+
* @param props link properties
|
|
544
|
+
* @returns rendered anchor element
|
|
545
|
+
*/
|
|
546
|
+
declare const Link: ({ children, onClick, replace, to, ...rest }: LinkProps) => ReactElement;
|
|
547
|
+
//#endregion
|
|
548
|
+
export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LeafType, Link, type LinkProps, type MatchedNode, NavigationHistory, type NavigationHistoryOptions, type OptionalCodec, Outlet, type ParamsOf, type QueryPatchOf, type ReadonlyURLSearchParams, type ResolvedLeaf, type ResolvedNode, type RouteChildren, type RouteConfig, type RouteLeaf, type RouteMatch, type RouteMeta, type RouteName, type RouteNode, type RouteRegistry, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
|