@typed/navigation 1.0.0-beta.0 → 1.0.0-beta.2
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 +53 -48
- package/package.json +12 -8
- package/tsconfig.json +0 -6
package/README.md
CHANGED
|
@@ -2,7 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
> **Beta:** This package is in beta; APIs may change.
|
|
4
4
|
|
|
5
|
-
`@typed/navigation` provides
|
|
5
|
+
`@typed/navigation` provides typed, Effect-based control over the browser history API and in-memory history. It solves the need for reactive navigation state (current entry, history stack, transition, canGoBack/canGoForward), programmatic actions (navigate, back, forward, reload), and lifecycle hooks (before/after navigation) that can intercept, redirect, or cancel. Use it when you need: browser navigation with full history control; in-memory history for tests or SSR; blocking navigation on unsaved changes (confirm/cancel/redirect). The router (`@typed/router`) builds on navigation: `BrowserRouter` uses browser history, `ServerRouter` and `TestRouter` use in-memory providers.
|
|
6
|
+
|
|
7
|
+
## Integration
|
|
8
|
+
|
|
9
|
+
- **@typed/router** — `Router` = `CurrentRoute | Navigation`; BrowserRouter uses `fromWindow`; ServerRouter and TestRouter use `memory` or `initialMemory` for tests and SSR
|
|
10
|
+
- **@typed/ui** — Link component for programmatic navigation; HttpRouter uses `initialMemory` for server-side request handling
|
|
6
11
|
|
|
7
12
|
## Dependencies
|
|
8
13
|
|
|
@@ -23,10 +28,10 @@
|
|
|
23
28
|
import { Navigation } from "@typed/navigation";
|
|
24
29
|
|
|
25
30
|
// Inside Effect.gen(function* () { ... }); provide fromWindow (or memory) for browser
|
|
26
|
-
const nav = yield* Navigation;
|
|
27
|
-
const entry = yield* nav.currentEntry
|
|
28
|
-
yield* nav.navigate("/about", { history: "push" });
|
|
29
|
-
yield* nav.navigate("/about", { history: "replace" });
|
|
31
|
+
const nav = yield * Navigation;
|
|
32
|
+
const entry = yield * nav.currentEntry;
|
|
33
|
+
yield * nav.navigate("/about", { history: "push" });
|
|
34
|
+
yield * nav.navigate("/about", { history: "replace" });
|
|
30
35
|
// entry is the current Destination before navigating
|
|
31
36
|
```
|
|
32
37
|
|
|
@@ -36,23 +41,23 @@ yield* nav.navigate("/about", { history: "replace" });
|
|
|
36
41
|
|
|
37
42
|
Effect service for browser or in-memory history. Access via `yield* Navigation` inside an Effect that has a Navigation layer provided.
|
|
38
43
|
|
|
39
|
-
| Member
|
|
40
|
-
|
|
41
|
-
| `origin`
|
|
42
|
-
| `base`
|
|
43
|
-
| `currentEntry`
|
|
44
|
-
| `entries`
|
|
45
|
-
| `transition`
|
|
46
|
-
| `canGoBack`
|
|
47
|
-
| `canGoForward`
|
|
48
|
-
| `navigate(url, options?)`
|
|
49
|
-
| `back(options?)`
|
|
50
|
-
| `forward(options?)`
|
|
51
|
-
| `traverseTo(key, options?)`
|
|
52
|
-
| `updateCurrentEntry({ state })` | `Effect<Destination, NavigationError>`
|
|
53
|
-
| `reload(options?)`
|
|
54
|
-
| `onBeforeNavigation(handler)`
|
|
55
|
-
| `onNavigation(handler)`
|
|
44
|
+
| Member | Type | Description |
|
|
45
|
+
| ------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `origin` | `string` | Current origin (e.g. `"https://example.com"`). |
|
|
47
|
+
| `base` | `string` | Base URL (from `<base href>` or `"/"`). |
|
|
48
|
+
| `currentEntry` | `RefSubject.Computed<Destination>` | Reactive current history entry. |
|
|
49
|
+
| `entries` | `RefSubject.Computed<ReadonlyArray<Destination>>` | Reactive list of all history entries. |
|
|
50
|
+
| `transition` | `RefSubject.Filtered<Transition>` | Emits the in-progress transition when navigating. |
|
|
51
|
+
| `canGoBack` | `RefSubject.Computed<boolean>` | Whether `back()` can be called. |
|
|
52
|
+
| `canGoForward` | `RefSubject.Computed<boolean>` | Whether `forward()` can be called. |
|
|
53
|
+
| `navigate(url, options?)` | `Effect<Destination, NavigationError>` | Navigate to `url`; `options.history`: `"push"` \| `"replace"` \| `"auto"`, `state`, `info`. |
|
|
54
|
+
| `back(options?)` | `Effect<Destination, NavigationError>` | Go back one entry; `options.info` optional. |
|
|
55
|
+
| `forward(options?)` | `Effect<Destination, NavigationError>` | Go forward one entry; `options.info` optional. |
|
|
56
|
+
| `traverseTo(key, options?)` | `Effect<Destination, NavigationError>` | Go to the entry with the given `key`; `options.info` optional. |
|
|
57
|
+
| `updateCurrentEntry({ state })` | `Effect<Destination, NavigationError>` | Update the current entry’s `state` (replace in place). |
|
|
58
|
+
| `reload(options?)` | `Effect<Destination, NavigationError>` | Reload current entry; `options.info`, `options.state` optional. |
|
|
59
|
+
| `onBeforeNavigation(handler)` | `Effect<void, never, R \| Scope>` | Register a before-navigation handler; can redirect or cancel. |
|
|
60
|
+
| `onNavigation(handler)` | `Effect<void, never, R \| Scope>` | Register a handler that runs after navigation commits. |
|
|
56
61
|
|
|
57
62
|
### CurrentPath
|
|
58
63
|
|
|
@@ -60,36 +65,36 @@ Effect service for browser or in-memory history. Access via `yield* Navigation`
|
|
|
60
65
|
|
|
61
66
|
### Layers
|
|
62
67
|
|
|
63
|
-
| Layer
|
|
64
|
-
|
|
65
|
-
| `fromWindow(window?)`
|
|
66
|
-
| `memory(options)`
|
|
68
|
+
| Layer | Description |
|
|
69
|
+
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `fromWindow(window?)` | Uses the browser `Window` history API. Defaults to `globalThis.window`. Requires `Ids` in context. |
|
|
71
|
+
| `memory(options)` | In-memory history from `MemoryOptions`: `entries`, `origin?`, `base?`, `currentIndex?`, `maxEntries?`, `commit?`. |
|
|
67
72
|
| `initialMemory(options)` | In-memory history with a single initial entry. `InitialMemoryOptions`: `url`, `origin?`, `base?`, `maxEntries?`, `state?`. |
|
|
68
73
|
|
|
69
74
|
### Blocking (unsaved changes, etc.)
|
|
70
75
|
|
|
71
|
-
| Export
|
|
72
|
-
|
|
73
|
-
| `useBlockNavigation(params?)` | `Effect<BlockNavigation, never, Navigation \| R \| Scope>` | When navigation is attempted, can block and show confirm/cancel/redirect.
|
|
74
|
-
| `BlockNavigation`
|
|
75
|
-
| `Blocking`
|
|
76
|
-
| `UseBlockNavigationParams`
|
|
76
|
+
| Export | Type | Description |
|
|
77
|
+
| ----------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
78
|
+
| `useBlockNavigation(params?)` | `Effect<BlockNavigation, never, Navigation \| R \| Scope>` | When navigation is attempted, can block and show confirm/cancel/redirect. |
|
|
79
|
+
| `BlockNavigation` | interface | Extends `RefSubject.Filtered<Blocking>`; has `isBlocking: RefSubject.Computed<boolean>`. |
|
|
80
|
+
| `Blocking` | interface | Extends `BeforeNavigationEvent`; has `cancel`, `confirm`, `redirect(urlOrPath, options?)` effects. |
|
|
81
|
+
| `UseBlockNavigationParams` | interface | `shouldBlock?: (event) => Effect<boolean, RedirectError \| CancelNavigation, R>`. |
|
|
77
82
|
|
|
78
83
|
When a navigation is blocked, the handler receives a `Blocking` value; call `cancel` to abort, `confirm` to proceed, or `redirect(url, options?)` to redirect.
|
|
79
84
|
|
|
80
85
|
### Model types
|
|
81
86
|
|
|
82
|
-
| Type
|
|
83
|
-
|
|
84
|
-
| `Destination`
|
|
85
|
-
| `ProposedDestination`
|
|
86
|
-
| `NavigationType`
|
|
87
|
-
| `Transition`
|
|
88
|
-
| `BeforeNavigationEvent` | `type`, `from`, `delta`, `to`, `info`.
|
|
89
|
-
| `NavigationEvent`
|
|
90
|
-
| `NavigationError`
|
|
91
|
-
| `RedirectError`
|
|
92
|
-
| `CancelNavigation`
|
|
87
|
+
| Type | Description |
|
|
88
|
+
| ----------------------- | --------------------------------------------------------------------------------- |
|
|
89
|
+
| `Destination` | History entry: `id`, `key`, `url`, `state`, `sameDocument`. |
|
|
90
|
+
| `ProposedDestination` | Like `Destination` but without `id`/required `key`; used for “to” in transitions. |
|
|
91
|
+
| `NavigationType` | `"push"` \| `"replace"` \| `"reload"` \| `"traverse"`. |
|
|
92
|
+
| `Transition` | `type`, `from` (Destination), `to` (ProposedDestination), `info?`. |
|
|
93
|
+
| `BeforeNavigationEvent` | `type`, `from`, `delta`, `to`, `info`. |
|
|
94
|
+
| `NavigationEvent` | `type`, `destination`, `info`. |
|
|
95
|
+
| `NavigationError` | Error class; wraps underlying `error`. |
|
|
96
|
+
| `RedirectError` | Error class; `url`, `options?: { state?, info? }`. |
|
|
97
|
+
| `CancelNavigation` | Error class; no payload. |
|
|
93
98
|
|
|
94
99
|
### Handler types
|
|
95
100
|
|
|
@@ -98,8 +103,8 @@ When a navigation is blocked, the handler receives a `Blocking` value; call `can
|
|
|
98
103
|
|
|
99
104
|
### Core utilities
|
|
100
105
|
|
|
101
|
-
| Export
|
|
102
|
-
|
|
103
|
-
| `getUrl(origin, urlOrPath)` | `(origin: string, urlOrPath: string \| URL) => URL` | Resolve `urlOrPath` against `origin`; returns a `URL`.
|
|
104
|
-
| `NavigationState`
|
|
105
|
-
| `makeNavigationCore`
|
|
106
|
+
| Export | Type | Description |
|
|
107
|
+
| --------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
108
|
+
| `getUrl(origin, urlOrPath)` | `(origin: string, urlOrPath: string \| URL) => URL` | Resolve `urlOrPath` against `origin`; returns a `URL`. |
|
|
109
|
+
| `NavigationState` | type | Internal state: `entries`, `index`, `transition`. |
|
|
110
|
+
| `makeNavigationCore` | Effect | Low-level constructor for custom navigation backends; not typically used directly. |
|
package/package.json
CHANGED
|
@@ -1,9 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@typed/navigation",
|
|
3
|
-
"version": "1.0.0-beta.
|
|
4
|
-
"publishConfig": {
|
|
5
|
-
"access": "public"
|
|
6
|
-
},
|
|
3
|
+
"version": "1.0.0-beta.2",
|
|
7
4
|
"type": "module",
|
|
8
5
|
"exports": {
|
|
9
6
|
".": {
|
|
@@ -15,17 +12,24 @@
|
|
|
15
12
|
"import": "./dist/*.js"
|
|
16
13
|
}
|
|
17
14
|
},
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"effect": "4.0.0-beta.
|
|
20
|
-
"@typed/fx": "2.0.0-beta.
|
|
21
|
-
"@typed/id": "1.0.0-beta.
|
|
19
|
+
"effect": "4.0.0-beta.21",
|
|
20
|
+
"@typed/fx": "2.0.0-beta.2",
|
|
21
|
+
"@typed/id": "1.0.0-beta.2"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
24
|
"typescript": "5.9.3",
|
|
25
25
|
"vitest": "4.0.18"
|
|
26
26
|
},
|
|
27
|
+
"files": [
|
|
28
|
+
"dist",
|
|
29
|
+
"src"
|
|
30
|
+
],
|
|
27
31
|
"scripts": {
|
|
28
|
-
"build": "tsc",
|
|
32
|
+
"build": "[ -d dist ] || rm -f tsconfig.tsbuildinfo; tsc",
|
|
29
33
|
"test": "vitest run --passWithNoTests"
|
|
30
34
|
}
|
|
31
35
|
}
|