@oomfware/stacker 0.2.2 → 0.2.4
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 +23 -15
- package/dist/index.d.mts +61 -49
- package/dist/index.mjs +143 -84
- package/dist/testing.d.mts +4 -3
- package/dist/testing.mjs +29 -16
- package/dist/{types-Bo4ESWAT.d.mts → types--iOZjfC1.d.mts} +48 -37
- package/dist/{url-DerpiRjh.mjs → url-ghfWE9j6.mjs} +5 -5
- package/package.json +69 -68
|
@@ -1,41 +1,42 @@
|
|
|
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 {
|
|
13
|
+
/** slot identity preserved across replacements. */
|
|
14
|
+
readonly key: string;
|
|
12
15
|
/** unique per-revision identifier. */
|
|
13
16
|
readonly id: string;
|
|
14
17
|
/** entry position in the ledger. */
|
|
15
18
|
readonly index: number;
|
|
16
|
-
/**
|
|
17
|
-
readonly
|
|
19
|
+
/** entry URL or null if hidden. */
|
|
20
|
+
readonly url: string | null;
|
|
18
21
|
/** whether traversal to this entry stays within the current document. */
|
|
19
22
|
readonly sameDocument: boolean;
|
|
20
23
|
/** state associated with the entry. */
|
|
21
24
|
readonly state: unknown;
|
|
22
|
-
/** entry URL or null if hidden. */
|
|
23
|
-
readonly url: string | null;
|
|
24
25
|
}
|
|
25
26
|
/** active history entry with parsed URL components. */
|
|
26
27
|
interface HistoryLocation {
|
|
27
|
-
/**
|
|
28
|
-
readonly
|
|
28
|
+
/** slot identity. */
|
|
29
|
+
readonly key: string;
|
|
29
30
|
/** per-revision identifier. */
|
|
30
31
|
readonly id: string;
|
|
31
32
|
/** entry position in the ledger. */
|
|
32
33
|
readonly index: number;
|
|
33
|
-
/** slot identity. */
|
|
34
|
-
readonly key: string;
|
|
35
34
|
/** URL pathname starting with a slash. */
|
|
36
35
|
readonly pathname: string;
|
|
37
36
|
/** URL query string including the leading question mark. */
|
|
38
37
|
readonly search: string;
|
|
38
|
+
/** URL fragment including the leading hash symbol. */
|
|
39
|
+
readonly hash: string;
|
|
39
40
|
/** state associated with the entry. */
|
|
40
41
|
readonly state: unknown;
|
|
41
42
|
}
|
|
@@ -51,21 +52,21 @@ interface HistoryLocation {
|
|
|
51
52
|
type HistoryScrollBehavior = 'auto' | 'preserve';
|
|
52
53
|
/** options for history write operations. */
|
|
53
54
|
interface HistoryNavigateOptions {
|
|
54
|
-
/** arbitrary metadata passed to history listeners. */
|
|
55
|
-
readonly info?: unknown;
|
|
56
|
-
/** scroll and focus behavior. */
|
|
57
|
-
readonly scroll?: HistoryScrollBehavior;
|
|
58
55
|
/** state data associated with the entry. */
|
|
59
56
|
readonly state?: unknown;
|
|
57
|
+
/** scroll and focus behavior. */
|
|
58
|
+
readonly scroll?: HistoryScrollBehavior;
|
|
59
|
+
/** arbitrary metadata passed to history listeners. */
|
|
60
|
+
readonly info?: unknown;
|
|
60
61
|
}
|
|
61
62
|
/** history update details dispatched to listeners. */
|
|
62
63
|
interface HistoryUpdate {
|
|
63
64
|
readonly action: HistoryAction;
|
|
64
|
-
/** metadata passed to the write operation. */
|
|
65
|
-
readonly info: unknown;
|
|
66
65
|
readonly location: HistoryLocation;
|
|
67
66
|
/** viewport behavior, which listeners apply. */
|
|
68
67
|
readonly scroll: HistoryScrollBehavior;
|
|
68
|
+
/** metadata passed to the write operation. */
|
|
69
|
+
readonly info: unknown;
|
|
69
70
|
}
|
|
70
71
|
/**
|
|
71
72
|
* history update callback subscriber.
|
|
@@ -75,37 +76,18 @@ interface HistoryUpdate {
|
|
|
75
76
|
type HistoryListener = (update: HistoryUpdate) => void | Promise<void>;
|
|
76
77
|
/** history manager interface modeled on the web navigation API. */
|
|
77
78
|
interface History {
|
|
79
|
+
/** active history location. */
|
|
80
|
+
readonly location: HistoryLocation;
|
|
78
81
|
/** whether a backward entry exists. */
|
|
79
82
|
readonly canGoBack: boolean;
|
|
80
83
|
/** whether a forward entry exists. */
|
|
81
84
|
readonly canGoForward: boolean;
|
|
82
|
-
/** active history location. */
|
|
83
|
-
readonly location: HistoryLocation;
|
|
84
|
-
/** navigates back one entry. */
|
|
85
|
-
back(): void;
|
|
86
|
-
/** detaches listeners and cleans up resources. */
|
|
87
|
-
dispose(): void;
|
|
88
85
|
/**
|
|
89
86
|
* lists all entries in the ledger.
|
|
90
87
|
*
|
|
91
88
|
* @returns array of history entries
|
|
92
89
|
*/
|
|
93
90
|
entries(): readonly HistoryEntry[];
|
|
94
|
-
/** navigates forward one entry. */
|
|
95
|
-
forward(): void;
|
|
96
|
-
/**
|
|
97
|
-
* navigates by a delta offset.
|
|
98
|
-
*
|
|
99
|
-
* @param delta number of entries to move
|
|
100
|
-
*/
|
|
101
|
-
go(delta: number): void;
|
|
102
|
-
/**
|
|
103
|
-
* subscribes to history updates.
|
|
104
|
-
*
|
|
105
|
-
* @param listener update callback
|
|
106
|
-
* @returns unsubscribe function
|
|
107
|
-
*/
|
|
108
|
-
listen(listener: HistoryListener): () => void;
|
|
109
91
|
/**
|
|
110
92
|
* pushes a new history entry.
|
|
111
93
|
*
|
|
@@ -120,6 +102,16 @@ interface History {
|
|
|
120
102
|
* @param options navigation options
|
|
121
103
|
*/
|
|
122
104
|
replace(to: string, options?: HistoryNavigateOptions): void;
|
|
105
|
+
/**
|
|
106
|
+
* rewrites the state of the active entry in place, without navigating.
|
|
107
|
+
*
|
|
108
|
+
* the entry keeps its id, key and URL, so no revision is minted and the user's place on the page is left
|
|
109
|
+
* alone. listeners are notified with the `update` action, since the caller is only ever one of them.
|
|
110
|
+
*
|
|
111
|
+
* @param state state data to store on the entry, replacing whatever is there
|
|
112
|
+
* @throws when the state cannot be structured-cloned
|
|
113
|
+
*/
|
|
114
|
+
updateState(state: unknown): void;
|
|
123
115
|
/**
|
|
124
116
|
* navigates to an existing entry by key.
|
|
125
117
|
*
|
|
@@ -127,6 +119,25 @@ interface History {
|
|
|
127
119
|
* @returns promise that resolves on commit and rejects if traversal fails
|
|
128
120
|
*/
|
|
129
121
|
traverseTo(key: string): Promise<void>;
|
|
122
|
+
/**
|
|
123
|
+
* navigates by a delta offset.
|
|
124
|
+
*
|
|
125
|
+
* @param delta number of entries to move
|
|
126
|
+
*/
|
|
127
|
+
go(delta: number): void;
|
|
128
|
+
/** navigates back one entry. */
|
|
129
|
+
back(): void;
|
|
130
|
+
/** navigates forward one entry. */
|
|
131
|
+
forward(): void;
|
|
132
|
+
/**
|
|
133
|
+
* subscribes to history updates.
|
|
134
|
+
*
|
|
135
|
+
* @param listener update callback
|
|
136
|
+
* @returns unsubscribe function
|
|
137
|
+
*/
|
|
138
|
+
listen(listener: HistoryListener): () => void;
|
|
139
|
+
/** detaches listeners and cleans up resources. */
|
|
140
|
+
dispose(): 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 };
|
|
@@ -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,7 +47,7 @@ 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}`;
|
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.4",
|
|
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.0.2"
|
|
43
|
+
},
|
|
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",
|
|
62
|
+
"typescript": "^7.0.2",
|
|
63
|
+
"vite": "^8.1.5",
|
|
64
|
+
"vitest": "^4.1.10"
|
|
65
|
+
},
|
|
66
|
+
"peerDependencies": {
|
|
67
|
+
"react": ">=19.0.0",
|
|
68
|
+
"react-dom": ">=19.0.0"
|
|
69
|
+
}
|
|
70
|
+
}
|