@oomfware/stacker 0.2.3 → 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.
@@ -1,11 +1,10 @@
1
- import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-kax-GwM6.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
- /** initially active entry index. */
6
- readonly index?: number;
7
4
  /** initial entry relative URLs. */
8
5
  readonly initialEntries?: readonly string[];
6
+ /** initially active entry index. */
7
+ readonly index?: number;
9
8
  }
10
9
  /**
11
10
  * in-memory history manager for testing.
@@ -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,10 +1,10 @@
1
- import { o as resolvePath, t as createPath } from "./url-DerpiRjh.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
- hash: "",
6
5
  pathname: "/",
7
- search: ""
6
+ search: "",
7
+ hash: ""
8
8
  };
9
9
  /**
10
10
  * in-memory history manager for testing.
@@ -34,12 +34,12 @@ var MemoryHistory = class {
34
34
  }
35
35
  entries() {
36
36
  return this.#entries.map((location) => ({
37
+ key: location.key,
37
38
  id: location.id,
38
39
  index: location.index,
39
- key: location.key,
40
+ url: createPath(location),
40
41
  sameDocument: true,
41
- state: location.state,
42
- url: createPath(location)
42
+ state: location.state
43
43
  }));
44
44
  }
45
45
  push(to, options = {}) {
@@ -49,9 +49,9 @@ var MemoryHistory = class {
49
49
  this.#entries = [...this.#entries.slice(0, this.#index), location];
50
50
  this.#emit({
51
51
  action: "push",
52
- info: options.info,
53
52
  location,
54
- scroll: options.scroll ?? "auto"
53
+ scroll: options.scroll ?? "auto",
54
+ info: options.info
55
55
  });
56
56
  }
57
57
  replace(to, options = {}) {
@@ -60,9 +60,9 @@ var MemoryHistory = class {
60
60
  this.#entries = this.#entries.with(this.#index, location);
61
61
  this.#emit({
62
62
  action: "replace",
63
- info: options.info,
64
63
  location,
65
- scroll: options.scroll ?? "auto"
64
+ scroll: options.scroll ?? "auto",
65
+ info: options.info
66
66
  });
67
67
  }
68
68
  updateState(state) {
@@ -73,9 +73,9 @@ var MemoryHistory = class {
73
73
  this.#entries = this.#entries.with(this.#index, location);
74
74
  this.#emit({
75
75
  action: "update",
76
- info: void 0,
77
76
  location,
78
- scroll: "preserve"
77
+ scroll: "preserve",
78
+ info: void 0
79
79
  });
80
80
  }
81
81
  traverseTo(key) {
@@ -90,9 +90,9 @@ var MemoryHistory = class {
90
90
  this.#index = next;
91
91
  this.#emit({
92
92
  action: "traverse",
93
- info: void 0,
94
93
  location: this.#current(),
95
- scroll: "auto"
94
+ scroll: "auto",
95
+ info: void 0
96
96
  });
97
97
  }
98
98
  back() {
@@ -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++}`;
@@ -114,14 +114,14 @@ var MemoryHistory = class {
114
114
  return `k${this.#keySeq++}`;
115
115
  }
116
116
  #make(to, base, id, key, index, state) {
117
- const { hash, pathname, search } = resolvePath(to, base);
117
+ const { pathname, search, hash } = resolvePath(to, base);
118
118
  return {
119
- hash,
119
+ key,
120
120
  id,
121
121
  index,
122
- key,
123
122
  pathname,
124
123
  search,
124
+ hash,
125
125
  state: structuredClone(state)
126
126
  };
127
127
  }
@@ -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
  *
@@ -10,33 +9,33 @@
10
9
  type HistoryAction = 'push' | 'replace' | 'traverse' | 'update';
11
10
  /** an entry in the browser session history ledger. */
12
11
  interface HistoryEntry {
12
+ /** slot identity preserved across replacements. */
13
+ readonly key: string;
13
14
  /** unique per-revision identifier. */
14
15
  readonly id: string;
15
16
  /** entry position in the ledger. */
16
17
  readonly index: number;
17
- /** slot identity preserved across replacements. */
18
- readonly key: string;
18
+ /** entry URL or null if hidden. */
19
+ readonly url: string | null;
19
20
  /** whether traversal to this entry stays within the current document. */
20
21
  readonly sameDocument: boolean;
21
22
  /** state associated with the entry. */
22
23
  readonly state: unknown;
23
- /** entry URL or null if hidden. */
24
- readonly url: string | null;
25
24
  }
26
25
  /** active history entry with parsed URL components. */
27
26
  interface HistoryLocation {
28
- /** URL fragment including the leading hash symbol. */
29
- readonly hash: string;
27
+ /** slot identity. */
28
+ readonly key: string;
30
29
  /** per-revision identifier. */
31
30
  readonly id: string;
32
31
  /** entry position in the ledger. */
33
32
  readonly index: number;
34
- /** slot identity. */
35
- readonly key: string;
36
33
  /** URL pathname starting with a slash. */
37
34
  readonly pathname: string;
38
35
  /** URL query string including the leading question mark. */
39
36
  readonly search: string;
37
+ /** URL fragment including the leading hash symbol. */
38
+ readonly hash: string;
40
39
  /** state associated with the entry. */
41
40
  readonly state: unknown;
42
41
  }
