@oomfware/stacker 0.2.2 → 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 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
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-kax-GwM6.mjs";
2
2
  import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
3
3
  //#region src/codec.d.ts
4
4
  /**
@@ -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;
@@ -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. */
package/dist/index.mjs CHANGED
@@ -411,6 +411,7 @@ var NavigationHistory = class {
411
411
  this.#win.reportError(error);
412
412
  });
413
413
  this.#location = this.#read();
414
+ this.#nav.addEventListener("currententrychange", this.#onCurrentEntryChange);
414
415
  this.#nav.addEventListener("navigate", this.#onNavigate);
415
416
  this.#nav.addEventListener("navigateerror", this.#onNavigateError);
416
417
  this.#win.history.scrollRestoration = "manual";
@@ -440,6 +441,9 @@ var NavigationHistory = class {
440
441
  replace(to, options = {}) {
441
442
  this.#navigate(to, "replace", options);
442
443
  }
444
+ updateState(state) {
445
+ this.#nav.updateCurrentEntry({ state });
446
+ }
443
447
  traverseTo(key) {
444
448
  return this.#track(this.#nav.traverseTo(key));
445
449
  }
@@ -463,6 +467,7 @@ var NavigationHistory = class {
463
467
  }
464
468
  dispose() {
465
469
  this.#disposed = true;
470
+ this.#nav.removeEventListener("currententrychange", this.#onCurrentEntryChange);
466
471
  this.#nav.removeEventListener("navigate", this.#onNavigate);
467
472
  this.#nav.removeEventListener("navigateerror", this.#onNavigateError);
468
473
  this.#listeners.clear();
@@ -475,8 +480,11 @@ var NavigationHistory = class {
475
480
  if (this.#disposed || isAbort(error)) return;
476
481
  this.#onError(error);
477
482
  }
478
- #report(committed) {
479
- committed.catch((error) => {
483
+ async #notify(update) {
484
+ await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
485
+ }
486
+ #report(work) {
487
+ work.catch((error) => {
480
488
  this.#fail(error);
481
489
  });
482
490
  }
@@ -507,6 +515,16 @@ var NavigationHistory = class {
507
515
  state: entry.getState()
508
516
  };
509
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
+ };
510
528
  #onNavigate = (event) => {
511
529
  const action = toAction(event.navigationType);
512
530
  if (action === void 0 || !event.canIntercept) return;
@@ -521,13 +539,12 @@ var NavigationHistory = class {
521
539
  scroll: "manual",
522
540
  handler: async () => {
523
541
  this.#location = this.#read();
524
- const update = {
542
+ await this.#notify({
525
543
  action,
526
544
  info,
527
545
  location: this.#location,
528
546
  scroll
529
- };
530
- await Promise.all([...this.#listeners].map(async (listener) => listener(update)));
547
+ });
531
548
  }
532
549
  });
533
550
  };
@@ -766,6 +783,10 @@ var Router = class {
766
783
  this.#record(location, TOP);
767
784
  this.#view = this.#recompute();
768
785
  this.#unlisten = this.#history.listen(async ({ action, location: next, scroll }) => {
786
+ if (action === "update") {
787
+ this.#updates.emit();
788
+ return;
789
+ }
769
790
  const win = this.#win;
770
791
  const restoring = scroll === "auto" && win !== null;
771
792
  if (restoring) {
@@ -941,6 +962,19 @@ var Router = class {
941
962
  state: location.state
942
963
  });
943
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
+ }
944
978
  /** navigates back one entry. */
945
979
  back() {
946
980
  this.#history.back();
@@ -1,4 +1,4 @@
1
- import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-Bo4ESWAT.mjs";
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,6 +22,7 @@ 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
+ updateState(state: unknown): void;
25
26
  traverseTo(key: string): Promise<void>;
26
27
  go(delta: number): void;
27
28
  back(): void;
package/dist/testing.mjs CHANGED
@@ -65,6 +65,19 @@ 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
83
  if (index === -1) return Promise.reject(/* @__PURE__ */ new Error(`stacker: no history entry with key '${key}'`));
@@ -109,7 +122,7 @@ var MemoryHistory = class {
109
122
  key,
110
123
  pathname,
111
124
  search,
112
- state
125
+ state: structuredClone(state)
113
126
  };
114
127
  }
115
128
  #current() {
@@ -1,12 +1,13 @@
1
1
  //#region src/history/types.d.ts
2
2
  /**
3
- * the type of navigation that produced a history update.
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. */
@@ -127,6 +128,16 @@ interface History {
127
128
  * @returns promise that resolves on commit and rejects if traversal fails
128
129
  */
129
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;
130
141
  }
131
142
  //#endregion
132
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 };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oomfware/stacker",
3
- "version": "0.2.2",
3
+ "version": "0.2.3",
4
4
  "description": "type-safe stack router for React",
5
5
  "license": "0BSD",
6
6
  "repository": {