@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.
- package/README.md +16 -16
- package/dist/index.d.mts +73 -95
- package/dist/index.mjs +238 -125
- package/dist/testing.d.mts +5 -7
- package/dist/testing.mjs +19 -20
- package/dist/{types-kax-GwM6.d.mts → types-BUru23Cr.d.mts} +41 -43
- package/dist/{url-DerpiRjh.mjs → url-0EHjozDe.mjs} +6 -7
- package/package.json +69 -68
package/dist/testing.d.mts
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
|
-
import { a as HistoryLocation, i as HistoryListener, o as HistoryNavigateOptions, r as HistoryEntry, t as History } from "./types-
|
|
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
|
-
|
|
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-
|
|
1
|
+
import { o as resolvePath, t as createPath } from "./url-0EHjozDe.mjs";
|
|
2
2
|
import { SimpleEventEmitter } from "@mary-ext/simple-event-emitter";
|
|
3
|
-
|
|
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
|
-
|
|
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
|
|
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 {
|
|
117
|
+
const { pathname, search, hash } = resolvePath(to, base);
|
|
118
118
|
return {
|
|
119
|
-
|
|
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
|
-
/**
|
|
18
|
-
readonly
|
|
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
|
-
/**
|
|
29
|
-
readonly
|
|
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
|
-
*
|
|
122
|
+
* navigates by a delta offset.
|
|
133
123
|
*
|
|
134
|
-
*
|
|
135
|
-
|
|
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
|
|
138
|
-
* @
|
|
134
|
+
* @param listener update callback
|
|
135
|
+
* @returns unsubscribe function
|
|
139
136
|
*/
|
|
140
|
-
|
|
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
|
-
|
|
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 = ({
|
|
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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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
|
+
}
|