@oomfware/stacker 0.2.4 → 0.2.5

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
@@ -303,8 +303,8 @@ use `router.dispose()` to detach the router from history when it is no longer ne
303
303
  use focus hooks for work that should run when the screen becomes active, rather than when it mounts:
304
304
 
305
305
  ```tsx
306
- import { useCallback } from 'react';
307
306
  import { useFocusEffect, useIsFocused } from '@oomfware/stacker';
307
+ import { useCallback } from 'react';
308
308
 
309
309
  const Profile = () => {
310
310
  const [{ actor }] = useParams('Profile');
package/dist/index.d.mts CHANGED
@@ -1,6 +1,5 @@
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";
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-BUru23Cr.mjs";
2
2
  import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
3
- //#region src/codec.d.ts
4
3
  /**
5
4
  * a bidirectional codec for a single route parameter.
6
5
  *
@@ -54,26 +53,26 @@ type BuildShape<P extends CodecRecord> = Prettify$1<{ [K in Exclude<keyof P, Def
54
53
  *
55
54
  * @returns the string codec
56
55
  */
57
- declare const string: () => Codec<string>;
56
+ export declare const string: () => Codec<string>;
58
57
  /**
59
58
  * creates a codec for a safe integer.
60
59
  *
61
60
  * @returns the integer codec
62
61
  */
63
- declare const integer: () => Codec<number>;
62
+ export declare const integer: () => Codec<number>;
64
63
  /**
65
64
  * creates a codec for a boolean value.
66
65
  *
67
66
  * @returns the boolean codec
68
67
  */
69
- declare const boolean: () => Codec<boolean>;
68
+ export declare const boolean: () => Codec<boolean>;
70
69
  /**
71
70
  * creates a codec for a fixed set of string values.
72
71
  *
73
72
  * @param values the allowed string values
74
73
  * @returns the enum codec
75
74
  */
76
- declare const enumOf: <const V extends readonly string[]>(values: V) => Codec<V[number]>;
75
+ export declare const enumOf: <const V extends readonly string[]>(values: V) => Codec<V[number]>;
77
76
  /**
78
77
  * creates a codec for a string that rejects the empty value.
79
78
  *
@@ -83,14 +82,14 @@ declare const enumOf: <const V extends readonly string[]>(values: V) => Codec<V[
83
82
  *
84
83
  * @returns the non-empty string codec
85
84
  */
86
- declare const nonEmpty: () => Codec<string>;
85
+ export declare const nonEmpty: () => Codec<string>;
87
86
  /**
88
87
  * wraps a codec to allow its parameter to be absent.
89
88
  *
90
89
  * @param codec the inner codec
91
90
  * @returns the optional codec
92
91
  */
93
- declare const optional: <T>(codec: Codec<T>) => OptionalCodec<T>;
92
+ export declare const optional: <T>(codec: Codec<T>) => OptionalCodec<T>;
94
93
  /**
95
94
  * wraps a codec with a default value.
96
95
  *
@@ -98,9 +97,7 @@ declare const optional: <T>(codec: Codec<T>) => OptionalCodec<T>;
98
97
  * @param fallback the default value
99
98
  * @returns the defaulted codec
100
99
  */
101
- declare const withDefault: <T>(codec: Codec<T>, fallback: T) => DefaultedCodec<T>;
102
- //#endregion
103
- //#region src/routes.d.ts
100
+ export declare const withDefault: <T>(codec: Codec<T>, fallback: T) => DefaultedCodec<T>;
104
101
  type Empty = Record<never, never>;
105
102
  /**
106
103
  * defines how a leaf route instance is keyed.
@@ -189,14 +186,14 @@ interface RouteChildren {
189
186
  * @param config the route configuration
190
187
  * @returns the route leaf node
191
188
  */
192
- declare const route: <const Params extends CodecRecord = Empty, const Query extends CodecRecord = Empty>(config: RouteConfig<Params, Query>) => RouteLeaf<Params, Query>;
189
+ export declare const route: <const Params extends CodecRecord = Empty, const Query extends CodecRecord = Empty>(config: RouteConfig<Params, Query>) => RouteLeaf<Params, Query>;
193
190
  /**
194
191
  * defines an interior layout node.
195
192
  *
196
193
  * @param config the layout configuration
197
194
  * @returns the layout node
198
195
  */
199
- declare const layout: <const Children extends RouteChildren, const Params extends CodecRecord = Empty>(config: LayoutConfig<Children, Params>) => LayoutNode<Children, Params>;
196
+ export declare const layout: <const Children extends RouteChildren, const Params extends CodecRecord = Empty>(config: LayoutConfig<Children, Params>) => LayoutNode<Children, Params>;
200
197
  /** a node resolved with an id and normalized parameters. */
201
198
  interface ResolvedNode {
202
199
  readonly kind: 'layout' | 'route';
@@ -238,7 +235,7 @@ type ValidRoutes<T> = { readonly [K in keyof T]: T[K] extends RouteNode ? T[K] :
238
235
  * @returns the compiled registry
239
236
  * @throws when route definitions violate nesting, unique names, or codec constraints
240
237
  */
241
- declare const defineRoutes: <const T>(tree: T & ValidRoutes<T>) => RouteRegistry<T>;
238
+ export declare const defineRoutes: <const T>(tree: T & ValidRoutes<T>) => RouteRegistry<T>;
242
239
  type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
243
240
  type FlattenChildren<C> = UnionToIntersection<{ [K in keyof C]: C[K] extends {
244
241
  readonly kind: 'layout';
@@ -281,8 +278,6 @@ type BuildParamsOf<R, K extends RouteName<R>> = LeafBuild<LeavesMap<R>[K]>;
281
278
  * `undefined` to delete the parameter. path parameters are excluded — they are not settable in place.
282
279
  */
283
280
  type QueryPatchOf<R, K extends RouteName<R>> = LeafQueryPatch<LeavesMap<R>[K]>;
284
- //#endregion
285
- //#region src/match.d.ts
286
281
  /** a node on a matched chain paired with its instance parameters. */
287
282
  interface MatchedNode {
288
283
  readonly node: ResolvedNode;
@@ -304,9 +299,7 @@ interface RouteMatch {
304
299
  * @param key the metadata key to resolve
305
300
  * @returns the nearest metadata value, or undefined if none is found
306
301
  */
307
- declare const resolveMeta: <K extends keyof RouteMeta>(match: RouteMatch, key: K) => RouteMeta[K] | undefined;
308
- //#endregion
309
- //#region src/history/navigation.d.ts
302
+ export declare const resolveMeta: <K extends keyof RouteMeta>(match: RouteMatch, key: K) => RouteMeta[K] | undefined;
310
303
  /** options for navigation-api history. */
311
304
  interface NavigationHistoryOptions {
312
305
  /** window instance to bind to; defaults to global window. */
@@ -337,7 +330,7 @@ interface NavigationHistoryOptions {
337
330
  * intercepting same-document navigations converts standard page loads into in-app renders. per-revision
338
331
  * metadata and indices are managed natively by the browser.
339
332
  */
340
- declare class NavigationHistory implements History {
333
+ export declare class NavigationHistory implements History {
341
334
  #private;
342
335
  constructor(options?: NavigationHistoryOptions);
343
336
  get location(): HistoryLocation;
@@ -354,8 +347,6 @@ declare class NavigationHistory implements History {
354
347
  listen(listener: HistoryListener): () => void;
355
348
  dispose(): void;
356
349
  }
357
- //#endregion
358
- //#region src/view-model.d.ts
359
350
  /** an instance node within the layout tree structure. */
360
351
  interface InstanceNode {
361
352
  readonly instanceKey: string;
@@ -370,8 +361,6 @@ interface View {
370
361
  /** instance keys along the active chain from root to leaf. */
371
362
  readonly activePath: readonly string[];
372
363
  }
373
- //#endregion
374
- //#region src/lazy.d.ts
375
364
  /** a preloadable lazily-loaded component. */
376
365
  type LazyComponent<T extends ComponentType<any>> = LazyExoticComponent<T> & {
377
366
  /**
@@ -387,11 +376,9 @@ type LazyComponent<T extends ComponentType<any>> = LazyExoticComponent<T> & {
387
376
  * @param init component module loader
388
377
  * @returns lazy component
389
378
  */
390
- declare const lazy: <T extends ComponentType<any>>(init: () => Promise<{
379
+ export declare const lazy: <T extends ComponentType<any>>(init: () => Promise<{
391
380
  default: T;
392
381
  }>) => LazyComponent<T>;
393
- //#endregion
394
- //#region src/router.d.ts
395
382
  /** options for a navigation. */
396
383
  interface NavigateOptions<R extends RouteRegistry<unknown>> extends HistoryNavigateOptions {
397
384
  /** where to go */
@@ -422,7 +409,7 @@ interface RouterOptions<R extends RouteRegistry<unknown>> {
422
409
  * this class acts as the store for the React router view, maintaining and caching active matched nodes and
423
410
  * coordinates scrolling and focus.
424
411
  */
425
- declare class Router<R extends RouteRegistry<unknown>> {
412
+ export declare class Router<R extends RouteRegistry<unknown>> {
426
413
  #private;
427
414
  constructor(options: RouterOptions<R>);
428
415
  /** current view structure. */
@@ -535,8 +522,6 @@ declare class Router<R extends RouteRegistry<unknown>> {
535
522
  /** detaches history listeners and disposes resources. */
536
523
  dispose(): void;
537
524
  }
538
- //#endregion
539
- //#region src/react/router-view.d.ts
540
525
  /**
541
526
  * renders the current view tree of the router.
542
527
  *
@@ -547,51 +532,47 @@ declare class Router<R extends RouteRegistry<unknown>> {
547
532
  * @param props.router router instance
548
533
  * @returns rendered component tree
549
534
  */
550
- declare const RouterView: <R extends RouteRegistry<unknown>>({ router }: {
535
+ export declare const RouterView: <R extends RouteRegistry<unknown>>({ router }: {
551
536
  readonly router: Router<R>;
552
537
  }) => ReactElement;
553
- //#endregion
554
- //#region src/react/outlet.d.ts
555
538
  /**
556
539
  * renders the child branch pool within a layout component.
557
540
  *
558
541
  * @returns rendered outlet child pool or null if outside a layout
559
542
  */
560
- declare const Outlet: () => ReactElement | null;
561
- //#endregion
562
- //#region src/react/hooks.d.ts
543
+ export declare const Outlet: () => ReactElement | null;
563
544
  /**
564
545
  * gets the active router instance.
565
546
  *
566
547
  * @returns router instance
567
548
  * @throws when used outside a router view context
568
549
  */
569
- declare const useRouter: () => Router<RouteRegistry<unknown>>;
550
+ export declare const useRouter: () => Router<RouteRegistry<unknown>>;
570
551
  /**
571
552
  * gets the active history location.
572
553
  *
573
554
  * @returns history location
574
555
  */
575
- declare const useLocation: () => HistoryLocation;
556
+ export declare const useLocation: () => HistoryLocation;
576
557
  /**
577
558
  * gets the active route match information.
578
559
  *
579
560
  * @returns active route match
580
561
  */
581
- declare const useRoute: () => RouteMatch;
562
+ export declare const useRoute: () => RouteMatch;
582
563
  /**
583
564
  * gets the untyped parameter map of the nearest enclosing route node.
584
565
  *
585
566
  * @returns decoded parameters
586
567
  * @throws when used outside a route tree context
587
568
  */
588
- declare const useParams: () => Readonly<Record<string, unknown>>;
569
+ export declare const useParams: () => Readonly<Record<string, unknown>>;
589
570
  /**
590
571
  * gets whether the enclosing branch is focused (on screen).
591
572
  *
592
573
  * @returns true if focused
593
574
  */
594
- declare const useIsFocused: () => boolean;
575
+ export declare const useIsFocused: () => boolean;
595
576
  /**
596
577
  * runs an effect callback only while the branch is focused.
597
578
  *
@@ -600,7 +581,7 @@ declare const useIsFocused: () => boolean;
600
581
  *
601
582
  * @param effect effect callback
602
583
  */
603
- declare const useFocusEffect: (effect: EffectCallback) => void;
584
+ export declare const useFocusEffect: (effect: EffectCallback) => void;
604
585
  /** typed hooks bound to a specific route registry. */
605
586
  interface RouterHooks<R extends RouteRegistry<unknown>> {
606
587
  /** gets the typed router instance. */
@@ -620,9 +601,7 @@ interface RouterHooks<R extends RouteRegistry<unknown>> {
620
601
  * @returns typed hooks record
621
602
  * @throws when used with a router built from a different registry
622
603
  */
623
- declare const createRouterHooks: <R extends RouteRegistry<unknown>>(routes: R) => RouterHooks<R>;
624
- //#endregion
625
- //#region src/react/link.d.ts
604
+ export declare const createRouterHooks: <R extends RouteRegistry<unknown>>(routes: R) => RouterHooks<R>;
626
605
  /** properties for the link component. */
627
606
  interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
628
607
  /** target relative URL path. */
@@ -638,6 +617,5 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'
638
617
  * @param props link properties
639
618
  * @returns rendered anchor element
640
619
  */
641
- declare const Link: ({ to, replace, children, onClick, ...rest }: LinkProps) => ReactElement;
642
- //#endregion
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 };
620
+ export declare const Link: ({ to, replace, children, onClick, ...rest }: LinkProps) => ReactElement;
621
+ export type { BuildParamsOf, Codec, DefaultedCodec, History, HistoryAction, HistoryEntry, HistoryListener, HistoryLocation, HistoryNavigateOptions, HistoryScrollBehavior, HistoryUpdate, Infer, InstanceNode, LayoutConfig, LayoutNode, LazyComponent, LeafType, LinkProps, MatchedNode, MatchedTarget, NavigateOptions, NavigationHistoryOptions, OptionalCodec, ParamsOf, QueryPatchOf, ReadonlyURLSearchParams, ResolvedLeaf, ResolvedNode, RouteChildren, RouteConfig, RouteLeaf, RouteMatch, RouteMeta, RouteName, RouteNode, RouteRegistry, RouteTarget, RouterHooks, RouterOptions, View, WhenContext };
package/dist/index.mjs CHANGED
@@ -1,8 +1,8 @@
1
- import { a as parsePath, i as encodeSegment, n as decodeRemainder, o as resolvePath, r as encodeRemainder, t as createPath } from "./url-ghfWE9j6.mjs";
1
+ import { a as parsePath, i as encodeSegment, n as decodeRemainder, o as resolvePath, r as encodeRemainder, t as createPath } from "./url-0EHjozDe.mjs";
2
2
  import { Suspense, createContext, lazy as lazy$1, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
3
3
  import { SimpleEventEmitter } from "@mary-ext/simple-event-emitter";
4
4
  import { Fragment, jsx, jsxs } from "react/jsx-runtime";
5
- //#region src/codec.ts
5
+ // src/codec.ts
6
6
  const OPTIONAL = Symbol("stacker.optional");
7
7
  const DEFAULT = Symbol("stacker.default");
8
8
  /**
@@ -103,8 +103,7 @@ const isOptional = (codec) => {
103
103
  const getDefault = (codec) => {
104
104
  return DEFAULT in codec ? [codec[DEFAULT]] : void 0;
105
105
  };
106
- //#endregion
107
- //#region src/routes.ts
106
+ // src/routes.ts
108
107
  /**
109
108
  * defines a navigable leaf route.
110
109
  *
@@ -225,8 +224,7 @@ const defineRoutes = (tree) => {
225
224
  tree
226
225
  };
227
226
  };
228
- //#endregion
229
- //#region src/match.ts
227
+ // src/match.ts
230
228
  /**
231
229
  * looks up the nearest metadata value for a key on a matched chain, searching leaf-first.
232
230
  *
@@ -376,8 +374,9 @@ var Matcher = class {
376
374
  return out;
377
375
  }
378
376
  };
379
- //#endregion
380
- //#region src/history/navigation.ts
377
+ // src/webkit.ts
378
+ const isWebKit = (userAgent) => /AppleWebKit\//.test(userAgent) && !/(?:Chrome|Chromium)\//.test(userAgent);
379
+ // src/history/navigation.ts
381
380
  const ENVELOPE = Symbol("stacker.historyInfo");
382
381
  const isEnvelope = (value) => typeof value === "object" && value !== null && ENVELOPE in value;
383
382
  const toAction = (type) => {
@@ -389,7 +388,6 @@ const toAction = (type) => {
389
388
  }
390
389
  };
391
390
  const isAbort = (error) => typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
392
- const isWebKit = (userAgent) => /AppleWebKit\//.test(userAgent) && !/(?:Chrome|Chromium)\//.test(userAgent);
393
391
  /**
394
392
  * history implementation backed by the web navigation API.
395
393
  *
@@ -404,12 +402,12 @@ var NavigationHistory = class {
404
402
  #win;
405
403
  #disposed = false;
406
404
  #location;
407
- #interceptTraversals;
405
+ #webkit;
408
406
  constructor(options = {}) {
409
407
  this.#win = options.window ?? window;
410
408
  this.#nav = this.#win.navigation;
411
409
  this.#ignore = options.ignore;
412
- this.#interceptTraversals = !isWebKit(this.#win.navigator.userAgent);
410
+ this.#webkit = isWebKit(this.#win.navigator.userAgent);
413
411
  this.#onError = options.onError ?? ((error) => {
414
412
  this.#win.reportError(error);
415
413
  });
@@ -417,6 +415,7 @@ var NavigationHistory = class {
417
415
  this.#nav.addEventListener("currententrychange", this.#onCurrentEntryChange);
418
416
  this.#nav.addEventListener("navigate", this.#onNavigate);
419
417
  this.#nav.addEventListener("navigateerror", this.#onNavigateError);
418
+ if (this.#webkit) this.#win.addEventListener("popstate", this.#onPopState);
420
419
  this.#win.history.scrollRestoration = "manual";
421
420
  }
422
421
  get location() {
@@ -448,6 +447,7 @@ var NavigationHistory = class {
448
447
  this.#nav.updateCurrentEntry({ state });
449
448
  }
450
449
  traverseTo(key) {
450
+ if (this.#webkit) return this.#traverseLegacy(key);
451
451
  return this.#track(this.#nav.traverseTo(key));
452
452
  }
453
453
  go(delta) {
@@ -457,10 +457,20 @@ var NavigationHistory = class {
457
457
  this.#report(this.traverseTo(target.key));
458
458
  }
459
459
  back() {
460
- if (this.#nav.canGoBack) this.#report(this.#track(this.#nav.back()));
460
+ if (!this.#nav.canGoBack) return;
461
+ if (this.#webkit) {
462
+ this.#win.history.back();
463
+ return;
464
+ }
465
+ this.#report(this.#track(this.#nav.back()));
461
466
  }
462
467
  forward() {
463
- if (this.#nav.canGoForward) this.#report(this.#track(this.#nav.forward()));
468
+ if (!this.#nav.canGoForward) return;
469
+ if (this.#webkit) {
470
+ this.#win.history.forward();
471
+ return;
472
+ }
473
+ this.#report(this.#track(this.#nav.forward()));
464
474
  }
465
475
  listen(listener) {
466
476
  this.#listeners.add(listener);
@@ -473,8 +483,21 @@ var NavigationHistory = class {
473
483
  this.#nav.removeEventListener("currententrychange", this.#onCurrentEntryChange);
474
484
  this.#nav.removeEventListener("navigate", this.#onNavigate);
475
485
  this.#nav.removeEventListener("navigateerror", this.#onNavigateError);
486
+ this.#win.removeEventListener("popstate", this.#onPopState);
476
487
  this.#listeners.clear();
477
488
  }
489
+ async #traverseLegacy(key) {
490
+ const target = this.#nav.entries().find((entry) => entry.key === key);
491
+ if (target === void 0) throw new DOMException(`no history entry with the key '${key}'`, "InvalidStateError");
492
+ const delta = target.index - this.#location.index;
493
+ if (delta !== 0) this.#win.history.go(delta);
494
+ }
495
+ #onPopState = () => {
496
+ const entry = this.#nav.currentEntry;
497
+ if (entry !== null && entry.key === this.#location.key) return;
498
+ this.dispose();
499
+ this.#win.location.reload();
500
+ };
478
501
  #track(result) {
479
502
  result.finished?.catch(() => {});
480
503
  return result.committed?.then(() => void 0) ?? Promise.resolve();
@@ -519,7 +542,7 @@ var NavigationHistory = class {
519
542
  };
520
543
  }
521
544
  #onCurrentEntryChange = (event) => {
522
- if (event.navigationType === "traverse" && !this.#interceptTraversals) {
545
+ if (event.navigationType === "traverse" && this.#webkit) {
523
546
  this.#report(this.#traverseUnintercepted());
524
547
  return;
525
548
  }
@@ -553,7 +576,7 @@ var NavigationHistory = class {
553
576
  const action = toAction(event.navigationType);
554
577
  if (action === void 0 || !event.canIntercept) return;
555
578
  if (event.downloadRequest !== null || event.formData !== null) return;
556
- if (action === "traverse" && !this.#interceptTraversals) return;
579
+ if (action === "traverse" && this.#webkit) return;
557
580
  if (action !== "traverse" && this.#ignore?.(new URL(event.destination.url))) return;
558
581
  const envelope = isEnvelope(event.info) ? event.info : void 0;
559
582
  const info = envelope === void 0 ? event.info : envelope.info;
@@ -583,8 +606,7 @@ const toRelative = (url) => {
583
606
  const { pathname, search, hash } = new URL(url);
584
607
  return `${pathname}${search}${hash}`;
585
608
  };
586
- //#endregion
587
- //#region src/lazy.ts
609
+ // src/lazy.ts
588
610
  const noop = () => {};
589
611
  /**
590
612
  * defines a lazily-loaded component that can be preloaded.
@@ -622,8 +644,7 @@ const preloadAll = (chain) => {
622
644
  }
623
645
  return Promise.all(pending).then(noop);
624
646
  };
625
- //#endregion
626
- //#region src/build.ts
647
+ // src/build.ts
627
648
  const SEGMENT = /:([A-Za-z_]\w*)/g;
628
649
  var Builder = class {
629
650
  #registry;
@@ -674,8 +695,7 @@ var Builder = class {
674
695
  });
675
696
  }
676
697
  };
677
- //#endregion
678
- //#region src/cache.ts
698
+ // src/cache.ts
679
699
  /** selects the active entry and recent backward entries for caching. */
680
700
  const computeCachedKeys = (entries, activeKey, recency, policy) => {
681
701
  const cached = /* @__PURE__ */ new Set();
@@ -694,8 +714,7 @@ const computeCachedKeys = (entries, activeKey, recency, policy) => {
694
714
  for (const entry of [...backward.values()].toSorted((a, b) => b.index - a.index)) take(entry.key);
695
715
  return cached;
696
716
  };
697
- //#endregion
698
- //#region src/keys.ts
717
+ // src/keys.ts
699
718
  const SEP = "\0";
700
719
  /**
701
720
  * serializes path parameters into a stable, sorted, percent-encoded string.
@@ -722,8 +741,7 @@ const instanceKey = (matched, entryKey) => {
722
741
  if (resolved.kind === "layout") return `${resolved.id}${SEP}${canonical(matched)}`;
723
742
  return (resolved.node.kind === "route" ? resolved.node.type ?? "page" : "page") === "singleton" ? `${resolved.id}${SEP}${canonical(matched)}` : `${resolved.id}${SEP}entry:${entryKey}`;
724
743
  };
725
- //#endregion
726
- //#region src/view-model.ts
744
+ // src/view-model.ts
727
745
  /**
728
746
  * builds the active view and computes which entries and instances to prune.
729
747
  *
@@ -760,8 +778,7 @@ const computeView = (cached, pinned, activeKey) => {
760
778
  activePath: active.match.chain.map((matched) => instanceKey(matched, active.key))
761
779
  };
762
780
  };
763
- //#endregion
764
- //#region src/router.ts
781
+ // src/router.ts
765
782
  const DefaultNotFound = () => null;
766
783
  const TOP = {
767
784
  x: 0,
@@ -793,6 +810,8 @@ var Router = class {
793
810
  #commitWaiters = [];
794
811
  #viewAttached = false;
795
812
  #pendingScroll = null;
813
+ #guardScrolls;
814
+ #stopScrollGuard = null;
796
815
  constructor(options) {
797
816
  this.#history = options.history;
798
817
  this.#routes = options.routes;
@@ -803,6 +822,7 @@ var Router = class {
803
822
  this.#notFound = makeNotFound(options.notFound ?? DefaultNotFound);
804
823
  this.#pins = new Map((options.pins ?? []).map((name) => [name, this.#makePin(name)]));
805
824
  this.#win = options.window ?? (typeof window === "undefined" ? null : window);
825
+ this.#guardScrolls = this.#win !== null && isWebKit(this.#win.navigator.userAgent);
806
826
  const location = this.#history.location;
807
827
  this.#activeKey = location.key;
808
828
  this.#record(location, TOP);
@@ -812,21 +832,31 @@ var Router = class {
812
832
  this.#updates.emit();
813
833
  return;
814
834
  }
815
- const win = this.#win;
816
- const restoring = scroll === "auto" && win !== null;
817
- if (restoring) {
835
+ const win = scroll === "auto" ? this.#win : null;
836
+ const departed = win === null ? null : {
837
+ x: win.scrollX,
838
+ y: win.scrollY
839
+ };
840
+ if (departed !== null) {
818
841
  const outgoing = this.#entries.get(this.#activeKey);
819
- if (outgoing !== void 0) outgoing.scrollPos = {
820
- x: win.scrollX,
821
- y: win.scrollY
822
- };
842
+ if (outgoing !== void 0) outgoing.scrollPos = departed;
823
843
  }
824
844
  this.#prune();
825
845
  const target = (action === "traverse" ? this.#entries.get(next.key)?.scrollPos : void 0) ?? TOP;
826
846
  this.#record(next, target);
827
847
  this.#activeKey = next.key;
828
848
  this.#view = this.#recompute();
829
- this.#pendingScroll = restoring ? target : null;
849
+ if (win !== null && departed !== null) {
850
+ this.#pendingScroll = {
851
+ target,
852
+ guard: this.#guardScrolls && Math.abs(departed.y - target.y) >= 1
853
+ };
854
+ win.scrollTo({
855
+ behavior: "instant",
856
+ left: target.x,
857
+ top: target.y
858
+ });
859
+ } else this.#pendingScroll = null;
830
860
  const committed = this.#awaitCommit();
831
861
  this.#updates.emit();
832
862
  await committed;
@@ -1041,16 +1071,79 @@ var Router = class {
1041
1071
  this.#pendingScroll = null;
1042
1072
  win.scrollTo({
1043
1073
  behavior: "instant",
1044
- left: pending.x,
1045
- top: pending.y
1074
+ left: pending.target.x,
1075
+ top: pending.target.y
1046
1076
  });
1077
+ if (pending.guard) this.#guardScroll(win);
1047
1078
  }
1048
1079
  /** detaches history listeners and disposes resources. */
1049
1080
  dispose() {
1081
+ this.#stopScrollGuard?.();
1050
1082
  this.#unlisten();
1051
1083
  this.#history.dispose();
1052
1084
  this.notifyCommit();
1053
1085
  }
1086
+ #guardScroll(win) {
1087
+ this.#stopScrollGuard?.();
1088
+ const controller = new AbortController();
1089
+ const { signal } = controller;
1090
+ const stop = () => {
1091
+ controller.abort();
1092
+ };
1093
+ const timer = setTimeout(stop, 1e3);
1094
+ this.#stopScrollGuard = stop;
1095
+ signal.addEventListener("abort", () => {
1096
+ clearTimeout(timer);
1097
+ if (this.#stopScrollGuard === stop) this.#stopScrollGuard = null;
1098
+ });
1099
+ const root = win.document.scrollingElement ?? win.document.documentElement;
1100
+ const read = () => ({
1101
+ x: Math.max(0, win.scrollX),
1102
+ y: Math.max(0, win.scrollY)
1103
+ });
1104
+ let expected = read();
1105
+ const scrollTo = win.scrollTo.bind(win);
1106
+ for (const method of [
1107
+ "scroll",
1108
+ "scrollTo",
1109
+ "scrollBy"
1110
+ ]) {
1111
+ const original = win[method];
1112
+ win[method] = function(...args) {
1113
+ const [options] = args;
1114
+ if (typeof options === "object" && options !== null && "behavior" in options && options.behavior === "smooth") stop();
1115
+ Reflect.apply(original, this, args);
1116
+ expected = read();
1117
+ };
1118
+ signal.addEventListener("abort", () => {
1119
+ win[method] = original;
1120
+ });
1121
+ }
1122
+ win.addEventListener("scroll", () => {
1123
+ const current = read();
1124
+ if (Math.abs(current.y - expected.y) < 1 && Math.abs(current.x - expected.x) < 1) return;
1125
+ const maxY = Math.max(0, root.scrollHeight - root.clientHeight);
1126
+ if (expected.y > maxY && Math.abs(current.y - maxY) < 1) {
1127
+ expected = current;
1128
+ return;
1129
+ }
1130
+ scrollTo({
1131
+ behavior: "instant",
1132
+ left: expected.x,
1133
+ top: expected.y
1134
+ });
1135
+ }, { signal });
1136
+ for (const type of [
1137
+ "touchstart",
1138
+ "wheel",
1139
+ "keydown",
1140
+ "pointerdown"
1141
+ ]) win.addEventListener(type, stop, {
1142
+ capture: true,
1143
+ passive: true,
1144
+ signal
1145
+ });
1146
+ }
1054
1147
  #active() {
1055
1148
  const active = this.#entries.get(this.#activeKey);
1056
1149
  if (active === void 0) throw new Error(`stacker: no warm entry for the active key '${this.#activeKey}'`);
@@ -1089,10 +1182,11 @@ var Router = class {
1089
1182
  }
1090
1183
  #recompute() {
1091
1184
  const active = this.#active();
1092
- const cachedKeys = computeCachedKeys([...this.#entries.values()].map((entry) => ({
1185
+ const refs = [...this.#entries.values()].map((entry) => ({
1093
1186
  key: entry.key,
1094
1187
  index: entry.index
1095
- })), active.key, this.#recency, { max: this.#max });
1188
+ }));
1189
+ const cachedKeys = computeCachedKeys(refs, active.key, this.#recency, { max: this.#max });
1096
1190
  const cached = [];
1097
1191
  for (const entry of this.#entries.values()) if (cachedKeys.has(entry.key)) cached.push({
1098
1192
  key: entry.key,
@@ -1161,13 +1255,11 @@ const makeNotFound = (component) => {
1161
1255
  node
1162
1256
  };
1163
1257
  };
1164
- //#endregion
1165
- //#region src/react/context.ts
1258
+ // src/react/context.ts
1166
1259
  const RouterContext = createContext(null);
1167
1260
  const ActiveChainContext = createContext([]);
1168
1261
  const CurrentNodeContext = createContext(null);
1169
- //#endregion
1170
- //#region src/react/router-view.tsx
1262
+ // src/react/router-view.tsx
1171
1263
  /**
1172
1264
  * renders the current view tree of the router.
1173
1265
  *
@@ -1231,8 +1323,7 @@ const Branch = ({ node, focused }) => {
1231
1323
  })
1232
1324
  });
1233
1325
  };
1234
- //#endregion
1235
- //#region src/react/outlet.tsx
1326
+ // src/react/outlet.tsx
1236
1327
  /**
1237
1328
  * renders the child branch pool within a layout component.
1238
1329
  *
@@ -1243,8 +1334,7 @@ const Outlet = () => {
1243
1334
  if (current === null) return null;
1244
1335
  return /* @__PURE__ */ jsx(Pool, { nodes: current.node.children });
1245
1336
  };
1246
- //#endregion
1247
- //#region src/react/hooks.ts
1337
+ // src/react/hooks.ts
1248
1338
  /**
1249
1339
  * gets the active router instance.
1250
1340
  *
@@ -1343,8 +1433,7 @@ const createRouterHooks = (routes) => {
1343
1433
  }
1344
1434
  };
1345
1435
  };
1346
- //#endregion
1347
- //#region src/react/link.tsx
1436
+ // src/react/link.tsx
1348
1437
  const isModifiedClick = (event) => event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
1349
1438
  const isRoutable = (to) => {
1350
1439
  try {
@@ -1378,5 +1467,4 @@ const Link = ({ to, replace, children, onClick, ...rest }) => {
1378
1467
  children
1379
1468
  });
1380
1469
  };
1381
- //#endregion
1382
1470
  export { Link, NavigationHistory, Outlet, Router, RouterView, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
@@ -1,5 +1,4 @@
1
- import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types--iOZjfC1.mjs";
2
- //#region src/history/memory.d.ts
1
+ import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-BUru23Cr.mjs";
3
2
  /** options for the memory history constructor. */
4
3
  interface MemoryHistoryOptions {
5
4
  /** initial entry relative URLs. */
@@ -13,7 +12,7 @@ interface MemoryHistoryOptions {
13
12
  * replicates browser navigation ledger semantics, including history replacement, entry stack pruning, and
14
13
  * state traversal.
15
14
  */
16
- declare class MemoryHistory implements History {
15
+ export declare class MemoryHistory implements History {
17
16
  #private;
18
17
  constructor(options?: MemoryHistoryOptions);
19
18
  get location(): HistoryLocation;
@@ -30,5 +29,4 @@ declare class MemoryHistory implements History {
30
29
  listen(listener: HistoryListener): () => void;
31
30
  dispose(): void;
32
31
  }
33
- //#endregion
34
- export { MemoryHistory, type MemoryHistoryOptions };
32
+ export type { MemoryHistoryOptions };
package/dist/testing.mjs CHANGED
@@ -1,6 +1,6 @@
1
- import { o as resolvePath, t as createPath } from "./url-ghfWE9j6.mjs";
1
+ import { o as resolvePath, t as createPath } from "./url-0EHjozDe.mjs";
2
2
  import { SimpleEventEmitter } from "@mary-ext/simple-event-emitter";
3
- //#region src/history/memory.ts
3
+ // src/history/memory.ts
4
4
  const ROOT = {
5
5
  pathname: "/",
6
6
  search: "",
@@ -105,7 +105,7 @@ var MemoryHistory = class {
105
105
  return this.#updates.subscribe(listener);
106
106
  }
107
107
  dispose() {
108
- this.#updates = new SimpleEventEmitter();
108
+ this.#updates.clear();
109
109
  }
110
110
  #nextId() {
111
111
  return `i${this.#idSeq++}`;
@@ -134,5 +134,4 @@ var MemoryHistory = class {
134
134
  this.#updates.emit(update);
135
135
  }
136
136
  };
