@xzsv/router 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +110 -2
- package/package.json +30 -4
- package/src/Link.svelte +62 -0
- package/src/Recursive.svelte +87 -0
- package/src/RouteNode.svelte +19 -0
- package/src/Router.svelte +57 -0
- package/src/create.svelte.ts +694 -0
- package/src/env.d.ts +3 -0
- package/src/index.ts +47 -0
- package/src/log.ts +6 -0
- package/src/route-node-context.ts +6 -0
- package/src/types.ts +351 -0
- package/src/utils.ts +545 -0
package/src/index.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module: @xzsv/router
|
|
3
|
+
*
|
|
4
|
+
* A lightweight, client-side router for Svelte 5 with support for:
|
|
5
|
+
* - Nested routes and layouts
|
|
6
|
+
* - Dynamic parameters and wildcards
|
|
7
|
+
* - Lazy loading
|
|
8
|
+
* - Navigation hooks
|
|
9
|
+
* - Dual-tree rendering for smooth transitions
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
// Core router
|
|
13
|
+
export {
|
|
14
|
+
createRouter,
|
|
15
|
+
isActiveLink,
|
|
16
|
+
phase,
|
|
17
|
+
preloadRoute,
|
|
18
|
+
routeNode,
|
|
19
|
+
searchParamsProxy as searchParams,
|
|
20
|
+
} from './create.svelte.ts'
|
|
21
|
+
export { default as Link } from './Link.svelte'
|
|
22
|
+
export { log } from './log.ts'
|
|
23
|
+
export { default as Router } from './Router.svelte'
|
|
24
|
+
export { q } from './utils.ts'
|
|
25
|
+
|
|
26
|
+
// Types
|
|
27
|
+
export type {
|
|
28
|
+
AllParams,
|
|
29
|
+
ComponentTree,
|
|
30
|
+
ComponentTreeNode,
|
|
31
|
+
Hooks,
|
|
32
|
+
LayoutComponent,
|
|
33
|
+
LazyRouteComponent,
|
|
34
|
+
LinkProps,
|
|
35
|
+
Location,
|
|
36
|
+
NavigateOptions,
|
|
37
|
+
Path,
|
|
38
|
+
PathParams,
|
|
39
|
+
Phase,
|
|
40
|
+
QueryValue,
|
|
41
|
+
RouteComponent,
|
|
42
|
+
RouteNodeInfo,
|
|
43
|
+
RouterApi,
|
|
44
|
+
Routes,
|
|
45
|
+
TransitionFn,
|
|
46
|
+
Transitions,
|
|
47
|
+
} from './types'
|
package/src/log.ts
ADDED
package/src/types.ts
ADDED
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
import type { Component, Snippet } from 'svelte'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Base props for route components
|
|
5
|
+
*/
|
|
6
|
+
export type BaseProps = {}
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Lazy-loaded route component
|
|
10
|
+
*/
|
|
11
|
+
export type LazyRouteComponent<Props extends BaseProps = BaseProps> = () => Promise<{
|
|
12
|
+
[key: string]: Component<Props>
|
|
13
|
+
}>
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Route component can be either a regular component or a lazy-loaded one
|
|
17
|
+
*/
|
|
18
|
+
export type RouteComponent<Props extends BaseProps = any> =
|
|
19
|
+
| Component<Props>
|
|
20
|
+
| LazyRouteComponent<Props>
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Contextual info passed to transition callbacks per route node.
|
|
24
|
+
*/
|
|
25
|
+
export type RouteNodeInfo = {
|
|
26
|
+
depth: number
|
|
27
|
+
key: number
|
|
28
|
+
from: string
|
|
29
|
+
to: string
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Per-element transition callback. Return a promise to hold the
|
|
34
|
+
* dual-tree swap until the animation settles (or the timeout fires).
|
|
35
|
+
*/
|
|
36
|
+
export type TransitionFn = (
|
|
37
|
+
el: HTMLElement,
|
|
38
|
+
info: RouteNodeInfo,
|
|
39
|
+
) => void | Promise<void>
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Router-orchestrated transitions: enter/leave fire per route-node
|
|
43
|
+
* element (pages/layout roots carrying the `routeNode` attachment),
|
|
44
|
+
* only for nodes past the equality point — persistent layouts never
|
|
45
|
+
* animate. `timeoutMs` bounds how long the router waits for returned
|
|
46
|
+
* promises before finalizing anyway (default 1000).
|
|
47
|
+
*/
|
|
48
|
+
export type Transitions = {
|
|
49
|
+
enter?: TransitionFn
|
|
50
|
+
leave?: TransitionFn
|
|
51
|
+
timeoutMs?: number
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Layout component includes children snippet
|
|
56
|
+
*/
|
|
57
|
+
export type LayoutComponent =
|
|
58
|
+
| RouteComponent<{ children: Snippet }>
|
|
59
|
+
| [RouteComponent, { submodule?: string }]
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Component tree structure for dual-tree rendering
|
|
63
|
+
*/
|
|
64
|
+
export type ComponentTree = {
|
|
65
|
+
value: {
|
|
66
|
+
a: ComponentTreeNode[]
|
|
67
|
+
b: ComponentTreeNode[]
|
|
68
|
+
eq: number
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export type ComponentTreeNode = {
|
|
73
|
+
C: Component<any>
|
|
74
|
+
key: number
|
|
75
|
+
params?: Record<string, string>
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Lifecycle hooks for route navigation
|
|
80
|
+
*/
|
|
81
|
+
export type Hooks = {
|
|
82
|
+
/**
|
|
83
|
+
* Called before loading the route components.
|
|
84
|
+
* Can throw to cancel navigation.
|
|
85
|
+
*/
|
|
86
|
+
beforeLoad?(args: {
|
|
87
|
+
from: string
|
|
88
|
+
to: string
|
|
89
|
+
cycle: Cycle
|
|
90
|
+
match?: RouteComponent
|
|
91
|
+
params: Record<string, string>
|
|
92
|
+
signal?: AbortSignal
|
|
93
|
+
}): void | Promise<void>
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Called after components are resolved but before rendering.
|
|
97
|
+
* Useful for loading data or assets.
|
|
98
|
+
*/
|
|
99
|
+
duringLoad?(args: {
|
|
100
|
+
from: string
|
|
101
|
+
to: string
|
|
102
|
+
cycle: Cycle
|
|
103
|
+
componentTree: ComponentTree['value']
|
|
104
|
+
mountedComponents: Record<string, any>
|
|
105
|
+
keys: { in: string[]; out: string[] }
|
|
106
|
+
signal?: AbortSignal
|
|
107
|
+
}): void | Promise<void>
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Called during the rendering phase.
|
|
111
|
+
* Used for transitions and animations.
|
|
112
|
+
*/
|
|
113
|
+
duringRender?(args: {
|
|
114
|
+
from: string
|
|
115
|
+
to: string
|
|
116
|
+
cycle: Cycle
|
|
117
|
+
componentTree: ComponentTree['value']
|
|
118
|
+
mountedComponents: Record<string, any>
|
|
119
|
+
keys: { in: string[]; out: string[] }
|
|
120
|
+
signal?: AbortSignal
|
|
121
|
+
}): void | Promise<void>
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Called after rendering is complete.
|
|
125
|
+
*/
|
|
126
|
+
afterRender?(args: {
|
|
127
|
+
from: string
|
|
128
|
+
to: string
|
|
129
|
+
cycle: Cycle
|
|
130
|
+
componentTree: ComponentTree['value']
|
|
131
|
+
mountedComponents: Record<string, any>
|
|
132
|
+
keys: { in: string[]; out: string[] }
|
|
133
|
+
signal?: AbortSignal
|
|
134
|
+
}): void
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Tree cycle
|
|
139
|
+
*/
|
|
140
|
+
export type Cycle = {
|
|
141
|
+
value: 'a' | 'ba' | 'b' | 'ab'
|
|
142
|
+
from: 'a' | 'b'
|
|
143
|
+
readonly to: 'a' | 'b'
|
|
144
|
+
readonly first: 'a' | 'b'
|
|
145
|
+
readonly second: 'a' | 'b' | undefined
|
|
146
|
+
readonly chars: ReadonlyArray<('a' | 'b')>
|
|
147
|
+
readonly isSingle: boolean
|
|
148
|
+
readonly isDual: boolean
|
|
149
|
+
readonly filled: 'ab' | 'ba'
|
|
150
|
+
fill(): void
|
|
151
|
+
finalize(): void
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Route definition structure
|
|
156
|
+
*/
|
|
157
|
+
export type Routes = {
|
|
158
|
+
[_: `/${string}`]:
|
|
159
|
+
| RouteComponent
|
|
160
|
+
| [RouteComponent, { submodule?: string; params?: string[] }]
|
|
161
|
+
| Routes
|
|
162
|
+
[_: `*${string}` | `(*${string})`]:
|
|
163
|
+
| RouteComponent
|
|
164
|
+
| [RouteComponent, { submodule?: string; params?: string[] }]
|
|
165
|
+
| undefined
|
|
166
|
+
layout?: LayoutComponent
|
|
167
|
+
hooks?: Hooks
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* Navigation options
|
|
172
|
+
*/
|
|
173
|
+
export type NavigateOptions = {
|
|
174
|
+
hash?: string
|
|
175
|
+
replace?: boolean
|
|
176
|
+
scrollToTop?: ScrollBehavior | false
|
|
177
|
+
search?: string
|
|
178
|
+
state?: string
|
|
179
|
+
bypass?: boolean
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Query parameter values accepted by `q()` and `<Link search={...}>`.
|
|
184
|
+
* Falsy-absent values (`undefined`/`null`/`''`) are skipped.
|
|
185
|
+
*/
|
|
186
|
+
export type QueryValue = string | number | boolean | undefined | null
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Props for the `<Link>` component. Only `to` and `children` are required;
|
|
190
|
+
* everything else mirrors `navigate()` options, which Link forwards via
|
|
191
|
+
* the router's global click interception (`data-*` attributes).
|
|
192
|
+
*/
|
|
193
|
+
export type LinkProps = {
|
|
194
|
+
/** Target path — build dynamic ones with `p()`. */
|
|
195
|
+
to: string
|
|
196
|
+
/** Params for `to`'s dynamic segments; used for active matching. */
|
|
197
|
+
params?: Record<string, string>
|
|
198
|
+
/** Query string: a ready-made string or an object encoded via `q()`. */
|
|
199
|
+
search?: string | Record<string, QueryValue>
|
|
200
|
+
hash?: string
|
|
201
|
+
replace?: boolean
|
|
202
|
+
scrollToTop?: ScrollBehavior | false
|
|
203
|
+
/** Prefix-match for active state (section nav inside a page tree). */
|
|
204
|
+
startsWith?: boolean
|
|
205
|
+
/** Class applied when the link is active. */
|
|
206
|
+
activeClass?: string
|
|
207
|
+
/** Class applied when the link is inactive. */
|
|
208
|
+
inactiveClass?: string
|
|
209
|
+
/** Emit `data-preload` for hover prefetch. Default `true`. */
|
|
210
|
+
preload?: boolean
|
|
211
|
+
class?: string
|
|
212
|
+
children: Snippet
|
|
213
|
+
[key: string]: unknown
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Location information
|
|
218
|
+
*/
|
|
219
|
+
export type Location = {
|
|
220
|
+
pathname: string
|
|
221
|
+
search: string
|
|
222
|
+
state: any
|
|
223
|
+
hash: string
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Router phase states
|
|
228
|
+
*/
|
|
229
|
+
export type Phase =
|
|
230
|
+
| 'idle'
|
|
231
|
+
| 'beforeLoad'
|
|
232
|
+
| 'duringLoad'
|
|
233
|
+
| 'duringRender'
|
|
234
|
+
| 'afterRender'
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Type utilities for extracting route paths and params
|
|
238
|
+
*/
|
|
239
|
+
type StripNonRoutes<T extends Routes> = {
|
|
240
|
+
[
|
|
241
|
+
K in keyof T as K extends `*${string}` ? never
|
|
242
|
+
: K extends `(*${string})` ? never
|
|
243
|
+
: K extends 'layout' ? never
|
|
244
|
+
: K extends 'hooks' ? never
|
|
245
|
+
: K
|
|
246
|
+
]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K]
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
type RecursiveKeys<T extends Routes, Prefix extends string = ''> = {
|
|
250
|
+
[K in keyof T]: K extends string ? T[K] extends Routes ? RecursiveKeys<T[K], `${Prefix}${K}`>
|
|
251
|
+
: `${Prefix}${K}`
|
|
252
|
+
: never
|
|
253
|
+
}[keyof T]
|
|
254
|
+
|
|
255
|
+
type RemoveLastSlash<T extends string> = T extends '/' ? T
|
|
256
|
+
: T extends `${infer R}/` ? R
|
|
257
|
+
: T
|
|
258
|
+
|
|
259
|
+
type RemoveParenthesis<T extends string> = T extends `${infer A}(${infer B})${infer C}`
|
|
260
|
+
? RemoveParenthesis<`${A}${B}${C}`>
|
|
261
|
+
: T
|
|
262
|
+
|
|
263
|
+
export type Path<T extends Routes> = RemoveParenthesis<
|
|
264
|
+
RemoveLastSlash<RecursiveKeys<StripNonRoutes<T>>>
|
|
265
|
+
>
|
|
266
|
+
|
|
267
|
+
type ExtractParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
|
|
268
|
+
? Param | ExtractParams<`/${Rest}`>
|
|
269
|
+
: T extends `${string}(:${infer Param})` ? Param
|
|
270
|
+
: T extends `${string}:${infer Param}` ? Param
|
|
271
|
+
: T extends `${string}(*${infer Param})` ? Param
|
|
272
|
+
: T extends `${string}*${infer Param}` ? Param extends '' ? never
|
|
273
|
+
: Param
|
|
274
|
+
: never
|
|
275
|
+
|
|
276
|
+
export type PathParams<T extends string> = ExtractParams<T> extends never ? never : Record<ExtractParams<T>, string>
|
|
277
|
+
|
|
278
|
+
// export type ConstructPathArgs<T extends string> = PathParams<T> extends never ? [T] : [T, PathParams<T>]
|
|
279
|
+
|
|
280
|
+
type NavigateArgs<T extends string> =
|
|
281
|
+
| (PathParams<T> extends never ? [T] | [T, NavigateOptions]
|
|
282
|
+
: [T, NavigateOptions & { params: PathParams<T> }])
|
|
283
|
+
| [number]
|
|
284
|
+
|
|
285
|
+
export type IsActiveArgs<T extends string> = PathParams<T> extends never ? [T] : [T] | [T, PathParams<T>]
|
|
286
|
+
|
|
287
|
+
export type AllParams<T extends Routes> = Partial<
|
|
288
|
+
Record<ExtractParams<RecursiveKeys<T>>, string>
|
|
289
|
+
>
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Main router API
|
|
293
|
+
*/
|
|
294
|
+
export type RouterApi<T extends Routes> = {
|
|
295
|
+
/**
|
|
296
|
+
* Construct a path with type safety
|
|
297
|
+
*/
|
|
298
|
+
p(path: string, params?: Record<string, string>): string
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Navigate to a route
|
|
302
|
+
*/
|
|
303
|
+
navigate<U extends Path<T>>(...args: NavigateArgs<U>): void
|
|
304
|
+
/**
|
|
305
|
+
* Dynamic/constructed paths (e.g. results of `p()` or built strings):
|
|
306
|
+
* no literal checking, params must already be substituted.
|
|
307
|
+
*/
|
|
308
|
+
navigate(path: string, options?: NavigateOptions): void
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* Warm a route's lazy components programmatically — what hover-preload
|
|
312
|
+
* does, callable from pointerdown handlers, idle callbacks, or boot
|
|
313
|
+
* sequences. Deduped per path; resolves when components are loaded.
|
|
314
|
+
*/
|
|
315
|
+
preload(path: string): Promise<void>
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Check if a path is active
|
|
319
|
+
*/
|
|
320
|
+
isActive: {
|
|
321
|
+
<U extends Path<T>>(...args: IsActiveArgs<U>): boolean
|
|
322
|
+
startsWith<U extends Path<T>>(...args: IsActiveArgs<U>): boolean
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Current route information
|
|
327
|
+
*/
|
|
328
|
+
route: {
|
|
329
|
+
params: AllParams<T>
|
|
330
|
+
pathname: Path<T>
|
|
331
|
+
search: string
|
|
332
|
+
state: unknown
|
|
333
|
+
hash: string
|
|
334
|
+
phase: Phase
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* Current navigation phase
|
|
339
|
+
*/
|
|
340
|
+
phase: { value: Phase }
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Component tree (for advanced use cases)
|
|
344
|
+
*/
|
|
345
|
+
C: ComponentTree
|
|
346
|
+
|
|
347
|
+
/**
|
|
348
|
+
* Mounted components (for advanced use cases)
|
|
349
|
+
*/
|
|
350
|
+
MC: Record<string, any>
|
|
351
|
+
}
|