@@ -52,21 +51,21 @@ interface HistoryLocation {
52
51
  type HistoryScrollBehavior = 'auto' | 'preserve';
53
52
  /** options for history write operations. */
54
53
  interface HistoryNavigateOptions {
55
- /** arbitrary metadata passed to history listeners. */
56
- readonly info?: unknown;
57
- /** scroll and focus behavior. */
58
- readonly scroll?: HistoryScrollBehavior;
59
54
  /** state data associated with the entry. */
60
55
  readonly state?: unknown;
56
+ /** scroll and focus behavior. */
57
+ readonly scroll?: HistoryScrollBehavior;
58
+ /** arbitrary metadata passed to history listeners. */
59
+ readonly info?: unknown;
61
60
  }
62
61
  /** history update details dispatched to listeners. */
63
62
  interface HistoryUpdate {
64
63
  readonly action: HistoryAction;
65
- /** metadata passed to the write operation. */
66
- readonly info: unknown;
67
64
  readonly location: HistoryLocation;
68
65
  /** viewport behavior, which listeners apply. */
69
66
  readonly scroll: HistoryScrollBehavior;
67
+ /** metadata passed to the write operation. */
68
+ readonly info: unknown;
70
69
  }
71
70
  /**
72
71
  * history update callback subscriber.
@@ -76,37 +75,18 @@ interface HistoryUpdate {
76
75
  type HistoryListener = (update: HistoryUpdate) => void | Promise<void>;
77
76
  /** history manager interface modeled on the web navigation API. */
78
77
  interface History {
78
+ /** active history location. */
79
+ readonly location: HistoryLocation;
79
80
  /** whether a backward entry exists. */
80
81
  readonly canGoBack: boolean;
81
82
  /** whether a forward entry exists. */
82
83
  readonly canGoForward: boolean;
83
- /** active history location. */
84
- readonly location: HistoryLocation;
85
- /** navigates back one entry. */
86
- back(): void;
87
- /** detaches listeners and cleans up resources. */
88
- dispose(): void;
89
84
  /**
90
85
  * lists all entries in the ledger.
91
86
  *
92
87
  * @returns array of history entries
93
88
  */
94
89
  entries(): readonly HistoryEntry[];
95
- /** navigates forward one entry. */
96
- forward(): void;
97
- /**
98
- * navigates by a delta offset.
99
- *
100
- * @param delta number of entries to move
101
- */
102
- go(delta: number): void;
103
- /**
104
- * subscribes to history updates.
105
- *
106
- * @param listener update callback
107
- * @returns unsubscribe function
108
- */
109
- listen(listener: HistoryListener): () => void;
110
90
  /**
111
91
  * pushes a new history entry.
112
92
  *
@@ -121,6 +101,16 @@ interface History {
121
101
  * @param options navigation options
122
102
  */
123
103
  replace(to: string, options?: HistoryNavigateOptions): void;
104
+ /**
105
+ * rewrites the state of the active entry in place, without navigating.
106
+ *
107
+ * the entry keeps its id, key and URL, so no revision is minted and the user's place on the page is left
108
+ * alone. listeners are notified with the `update` action, since the caller is only ever one of them.
109
+ *
110
+ * @param state state data to store on the entry, replacing whatever is there
111
+ * @throws when the state cannot be structured-cloned
112
+ */
113
+ updateState(state: unknown): void;
124
114
  /**
125
115
  * navigates to an existing entry by key.
126
116
  *
@@ -129,15 +119,23 @@ interface History {
129
119
  */
130
120
  traverseTo(key: string): Promise<void>;
131
121
  /**
132
- * rewrites the state of the active entry in place, without navigating.
122
+ * navigates by a delta offset.
133
123
  *
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.
124
+ * @param delta number of entries to move
125
+ */
126
+ go(delta: number): void;
127
+ /** navigates back one entry. */
128
+ back(): void;
129
+ /** navigates forward one entry. */
130
+ forward(): void;
131
+ /**
132
+ * subscribes to history updates.
136
133
  *
137
- * @param state state data to store on the entry, replacing whatever is there
138
- * @throws when the state cannot be structured-cloned
134
+ * @param listener update callback
135
+ * @returns unsubscribe function
139
136
  */
140
- updateState(state: unknown): void;
137
+ listen(listener: HistoryListener): () => void;
138
+ /** detaches listeners and cleans up resources. */
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 = "";
@@ -14,17 +14,17 @@ const parsePath = (to) => {
14
14
  pathname = pathname.slice(0, searchIndex);
15
15
  }
16
16
  return {
17
- hash,
18
17
  pathname,
19
- search
18
+ search,
19
+ hash
20
20
  };
21
21
  };
22
22
  const resolvePath = (to, base) => {
23
23
  const resolved = new URL(to, `http://_${createPath(base)}`);
24
24
  return {
25
- hash: resolved.hash,
26
25
  pathname: resolved.pathname,
27
- search: resolved.search
26
+ search: resolved.search,
27
+ hash: resolved.hash
28
28
  };
29
29
  };
30
30
  const OUTSIDE_PCHAR = /[^\w!$&'()*+,\-.:;=@~]+/gu;
@@ -47,11 +47,10 @@ const decodeRemainder = (raw) => raw.split("/").map(decodeURIComponent).join("/"
47
47
  const encodeRemainder = (value) => {
48
48
  return value.split("/").map((segment) => encodeSegment(segment)).join("/");
49
49
  };
50
- const createPath = ({ hash, pathname, search }) => {
50
+ const createPath = ({ pathname, search, hash }) => {
51
51
  let out = pathname || "/";
52
52
  if (search && search !== "?") out += search.startsWith("?") ? search : `?${search}`;
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,69 +1,70 @@
1
1
  {
2
- "name": "@oomfware/stacker",
3
- "version": "0.2.3",
4
- "description": "type-safe stack router for React",
5
- "license": "0BSD",
6
- "repository": {
7
- "type": "git",
8
- "url": "https://codeberg.org/oomfware/stacker"
9
- },
10
- "files": [
11
- "dist/"
12
- ],
13
- "type": "module",
14
- "types": "./dist/index.d.mts",
15
- "exports": {
16
- ".": {
17
- "types": "./dist/index.d.mts",
18
- "default": "./dist/index.mjs"
19
- },
20
- "./testing": {
21
- "types": "./dist/testing.d.mts",
22
- "default": "./dist/testing.mjs"
23
- },
24
- "./package.json": "./package.json"
25
- },
26
- "publishConfig": {
27
- "access": "public"
28
- },
29
- "dependencies": {
30
- "@mary-ext/simple-event-emitter": "^1.0.2"
31
- },
32
- "devDependencies": {
33
- "@testing-library/dom": "^10.4.1",
34
- "@testing-library/jest-dom": "^6.9.1",
35
- "@testing-library/react": "^16.3.2",
36
- "@types/node": "^26.1.1",
37
- "@types/react": "^19.2.17",
38
- "@types/react-dom": "^19.2.3",
39
- "@vitejs/plugin-react": "^6.0.3",
40
- "@vitest/browser": "^4.1.10",
41
- "@vitest/browser-playwright": "^4.1.10",
42
- "bumpp": "^11.1.0",
43
- "oxfmt": "^0.59.0",
44
- "oxlint": "^1.74.0",
45
- "oxlint-tsgolint": "^0.25.0",
46
- "playwright": "^1.61.1",
47
- "react": "^19.2.7",
48
- "react-dom": "^19.2.7",
49
- "tsdown": "^0.22.9",
50
- "typescript": "^7.0.2",
51
- "vite": "^8.1.5",
52
- "vitest": "^4.1.10"
53
- },
54
- "peerDependencies": {
55
- "react": ">=19.0.0",
56
- "react-dom": ">=19.0.0"
57
- },
58
- "scripts": {
59
- "build": "oxlint && tsdown",
60
- "dev": "tsdown --watch",
61
- "fmt": "oxfmt",
62
- "lint": "oxlint",
63
- "play": "vite",
64
- "test": "vitest run",
65
- "test:types": "vitest run --typecheck.only",
66
- "test:watch": "vitest",
67
- "typecheck": "tsc -b"
68
- }
69
- }
2
+ "name": "@oomfware/stacker",
3
+ "version": "0.2.5",
4
+ "description": "type-safe stack router for React",
5
+ "license": "0BSD",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://codeberg.org/oomfware/stacker"
9
+ },
10
+ "files": [
11
+ "dist/"
12
+ ],
13
+ "type": "module",
14
+ "types": "./dist/index.d.mts",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./dist/index.d.mts",
18
+ "default": "./dist/index.mjs"
19
+ },
20
+ "./testing": {
21
+ "types": "./dist/testing.d.mts",
22
+ "default": "./dist/testing.mjs"
23
+ },
24
+ "./package.json": "./package.json"
25
+ },
26
+ "publishConfig": {
27
+ "access": "public"
28
+ },
29
+ "scripts": {
30
+ "build": "oxlint && tsdown",
31
+ "dev": "tsdown --watch",
32
+ "fmt": "oxfmt",
33
+ "lint": "oxlint",
34
+ "play": "vite",
35
+ "prepublishOnly": "pnpm run build",
36
+ "test": "vitest run",
37
+ "test:types": "vitest run --typecheck.only",
38
+ "test:watch": "vitest",
39
+ "typecheck": "tsc -b"
40
+ },
41
+ "dependencies": {
42
+ "@mary-ext/simple-event-emitter": "^1.1.0"
43
+ },
44
+ "devDependencies": {
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
+ "typescript": "^7.0.2",
63
+ "vite": "^8.3.8",
64
+ "vitest": "^5.1.0"
65
+ },
66
+ "peerDependencies": {
67
+ "react": ">=19.0.0",
68
+ "react-dom": ">=19.0.0"
69
+ }
70
+ }