137
- //#endregion
138
137
  export { MemoryHistory };
@@ -1,4 +1,3 @@
1
- //#region src/history/types.d.ts
2
1
  /**
3
2
  * the type of write that produced a history update.
4
3
  *
@@ -139,5 +138,4 @@ interface History {
139
138
  /** detaches listeners and cleans up resources. */
140
139
  dispose(): void;
141
140
  }
142
- //#endregion
143
141
  export { HistoryLocation as a, HistoryUpdate as c, HistoryListener as i, HistoryAction as n, HistoryNavigateOptions as o, HistoryEntry as r, HistoryScrollBehavior as s, History as t };
@@ -1,4 +1,4 @@
1
- //#region src/url.ts
1
+ // src/url.ts
2
2
  const parsePath = (to) => {
3
3
  let pathname = to;
4
4
  let search = "";
@@ -53,5 +53,4 @@ const createPath = ({ pathname, search, hash }) => {
53
53
  if (hash && hash !== "#") out += hash.startsWith("#") ? hash : `#${hash}`;
54
54
  return out;
55
55
  };
56
- //#endregion
57
56
  export { parsePath as a, encodeSegment as i, decodeRemainder as n, resolvePath as o, encodeRemainder as r, createPath as t };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oomfware/stacker",
3
- "version": "0.2.4",
3
+ "version": "0.2.5",
4
4
  "description": "type-safe stack router for React",
5
5
  "license": "0BSD",
6
6
  "repository": {
@@ -39,29 +39,29 @@
39
39
  "typecheck": "tsc -b"
40
40
  },
41
41
  "dependencies": {
42
- "@mary-ext/simple-event-emitter": "^1.0.2"
42
+ "@mary-ext/simple-event-emitter": "^1.1.0"
43
43
  },
44
44
  "devDependencies": {
45
- "@testing-library/dom": "^10.4.1",
46
- "@testing-library/jest-dom": "^6.9.1",
47
- "@testing-library/react": "^16.3.2",
48
- "@types/node": "^26.1.1",
49
- "@types/react": "^19.2.17",
50
- "@types/react-dom": "^19.2.3",
51
- "@vitejs/plugin-react": "^6.0.3",
52
- "@vitest/browser": "^4.1.10",
53
- "@vitest/browser-playwright": "^4.1.10",
54
- "bumpp": "^11.1.0",
55
- "oxfmt": "^0.59.0",
56
- "oxlint": "^1.74.0",
57
- "oxlint-tsgolint": "^0.25.0",
58
- "playwright": "^1.61.1",
59
- "react": "^19.2.7",
60
- "react-dom": "^19.2.7",
61
- "tsdown": "^0.22.9",
45
+ "@mary-ext/oxlint-rules": "^0.1.2",
46
+ "@testing-library/dom": "^10.4.2",
47
+ "@testing-library/jest-dom": "^7.0.1",
48
+ "@testing-library/react": "^16.3.3",
49
+ "@types/node": "^26.6.6",
50
+ "@types/react": "^19.3.0",
51
+ "@types/react-dom": "^19.3.0",
52
+ "@vitejs/plugin-react": "^6.3.0",
53
+ "@vitest/browser-playwright": "^5.1.0",
54
+ "bumpp": "^12.3.0",
55
+ "oxfmt": "^0.78.0",
56
+ "oxlint": "^1.93.0",
57
+ "oxlint-tsgolint": "^7.0.2007",
58
+ "playwright": "^1.65.1",
59
+ "react": "^19.3.1",
60
+ "react-dom": "^19.3.1",
61
+ "tsdown": "^0.23.7",
62
62
  "typescript": "^7.0.2",
63
- "vite": "^8.1.5",
64
- "vitest": "^4.1.10"
63
+ "vite": "^8.3.8",
64
+ "vitest": "^5.1.0"
65
65
  },
66
66
  "peerDependencies": {
67
67
  "react": ">=19.0.0",