@oomfware/stacker 0.2.2 → 0.2.4

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
@@ -38,17 +38,17 @@ const routes = defineRoutes({
38
38
  app: layout({
39
39
  component: AppShell,
40
40
  children: {
41
- Home: route({ component: Home, path: '/' }),
41
+ Home: route({ path: '/', component: Home }),
42
42
  Profile: route({
43
- component: Profile,
44
- params: { actor: string() },
45
43
  path: '/profile/:actor',
44
+ params: { actor: string() },
45
+ component: Profile,
46
46
  }),
47
47
  },
48
48
  }),
49
49
  });
50
50
 
51
- const router = new Router({ history: new NavigationHistory(), routes });
51
+ const router = new Router({ routes, history: new NavigationHistory() });
52
52
 
53
53
  export const App = () => <RouterView router={router} />;
54
54
  ```
@@ -65,14 +65,14 @@ const routes = defineRoutes({
65
65
  app: layout({
66
66
  component: AppShell,
67
67
  children: {
68
- Home: route({ component: Home, path: '/' }),
68
+ Home: route({ path: '/', component: Home }),
69
69
  Profile: route({
70
- component: Profile,
70
+ path: '/profile/:actor',
71
71
  params: { actor: string() },
72
72
  query: { tab: optional(string()) },
73
- path: '/profile/:actor',
73
+ component: Profile,
74
74
  }),
75
- Settings: route({ component: Settings, path: '/settings' }),
75
+ Settings: route({ path: '/settings', component: Settings }),
76
76
  },
77
77
  }),
78
78
  });
@@ -85,10 +85,10 @@ configure `type` to control page instance lifetimes:
85
85
 
86
86
  ```ts
87
87
  // page (default): new instance and state per history entry
88
- route({ component: Profile, path: '/profile/:actor', type: 'page' });
88
+ route({ path: '/profile/:actor', type: 'page', component: Profile });
89
89
 
90
90
  // singleton: one instance per distinct parameter set
91
- route({ component: Home, path: '/', type: 'singleton' });
91
+ route({ path: '/', type: 'singleton', component: Home });
92
92
  ```
93
93
 
94
94
  ### parameters
@@ -99,7 +99,6 @@ declare path and query parameters using codecs. types are inferred automatically
99
99
  import { boolean, enumOf, integer, optional, route, string, withDefault } from '@oomfware/stacker';
100
100
 
101
101
  route({
102
- component: SearchPage,
103
102
  path: '/search/:tag',
104
103
  params: { tag: string() },
105
104
  query: {
@@ -107,6 +106,7 @@ route({
107
106
  sort: withDefault(enumOf(['new', 'top']), 'new'),
108
107
  unread: optional(boolean()),
109
108
  },
109
+ component: SearchPage,
110
110
  });
111
111
  ```
112
112
 
@@ -117,7 +117,7 @@ end a path with `*name` to capture the rest of the URL, separators included. a s
117
117
  its bare parent path, where the remainder is empty:
118
118
 
119
119
  ```ts
120
- route({ component: Docs, params: { rest: string() }, path: '/docs/*rest' });
120
+ route({ path: '/docs/*rest', params: { rest: string() }, component: Docs });
121
121
 
122
122
  // /docs/guide/intro -> { rest: 'guide/intro' }
123
123
  // /docs -> { rest: '' }
@@ -186,6 +186,14 @@ router.replace('Profile', { tab: undefined }); // -> /profile/alice
186
186
  unmentioned params keep their values, undeclared keys are ignored, and naming a route other than the
187
187
  one on screen throws.
188
188
 
189
+ `router.updateState` rewrites the active entry's state without navigating at all, useful for the
190
+ things a URL should not carry, like a draft or a scroll anchor:
191
+
192
+ ```ts
193
+ router.updateState({ draft: 'hello' });
194
+ router.updateState({ ...(router.location.state as State), draft: '' });
195
+ ```
196
+
189
197
  a route target is a discriminated union, so narrowing on `name` narrows the params with it:
190
198
 
191
199
  ```ts
@@ -223,7 +231,7 @@ generate type-safe hooks bound to your route configuration using `createRouterHo
223
231
  ```tsx
224
232
  import { createRouterHooks } from '@oomfware/stacker';
225
233
 
226
- const { useParams, useRouter } = createRouterHooks(routes);
234
+ const { useRouter, useParams } = createRouterHooks(routes);
227
235
 
