@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.
@@ -1,41 +1,42 @@
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 {
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
- /** slot identity preserved across replacements. */
17
- readonly key: string;
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
- /** URL fragment including the leading hash symbol. */
28
- readonly hash: string;
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 = ({ 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}`;
package/package.json CHANGED
@@ -1,69 +1,70 @@
1
1
  {
2
- "name": "@oomfware/stacker",
3
- "version": "0.2.2",
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.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
+ }