@oomfware/stacker 0.2.1 → 0.2.3
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 +18 -0
- package/dist/index.d.mts +22 -2
- package/dist/index.mjs +85 -27
- package/dist/testing.d.mts +3 -2
- package/dist/testing.mjs +16 -2
- package/dist/{types-KOb6CZ7N.d.mts → types-kax-GwM6.d.mts} +15 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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
|
|
@@ -325,6 +333,16 @@ new NavigationHistory({
|
|
|
325
333
|
});
|
|
326
334
|
```
|
|
327
335
|
|
|
336
|
+
### failed navigations
|
|
337
|
+
|
|
338
|
+
`NavigationHistory` sends navigation and render errors to `onError`. it defaults to `reportError`:
|
|
339
|
+
|
|
340
|
+
```ts
|
|
341
|
+
new NavigationHistory({
|
|
342
|
+
onError: (error) => captureException(error),
|
|
343
|
+
});
|
|
344
|
+
```
|
|
345
|
+
|
|
328
346
|
### metadata
|
|
329
347
|
|
|
330
348
|
declare custom route metadata using module augmentation:
|
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-
|
|
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-kax-GwM6.mjs";
|
|
2
2
|
import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
|
|
3
3
|
//#region src/codec.d.ts
|
|
4
4
|
/**
|
|
@@ -322,6 +322,12 @@ interface NavigationHistoryOptions {
|
|
|
322
322
|
* @returns true to leave the navigation to the browser
|
|
323
323
|
*/
|
|
324
324
|
readonly ignore?: (url: URL) => boolean;
|
|
325
|
+
/**
|
|
326
|
+
* handles navigation and render failures. defaults to `Window.reportError`.
|
|
327
|
+
*
|
|
328
|
+
* @param error failure reason
|
|
329
|
+
*/
|
|
330
|
+
readonly onError?: (error: unknown) => void;
|
|
325
331
|
/** window instance to bind to; defaults to global window. */
|
|
326
332
|
readonly window?: Window;
|
|
327
333
|
}
|
|
@@ -340,7 +346,8 @@ declare class NavigationHistory implements History {
|
|
|
340
346
|
entries(): readonly HistoryEntry[];
|
|
341
347
|
push(to: string, options?: HistoryNavigateOptions): void;
|
|
342
348
|
replace(to: string, options?: HistoryNavigateOptions): void;
|
|
343
|
-
|
|
349
|
+
updateState(state: unknown): void;
|
|
350
|
+
traverseTo(key: string): Promise<void>;
|
|
344
351
|
go(delta: number): void;
|
|
345
352
|
back(): void;
|
|
346
353
|
forward(): void;
|
|
@@ -477,6 +484,8 @@ declare class Router<R extends RouteRegistry<unknown>> {
|
|
|
477
484
|
/**
|
|
478
485
|
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
479
486
|
*
|
|
487
|
+
* pushes the destination if traversal to a matching entry fails.
|
|
488
|
+
*
|
|
480
489
|
* @param to route target, or a relative URL resolved against the active location
|
|
481
490
|
*/
|
|
482
491
|
popTo(to: RouteTarget<R> | string): void;
|
|
@@ -491,6 +500,17 @@ declare class Router<R extends RouteRegistry<unknown>> {
|
|
|
491
500
|
* @throws when `name` is not the active route
|
|
492
501
|
*/
|
|
493
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;
|
|
494
514
|
/** navigates back one entry. */
|
|
495
515
|
back(): void;
|
|
496
516
|
/** navigates forward one entry. */
|
package/dist/index.mjs
CHANGED
|
@@ -388,10 +388,7 @@ const toAction = (type) => {
|
|
|
388
388
|
default: return;
|
|
389
389
|
}
|
|
390
390
|
};
|
|
391
|
-
const
|
|
392
|
-
result.committed?.catch(() => {});
|
|
393
|
-
result.finished?.catch(() => {});
|
|
394
|
-
};
|
|
391
|
+
const isAbort = (error) => typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
|
|
395
392
|
/**
|
|
396
393
|
* history implementation backed by the web navigation API.
|
|
397
394
|
*
|
|
@@ -399,17 +396,24 @@ const ignore = (result) => {
|
|
|
399
396
|
* metadata and indices are managed natively by the browser.
|
|
400
397
|
*/
|
|
401
398
|
var NavigationHistory = class {
|
|
402
|
-
#win;
|
|
403
|
-
#nav;
|
|
404
399
|
#ignore;
|
|
405
400
|
#listeners = /* @__PURE__ */ new Set();
|
|
401
|
+
#nav;
|
|
402
|
+
#onError;
|
|
403
|
+
#win;
|
|
404
|
+
#disposed = false;
|
|
406
405
|
#location;
|
|
407
406
|
constructor(options = {}) {
|
|
408
407
|
this.#win = options.window ?? window;
|
|
409
408
|
this.#nav = this.#win.navigation;
|
|
410
409
|
this.#ignore = options.ignore;
|
|
410
|
+
this.#onError = options.onError ?? ((error) => {
|
|
411
|
+
this.#win.reportError(error);
|
|
412
|
+
});
|
|
411
413
|
this.#location = this.#read();
|
|
414
|
+
this.#nav.addEventListener("currententrychange", this.#onCurrentEntryChange);
|
|
412
415
|
this.#nav.addEventListener("navigate", this.#onNavigate);
|
|
416
|
+
this.#nav.addEventListener("navigateerror", this.#onNavigateError);
|
|
413
417
|
this.#win.history.scrollRestoration = "manual";
|
|
414
418
|
}
|
|
415
419
|
get location() {
|
|
@@ -437,20 +441,23 @@ var NavigationHistory = class {
|
|
|
437
441
|
replace(to, options = {}) {
|
|
438
442
|
this.#navigate(to, "replace", options);
|
|
439
443
|
}
|
|
444
|
+
updateState(state) {
|
|
445
|
+
this.#nav.updateCurrentEntry({ state });
|
|
446
|
+
}
|
|
440
447
|
traverseTo(key) {
|
|
441
|
-
|
|
448
|
+
return this.#track(this.#nav.traverseTo(key));
|
|
442
449
|
}
|
|
443
450
|
go(delta) {
|
|
444
451
|
const entries = this.#nav.entries();
|
|
445
452
|
const target = entries[Math.max(0, Math.min(this.#location.index + delta, entries.length - 1))];
|
|
446
453
|
if (target === void 0 || target.key === this.#location.key) return;
|
|
447
|
-
this.traverseTo(target.key);
|
|
454
|
+
this.#report(this.traverseTo(target.key));
|
|
448
455
|
}
|
|
449
456
|
back() {
|
|
450
|
-
if (this.#nav.canGoBack)
|
|
457
|
+
if (this.#nav.canGoBack) this.#report(this.#track(this.#nav.back()));
|
|
451
458
|
}
|
|
452
459
|
forward() {
|
|
453
|
-
if (this.#nav.canGoForward)
|
|
460
|
+
if (this.#nav.canGoForward) this.#report(this.#track(this.#nav.forward()));
|
|
454
461
|
}
|
|
455
462
|
listen(listener) {
|
|
456
463
|
this.#listeners.add(listener);
|
|
@@ -459,9 +466,28 @@ var NavigationHistory = class {
|
|
|
459
466
|
};
|
|
460
467
|
}
|
|
461
468
|
dispose() {
|
|
469
|
+
this.#disposed = true;
|
|
470
|
+
this.#nav.removeEventListener("currententrychange", this.#onCurrentEntryChange);
|
|
462
471
|
this.#nav.removeEventListener("navigate", this.#onNavigate);
|
|
472
|
+
this.#nav.removeEventListener("navigateerror", this.#onNavigateError);
|
|
463
473
|
this.#listeners.clear();
|
|
464
474
|
}
|
|
475
|
+
#track(result) {
|
|
476
|
+
result.finished?.catch(() => {});
|
|
477
|
+
return result.committed?.then(() => void 0) ?? Promise.resolve();
|
|
478
|
+
}
|
|
479
|
+
#fail(error) {
|
|
480
|
+
if (this.#disposed || isAbort(error)) return;
|
|
481
|
+
this.#onError(error);
|
|
482
|
+
}
|
|
483
|
+
async #notify(update) {
|
|
484
|
+
await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
|
|
485
|
+
}
|
|
486
|
+
#report(work) {
|
|
487
|
+
work.catch((error) => {
|
|
488
|
+
this.#fail(error);
|
|
489
|
+
});
|
|
490
|
+
}
|
|
465
491
|
#navigate(to, history, options) {
|
|
466
492
|
const url = new URL(to, this.#win.location.href).href;
|
|
467
493
|
const envelope = {
|
|
@@ -469,11 +495,11 @@ var NavigationHistory = class {
|
|
|
469
495
|
info: options.info,
|
|
470
496
|
scroll: options.scroll ?? "auto"
|
|
471
497
|
};
|
|
472
|
-
|
|
498
|
+
this.#report(this.#track(this.#nav.navigate(url, {
|
|
473
499
|
history,
|
|
474
500
|
info: envelope,
|
|
475
501
|
state: options.state ?? null
|
|
476
|
-
}));
|
|
502
|
+
})));
|
|
477
503
|
}
|
|
478
504
|
#read() {
|
|
479
505
|
const entry = this.#nav.currentEntry;
|
|
@@ -489,6 +515,16 @@ var NavigationHistory = class {
|
|
|
489
515
|
state: entry.getState()
|
|
490
516
|
};
|
|
491
517
|
}
|
|
518
|
+
#onCurrentEntryChange = (event) => {
|
|
519
|
+
if (event.navigationType !== null) return;
|
|
520
|
+
this.#location = this.#read();
|
|
521
|
+
this.#report(this.#notify({
|
|
522
|
+
action: "update",
|
|
523
|
+
info: void 0,
|
|
524
|
+
location: this.#location,
|
|
525
|
+
scroll: "preserve"
|
|
526
|
+
}));
|
|
527
|
+
};
|
|
492
528
|
#onNavigate = (event) => {
|
|
493
529
|
const action = toAction(event.navigationType);
|
|
494
530
|
if (action === void 0 || !event.canIntercept) return;
|
|
@@ -503,16 +539,19 @@ var NavigationHistory = class {
|
|
|
503
539
|
scroll: "manual",
|
|
504
540
|
handler: async () => {
|
|
505
541
|
this.#location = this.#read();
|
|
506
|
-
|
|
542
|
+
await this.#notify({
|
|
507
543
|
action,
|
|
508
544
|
info,
|
|
509
545
|
location: this.#location,
|
|
510
546
|
scroll
|
|
511
|
-
};
|
|
512
|
-
await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
|
|
547
|
+
});
|
|
513
548
|
}
|
|
514
549
|
});
|
|
515
550
|
};
|
|
551
|
+
#onNavigateError = (event) => {
|
|
552
|
+
const error = event.error;
|
|
553
|
+
this.#fail(error);
|
|
554
|
+
};
|
|
516
555
|
};
|
|
517
556
|
const toRelative = (url) => {
|
|
518
557
|
if (url === null) return null;
|
|
@@ -612,18 +651,14 @@ var Builder = class {
|
|
|
612
651
|
};
|
|
613
652
|
//#endregion
|
|
614
653
|
//#region src/cache.ts
|
|
615
|
-
/**
|
|
616
|
-
|
|
617
|
-
*
|
|
618
|
-
* retains the active entry plus backward entries using an LRU policy. forward entries are dropped.
|
|
619
|
-
*/
|
|
620
|
-
const computeCachedKeys = (entries, activeIndex, recency, policy) => {
|
|
654
|
+
/** selects the active entry and recent backward entries for caching. */
|
|
655
|
+
const computeCachedKeys = (entries, activeKey, recency, policy) => {
|
|
621
656
|
const cached = /* @__PURE__ */ new Set();
|
|
622
|
-
const active = entries.find((entry) => entry.
|
|
623
|
-
if (active === void 0) throw new Error(`stacker: no history entry
|
|
657
|
+
const active = entries.find((entry) => entry.key === activeKey);
|
|
658
|
+
if (active === void 0) throw new Error(`stacker: no history entry with the active key '${activeKey}'`);
|
|
624
659
|
cached.add(active.key);
|
|
625
660
|
const backward = /* @__PURE__ */ new Map();
|
|
626
|
-
for (const entry of entries) if (entry.index <
|
|
661
|
+
for (const entry of entries) if (entry.index < active.index) backward.set(entry.key, entry);
|
|
627
662
|
let kept = 0;
|
|
628
663
|
const take = (key) => {
|
|
629
664
|
if (kept >= policy.max || cached.has(key) || !backward.has(key)) return;
|
|
@@ -748,6 +783,10 @@ var Router = class {
|
|
|
748
783
|
this.#record(location, TOP);
|
|
749
784
|
this.#view = this.#recompute();
|
|
750
785
|
this.#unlisten = this.#history.listen(async ({ action, location: next, scroll }) => {
|
|
786
|
+
if (action === "update") {
|
|
787
|
+
this.#updates.emit();
|
|
788
|
+
return;
|
|
789
|
+
}
|
|
751
790
|
const win = this.#win;
|
|
752
791
|
const restoring = scroll === "auto" && win !== null;
|
|
753
792
|
if (restoring) {
|
|
@@ -861,6 +900,8 @@ var Router = class {
|
|
|
861
900
|
/**
|
|
862
901
|
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
863
902
|
*
|
|
903
|
+
* pushes the destination if traversal to a matching entry fails.
|
|
904
|
+
*
|
|
864
905
|
* @param to route target, or a relative URL resolved against the active location
|
|
865
906
|
*/
|
|
866
907
|
popTo(to) {
|
|
@@ -870,13 +911,17 @@ var Router = class {
|
|
|
870
911
|
if (wantedMatch !== void 0) {
|
|
871
912
|
const wanted = this.#canonical(wantedMatch);
|
|
872
913
|
const entries = this.#history.entries();
|
|
873
|
-
|
|
914
|
+
const from = this.#history.location.key;
|
|
915
|
+
const start = entries.findIndex((entry) => entry.key === from);
|
|
916
|
+
for (let i = start; i >= 0; i--) {
|
|
874
917
|
const entry = entries[i];
|
|
875
918
|
if (entry === void 0 || !entry.sameDocument || entry.url === null) break;
|
|
876
919
|
const parts = parsePath(entry.url);
|
|
877
920
|
const match = this.#matcher.match(parts.pathname, parts.search, parts.hash);
|
|
878
921
|
if (match !== void 0 && match.name === wantedMatch.name && this.#canonical(match) === wanted) {
|
|
879
|
-
this.#history.traverseTo(entry.key)
|
|
922
|
+
this.#history.traverseTo(entry.key).catch(() => {
|
|
923
|
+
if (this.#history.location.key === from) this.#history.push(url);
|
|
924
|
+
});
|
|
880
925
|
return;
|
|
881
926
|
}
|
|
882
927
|
}
|
|
@@ -917,6 +962,19 @@ var Router = class {
|
|
|
917
962
|
state: location.state
|
|
918
963
|
});
|
|
919
964
|
}
|
|
965
|
+
/**
|
|
966
|
+
* rewrites the active history entry's state, without navigating.
|
|
967
|
+
*
|
|
968
|
+
* the entry keeps its URL and slot, so the screen stays mounted and the viewport does not move. the whole
|
|
969
|
+
* state is replaced, so build the next value from `router.location.state` to keep the parts you still want.
|
|
970
|
+
* readers of `useLocation` re-render with it.
|
|
971
|
+
*
|
|
972
|
+
* @param state state data to store on the entry
|
|
973
|
+
* @throws when the state cannot be structured-cloned, leaving the entry as it was
|
|
974
|
+
*/
|
|
975
|
+
updateState(state) {
|
|
976
|
+
this.#history.updateState(state);
|
|
977
|
+
}
|
|
920
978
|
/** navigates back one entry. */
|
|
921
979
|
back() {
|
|
922
980
|
this.#history.back();
|
|
@@ -1009,7 +1067,7 @@ var Router = class {
|
|
|
1009
1067
|
const cachedKeys = computeCachedKeys([...this.#entries.values()].map((entry) => ({
|
|
1010
1068
|
index: entry.index,
|
|
1011
1069
|
key: entry.key
|
|
1012
|
-
})), active.
|
|
1070
|
+
})), active.key, this.#recency, { max: this.#max });
|
|
1013
1071
|
const cached = [];
|
|
1014
1072
|
for (const entry of this.#entries.values()) if (cachedKeys.has(entry.key)) cached.push({
|
|
1015
1073
|
key: entry.key,
|
package/dist/testing.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-
|
|
1
|
+
import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-kax-GwM6.mjs";
|
|
2
2
|
//#region src/history/memory.d.ts
|
|
3
3
|
/** options for the memory history constructor. */
|
|
4
4
|
interface MemoryHistoryOptions {
|
|
@@ -22,7 +22,8 @@ declare class MemoryHistory implements History {
|
|
|
22
22
|
entries(): readonly HistoryEntry[];
|
|
23
23
|
push(to: string, options?: HistoryNavigateOptions): void;
|
|
24
24
|
replace(to: string, options?: HistoryNavigateOptions): void;
|
|
25
|
-
|
|
25
|
+
updateState(state: unknown): void;
|
|
26
|
+
traverseTo(key: string): Promise<void>;
|
|
26
27
|
go(delta: number): void;
|
|
27
28
|
back(): void;
|
|
28
29
|
forward(): void;
|
package/dist/testing.mjs
CHANGED
|
@@ -65,10 +65,24 @@ var MemoryHistory = class {
|
|
|
65
65
|
scroll: options.scroll ?? "auto"
|
|
66
66
|
});
|
|
67
67
|
}
|
|
68
|
+
updateState(state) {
|
|
69
|
+
const location = {
|
|
70
|
+
...this.#current(),
|
|
71
|
+
state: structuredClone(state)
|
|
72
|
+
};
|
|
73
|
+
this.#entries = this.#entries.with(this.#index, location);
|
|
74
|
+
this.#emit({
|
|
75
|
+
action: "update",
|
|
76
|
+
info: void 0,
|
|
77
|
+
location,
|
|
78
|
+
scroll: "preserve"
|
|
79
|
+
});
|
|
80
|
+
}
|
|
68
81
|
traverseTo(key) {
|
|
69
82
|
const index = this.#entries.findIndex((entry) => entry.key === key);
|
|
70
|
-
if (index === -1)
|
|
83
|
+
if (index === -1) return Promise.reject(/* @__PURE__ */ new Error(`stacker: no history entry with key '${key}'`));
|
|
71
84
|
this.go(index - this.#index);
|
|
85
|
+
return Promise.resolve();
|
|
72
86
|
}
|
|
73
87
|
go(delta) {
|
|
74
88
|
const next = Math.max(0, Math.min(this.#index + delta, this.#entries.length - 1));
|
|
@@ -108,7 +122,7 @@ var MemoryHistory = class {
|
|
|
108
122
|
key,
|
|
109
123
|
pathname,
|
|
110
124
|
search,
|
|
111
|
-
state
|
|
125
|
+
state: structuredClone(state)
|
|
112
126
|
};
|
|
113
127
|
}
|
|
114
128
|
#current() {
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
//#region src/history/types.d.ts
|
|
2
2
|
/**
|
|
3
|
-
* the type of
|
|
3
|
+
* the type of write that produced a history update.
|
|
4
4
|
*
|
|
5
5
|
* - `push` — a new entry was added.
|
|
6
6
|
* - `replace` — the active entry was replaced.
|
|
7
7
|
* - `traverse` — navigation occurred to an existing entry.
|
|
8
|
+
* - `update` — the active entry's state was rewritten in place, without navigating.
|
|
8
9
|
*/
|
|
9
|
-
type HistoryAction = 'push' | 'replace' | 'traverse';
|
|
10
|
+
type HistoryAction = 'push' | 'replace' | 'traverse' | 'update';
|
|
10
11
|
/** an entry in the browser session history ledger. */
|
|
11
12
|
interface HistoryEntry {
|
|
12
13
|
/** unique per-revision identifier. */
|
|
@@ -124,8 +125,19 @@ interface History {
|
|
|
124
125
|
* navigates to an existing entry by key.
|
|
125
126
|
*
|
|
126
127
|
* @param key target entry key
|
|
128
|
+
* @returns promise that resolves on commit and rejects if traversal fails
|
|
127
129
|
*/
|
|
128
|
-
traverseTo(key: string): void
|
|
130
|
+
traverseTo(key: string): Promise<void>;
|
|
131
|
+
/**
|
|
132
|
+
* rewrites the state of the active entry in place, without navigating.
|
|
133
|
+
*
|
|
134
|
+
* the entry keeps its id, key and URL, so no revision is minted and the user's place on the page is left
|
|
135
|
+
* alone. listeners are notified with the `update` action, since the caller is only ever one of them.
|
|
136
|
+
*
|
|
137
|
+
* @param state state data to store on the entry, replacing whatever is there
|
|
138
|
+
* @throws when the state cannot be structured-cloned
|
|
139
|
+
*/
|
|
140
|
+
updateState(state: unknown): void;
|
|
129
141
|
}
|
|
130
142
|
//#endregion
|
|
131
143
|
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 };
|