228
236
  const Profile = () => {
229
237
  const [{ actor }, replace] = useParams('Profile');
@@ -365,9 +373,9 @@ parameters:
365
373
 
366
374
  ```ts
367
375
  route({
368
- component: Beta,
369
376
  path: '/feed',
370
377
  when: ({ rawSearch }) => rawSearch.has('beta'),
378
+ component: Beta,
371
379
  });
372
380
  ```
373
381
 
@@ -379,7 +387,7 @@ use `MemoryHistory` to test routing behavior in environments without a DOM:
379
387
  import { MemoryHistory } from '@oomfware/stacker/testing';
380
388
 
381
389
  const router = new Router({
382
- history: new MemoryHistory({ initialEntries: ['/', '/profile/alice'] }),
383
390
  routes,
391
+ history: new MemoryHistory({ initialEntries: ['/', '/profile/alice'] }),
384
392
  });
385
393
  ```
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { a as HistoryLocation, c as HistoryUpdate, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryScrollBehavior, t as History } from "./types-Bo4ESWAT.mjs";
1
+ import { a as HistoryLocation, c as HistoryUpdate, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryScrollBehavior, t as History } from "./types--iOZjfC1.mjs";
2
2
  import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
3
3
  //#region src/codec.d.ts
4
4
  /**
@@ -128,28 +128,28 @@ interface RouteMeta {}
128
128
  type ReadonlyURLSearchParams = Omit<URLSearchParams, 'append' | 'delete' | 'set' | 'sort'>;
129
129
  /** context passed to a route `when` predicate. */
130
130
  interface WhenContext {
131
- readonly hash: string;
132
131
  readonly pathname: string;
133
- readonly rawSearch: ReadonlyURLSearchParams;
134
132
  readonly search: string;
133
+ readonly hash: string;
134
+ readonly rawSearch: ReadonlyURLSearchParams;
135
135
  }
136
136
  interface LeafShared<Params extends CodecRecord, Query extends CodecRecord> {
137
- /** component to render. */
138
- readonly component: ComponentType;
139
- /** suspense fallback component. */
140
- readonly fallback?: ReactNode;
141
- /** application metadata. */
142
- readonly meta?: RouteMeta;
143
- /** path parameter codecs. */
144
- readonly params?: Params;
145
137
  /** absolute URL path pattern. */
146
138
  readonly path: string;
139
+ /** path parameter codecs. */
140
+ readonly params?: Params;
147
141
  /** query parameter codecs. */
148
142
  readonly query?: Query;
149
- /** instance-keying strategy. */
150
- readonly type?: LeafType;
151
143
  /** dynamic predicate for route matching. */
152
144
  readonly when?: (ctx: WhenContext) => boolean;
145
+ /** instance-keying strategy. */
146
+ readonly type?: LeafType;
147
+ /** component to render. */
148
+ readonly component: ComponentType;
149
+ /** suspense fallback component. */
150
+ readonly fallback?: ReactNode;
151
+ /** application metadata. */
152
+ readonly meta?: RouteMeta;
153
153
  }
154
154
  /** configuration for a navigable leaf route. */
155
155
  type RouteConfig<Params extends CodecRecord, Query extends CodecRecord> = LeafShared<Params, Query>;
@@ -159,19 +159,19 @@ interface RouteLeaf<Params extends CodecRecord = Empty, Query extends CodecRecor
159
159
  }
160
160
  /** configuration for an interior layout node. */
161
161
  interface LayoutConfig<Children extends RouteChildren, Params extends CodecRecord> {
162
- /** nested child nodes. */
163
- readonly children: Children;
162
+ /**
163
+ * codecs for layout parameters. parameter names must appear in all descendant leaf paths, allowing layouts
164
+ * to decode their own values.
165
+ */
166
+ readonly params?: Params;
164
167
  /** layout component rendering an outlet. */
165
168
  readonly component: ComponentType;
166
169
  /** suspense fallback component. */
167
170
  readonly fallback?: ReactNode;
168
171
  /** application metadata. */
169
172
  readonly meta?: RouteMeta;
170
- /**
171
- * codecs for layout parameters. parameter names must appear in all descendant leaf paths, allowing layouts
172
- * to decode their own values.
173
- */
174
- readonly params?: Params;
173
+ /** nested child nodes. */
174
+ readonly children: Children;
175
175
  }
176
176
  /** an interior layout node. */
177
177
  type LayoutNode<Children extends RouteChildren = RouteChildren, Params extends CodecRecord = Empty> = {
@@ -204,25 +204,25 @@ interface ResolvedNode {
204
204
  readonly id: string;
205
205
  /** key name within the parent record. */
206
206
  readonly key: string;
207
- readonly node: RouteNode;
208
- /** local parameter codecs. */
209
- readonly params: CodecRecord;
210
207
  /** absolute path pattern if a route. */
211
208
  readonly path: string | undefined;
209
+ /** local parameter codecs. */
210
+ readonly params: CodecRecord;
211
+ readonly node: RouteNode;
212
212
  }
213
213
  /** a leaf node resolved with its ancestors and metadata. */
214
214
  interface ResolvedLeaf {
215
- /** ancestors list from root to leaf. */
216
- readonly chain: readonly ResolvedNode[];
217
- readonly leaf: RouteLeaf;
218
215
  /** unique route name. */
219
216
  readonly name: string;
220
- /** path parameter codecs. */
221
- readonly params: CodecRecord;
222
217
  /** absolute path pattern. */
223
218
  readonly path: string;
219
+ /** path parameter codecs. */
220
+ readonly params: CodecRecord;
224
221
  /** query parameter codecs. */
225
222
  readonly query: CodecRecord;
223
+ readonly leaf: RouteLeaf;
224
+ /** ancestors list from root to leaf. */
225
+ readonly chain: readonly ResolvedNode[];
226
226
  }
227
227
  /** a compiled registry of routes and nodes. */
228
228
  interface RouteRegistry<T> {
@@ -241,8 +241,8 @@ type ValidRoutes<T> = { readonly [K in keyof T]: T[K] extends RouteNode ? T[K] :
241
241
  declare const defineRoutes: <const T>(tree: T & ValidRoutes<T>) => RouteRegistry<T>;
242
242
  type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
243
243
  type FlattenChildren<C> = UnionToIntersection<{ [K in keyof C]: C[K] extends {
244
- readonly children: infer GC;
245
244
  readonly kind: 'layout';
245
+ readonly children: infer GC;
246
246
  } ? FlattenChildren<GC> : C[K] extends {
247
247
  readonly kind: 'route';
248
248
  } ? { readonly [P in K]: C[K]; } : never; }[keyof C]>;
@@ -291,11 +291,11 @@ interface MatchedNode {
291
291
  }
292
292
  /** the result of matching a URL, containing the chain, leaf, name, and parameters. */
293
293
  interface RouteMatch {
294
- readonly chain: readonly MatchedNode[];
295
- readonly leaf: ResolvedLeaf;
296
294
  readonly name: string;
297
295
  /** leaf parameters, combining path and query. */
298
296
  readonly params: Readonly<Record<string, unknown>>;
297
+ readonly leaf: ResolvedLeaf;
298
+ readonly chain: readonly MatchedNode[];
299
299
  }
300
300
  /**
301
301
  * looks up the nearest metadata value for a key on a matched chain, searching leaf-first.
@@ -309,6 +309,8 @@ declare const resolveMeta: <K extends keyof RouteMeta>(match: RouteMatch, key: K
309
309
  //#region src/history/navigation.d.ts
310
310
  /** options for navigation-api history. */
311
311
  interface NavigationHistoryOptions {
312
+ /** window instance to bind to; defaults to global window. */
313
+ readonly window?: Window;
312
314
  /**
313
315
  * same-origin destinations the server owns, which the browser should load as a real page rather than the
314
316
  * router rendering in-app — an OAuth entry point, a server-rendered admin area, a static file. without this
@@ -328,8 +330,6 @@ interface NavigationHistoryOptions {
328
330
  * @param error failure reason
329
331
  */
330
332
  readonly onError?: (error: unknown) => void;
331
- /** window instance to bind to; defaults to global window. */
332
- readonly window?: Window;
333
333
  }
334
334
  /**
335
335
  * history implementation backed by the web navigation API.
@@ -346,6 +346,7 @@ declare class NavigationHistory implements History {
346
346
  entries(): readonly HistoryEntry[];
347
347
  push(to: string, options?: HistoryNavigateOptions): void;
348
348
  replace(to: string, options?: HistoryNavigateOptions): void;
349
+ updateState(state: unknown): void;
349
350
  traverseTo(key: string): Promise<void>;
350
351
  go(delta: number): void;
351
352
  back(): void;
@@ -357,17 +358,17 @@ declare class NavigationHistory implements History {
357
358
  //#region src/view-model.d.ts
358
359
  /** an instance node within the layout tree structure. */
359
360
  interface InstanceNode {
360
- readonly children: InstanceNode[];
361
361
  readonly instanceKey: string;
362
362
  readonly node: ResolvedNode;
363
363
  readonly params: Readonly<Record<string, unknown>>;
364
+ readonly children: InstanceNode[];
364
365
  }
365
366
  /** the computed rendering view configuration. */
366
367
  interface View {
367
- /** instance keys along the active chain from root to leaf. */
368
- readonly activePath: readonly string[];
369
368
  /** the top-level pool (instances at the root outlet). */
370
369
  readonly roots: readonly InstanceNode[];
370
+ /** instance keys along the active chain from root to leaf. */
371
+ readonly activePath: readonly string[];
371
372
  }
372
373
  //#endregion
373
374
  //#region src/lazy.d.ts
@@ -393,25 +394,25 @@ declare const lazy: <T extends ComponentType<any>>(init: () => Promise<{
393
394
  //#region src/router.d.ts
394
395
  /** options for a navigation. */
395
396
  interface NavigateOptions<R extends RouteRegistry<unknown>> extends HistoryNavigateOptions {
396
- /** replace the active history entry instead. */
397
- readonly replace?: boolean;
398
397
  /** where to go */
399
398
  readonly to: RouteTarget<R> | string;
399
+ /** replace the active history entry instead. */
400
+ readonly replace?: boolean;
400
401
  }
401
402
  /** options for the router constructor. */
402
403
  interface RouterOptions<R extends RouteRegistry<unknown>> {
403
- /** default fallback component shown during lazy chunk loading. */
404
- readonly defaultFallback?: ReactNode;
404
+ /** compiled route registry. */
405
+ readonly routes: R;
405
406
  /** backing history instance. */
406
407
  readonly history: History;
407
- /** maximum number of backward entries to keep warm. */
408
- readonly max?: number;
409
408
  /** component rendered when no route matches. */
410
409
  readonly notFound?: ComponentType;
410
+ /** default fallback component shown during lazy chunk loading. */
411
+ readonly defaultFallback?: ReactNode;
412
+ /** maximum number of backward entries to keep warm. */
413
+ readonly max?: number;
411
414
  /** route names of pathless singleton routes to keep warm for the router's lifetime once first visited. */
412
415
  readonly pins?: readonly string[];
413
- /** compiled route registry. */
414
- readonly routes: R;
415
416
  /** window whose scroll position the router restores, defaulting to the global one where there is one. */
416
417
  readonly window?: Window;
417
418
  }
@@ -499,6 +500,17 @@ declare class Router<R extends RouteRegistry<unknown>> {
499
500
  * @throws when `name` is not the active route
500
501
  */
501
502
  replace<K extends RouteName<R>>(name: K, patch: QueryPatchOf<R, K>): void;
503
+ /**
504
+ * rewrites the active history entry's state, without navigating.
505
+ *
506
+ * the entry keeps its URL and slot, so the screen stays mounted and the viewport does not move. the whole
507
+ * state is replaced, so build the next value from `router.location.state` to keep the parts you still want.
508
+ * readers of `useLocation` re-render with it.
509
+ *
510
+ * @param state state data to store on the entry
511
+ * @throws when the state cannot be structured-cloned, leaving the entry as it was
512
+ */
513
+ updateState(state: unknown): void;
502
514
  /** navigates back one entry. */
503
515
  back(): void;
504
516
  /** navigates forward one entry. */
@@ -591,12 +603,12 @@ declare const useIsFocused: () => boolean;
591
603
  declare const useFocusEffect: (effect: EffectCallback) => void;
592
604
  /** typed hooks bound to a specific route registry. */
593
605
  interface RouterHooks<R extends RouteRegistry<unknown>> {
594
- /** gets a route's parameters and a setter that patches its query in place. */
595
- useParams<K extends RouteName<R>>(name: K): readonly [ParamsOf<R, K>, (patch: QueryPatchOf<R, K>) => void];
596
606
  /** gets the typed router instance. */
597
607
  useRouter(): Router<R>;
598
608
  /** gets the active route's name and parameters. */
599
609
  useTarget(): MatchedTarget<R>;
610
+ /** gets a route's parameters and a setter that patches its query in place. */
611
+ useParams<K extends RouteName<R>>(name: K): readonly [ParamsOf<R, K>, (patch: QueryPatchOf<R, K>) => void];
600
612
  }
601
613
  /**
602
614
  * generates typed hooks bound to a specific route registry.
@@ -613,10 +625,10 @@ declare const createRouterHooks: <R extends RouteRegistry<unknown>>(routes: R) =
613
625
  //#region src/react/link.d.ts
614
626
  /** properties for the link component. */
615
627
  interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
616
- /** replace the current history entry. */
617
- readonly replace?: boolean;
618
628
  /** target relative URL path. */
619
629
  readonly to: string;
630
+ /** replace the current history entry. */
631
+ readonly replace?: boolean;
620
632
  }
621
633
  /**
622
634
  * anchor element that intercepts clicks for in-app navigation.
@@ -626,6 +638,6 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'
626
638
  * @param props link properties
627
639
  * @returns rendered anchor element
628
640
  */
629
- declare const Link: ({ children, onClick, replace, to, ...rest }: LinkProps) => ReactElement;
641
+ declare const Link: ({ to, replace, children, onClick, ...rest }: LinkProps) => ReactElement;
630
642
  //#endregion
631
643
  export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryScrollBehavior, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LazyComponent, type LeafType, Link, type LinkProps, type MatchedNode, type MatchedTarget, type NavigateOptions, 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, type RouteTarget, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };