@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/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
@@ -0,0 +1,6 @@
1
+ import { getLogger } from '@logtape/logtape'
2
+
3
+ // Silent by default: the app configures LogTape sinks and levels
4
+ // (category ["xzsv", "router"]). The library never calls configure itself.
5
+ export const log = getLogger(['xzsv', 'router'])
6
+ export { getLogger }
@@ -0,0 +1,6 @@
1
+ export interface RouteNodeCtx {
2
+ depth: number
3
+ key: number
4
+ }
5
+
6
+ export const routeNodeKey = Symbol('xzsv-route-node')
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
+ }