@oomfware/stacker 0.1.0
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/LICENSE +14 -0
- package/README.md +286 -0
- package/dist/index.d.mts +548 -0
- package/dist/index.mjs +1102 -0
- package/dist/testing.d.mts +33 -0
- package/dist/testing.mjs +121 -0
- package/dist/types-Dj7Al7f8.d.mts +129 -0
- package/dist/url-CoOVqRk_.mjs +37 -0
- package/package.json +74 -0
- package/src/build.ts +53 -0
- package/src/cache.ts +53 -0
- package/src/codec.ts +182 -0
- package/src/history/memory.ts +155 -0
- package/src/history/navigation.ts +213 -0
- package/src/history/types.ts +133 -0
- package/src/index.ts +52 -0
- package/src/keys.ts +41 -0
- package/src/match.ts +180 -0
- package/src/react/context.ts +18 -0
- package/src/react/hooks.ts +178 -0
- package/src/react/link.tsx +61 -0
- package/src/react/outlet.tsx +18 -0
- package/src/react/router-view.tsx +79 -0
- package/src/router.ts +397 -0
- package/src/routes.ts +325 -0
- package/src/testing.ts +2 -0
- package/src/url.ts +41 -0
- package/src/view-model.ts +78 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
BSD Zero Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mary
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted.
|
|
7
|
+
|
|
8
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
9
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
10
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
11
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
12
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
13
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
14
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
# @oomfware/stacker
|
|
2
|
+
|
|
3
|
+
type-safe stack router for React.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @oomfware/stacker
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## usage
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import {
|
|
13
|
+
defineRoutes,
|
|
14
|
+
layout,
|
|
15
|
+
Link,
|
|
16
|
+
NavigationHistory,
|
|
17
|
+
Outlet,
|
|
18
|
+
route,
|
|
19
|
+
Router,
|
|
20
|
+
RouterView,
|
|
21
|
+
string,
|
|
22
|
+
} from '@oomfware/stacker';
|
|
23
|
+
|
|
24
|
+
const AppShell = () => (
|
|
25
|
+
<main>
|
|
26
|
+
<nav>
|
|
27
|
+
<Link to="/">home</Link>
|
|
28
|
+
<Link to="/profile/alice">alice</Link>
|
|
29
|
+
</nav>
|
|
30
|
+
<Outlet />
|
|
31
|
+
</main>
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
const Home = () => <h1>home</h1>;
|
|
35
|
+
const Profile = () => <h1>profile</h1>;
|
|
36
|
+
|
|
37
|
+
const routes = defineRoutes({
|
|
38
|
+
app: layout({
|
|
39
|
+
component: AppShell,
|
|
40
|
+
children: {
|
|
41
|
+
Home: route({ component: Home, path: '/' }),
|
|
42
|
+
Profile: route({
|
|
43
|
+
component: Profile,
|
|
44
|
+
params: { actor: string() },
|
|
45
|
+
path: '/profile/:actor',
|
|
46
|
+
}),
|
|
47
|
+
},
|
|
48
|
+
}),
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
const router = new Router({ history: new NavigationHistory(), routes });
|
|
52
|
+
|
|
53
|
+
export const App = () => <RouterView router={router} />;
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### defining routes
|
|
57
|
+
|
|
58
|
+
define routes using a nested tree of `layout` and `route` nodes. leaf names must be unique across
|
|
59
|
+
the tree:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import { defineRoutes, layout, route, string } from '@oomfware/stacker';
|
|
63
|
+
|
|
64
|
+
const routes = defineRoutes({
|
|
65
|
+
app: layout({
|
|
66
|
+
component: AppShell,
|
|
67
|
+
children: {
|
|
68
|
+
Home: route({ component: Home, path: '/' }),
|
|
69
|
+
Profile: route({
|
|
70
|
+
component: Profile,
|
|
71
|
+
params: { actor: string() },
|
|
72
|
+
query: { tab: optional(string()) },
|
|
73
|
+
path: '/profile/:actor',
|
|
74
|
+
}),
|
|
75
|
+
Settings: route({ component: Settings, path: '/settings' }),
|
|
76
|
+
},
|
|
77
|
+
}),
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
configure `type` to control page instance lifetimes:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
// page (default): new instance and state per history entry
|
|
85
|
+
route({ component: Profile, path: '/profile/:actor', type: 'page' });
|
|
86
|
+
|
|
87
|
+
// singleton: one instance per distinct parameter set
|
|
88
|
+
route({ component: Home, path: '/', type: 'singleton' });
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### parameters
|
|
92
|
+
|
|
93
|
+
declare path and query parameters using codecs. types are inferred automatically:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
import { boolean, enumOf, integer, optional, route, string, withDefault } from '@oomfware/stacker';
|
|
97
|
+
|
|
98
|
+
route({
|
|
99
|
+
component: SearchPage,
|
|
100
|
+
path: '/search/:tag',
|
|
101
|
+
params: { tag: string() },
|
|
102
|
+
query: {
|
|
103
|
+
page: withDefault(integer(), 1),
|
|
104
|
+
sort: withDefault(enumOf(['new', 'top']), 'new'),
|
|
105
|
+
unread: optional(boolean()),
|
|
106
|
+
},
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
path parameters are always required. query parameters without a default or optional codec must be
|
|
111
|
+
present in the URL to match the route.
|
|
112
|
+
|
|
113
|
+
write custom codecs by defining `decode` and `encode` methods:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import type { Codec } from '@oomfware/stacker';
|
|
117
|
+
|
|
118
|
+
const date: Codec<Date> = {
|
|
119
|
+
decode: (raw) => {
|
|
120
|
+
const ms = Date.parse(raw);
|
|
121
|
+
return Number.isNaN(ms) ? undefined : new Date(ms);
|
|
122
|
+
},
|
|
123
|
+
encode: (value) => value.toISOString(),
|
|
124
|
+
};
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`defineRoutes` throws at load time if codecs do not match the `:params` declared in the path.
|
|
128
|
+
|
|
129
|
+
### navigating
|
|
130
|
+
|
|
131
|
+
use `<Link>` to route in-app:
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
<Link to="/profile/alice">alice</Link>
|
|
135
|
+
<Link to="/settings" replace>settings</Link>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
plain `<a>` elements also route in-app automatically under `NavigationHistory`.
|
|
139
|
+
|
|
140
|
+
drive the router imperatively using either URLs or type-safe route names and parameters:
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
// string-based navigation
|
|
144
|
+
router.push('/profile/alice');
|
|
145
|
+
router.replace('/profile/alice');
|
|
146
|
+
|
|
147
|
+
// name-based navigation (type-checked)
|
|
148
|
+
router.navigate('Profile', { actor: 'alice' });
|
|
149
|
+
router.build('Profile', { actor: 'alice' }); // -> "/profile/alice"
|
|
150
|
+
|
|
151
|
+
// history manipulation
|
|
152
|
+
router.popTo('Messages');
|
|
153
|
+
router.setParams({ tab: 'media' });
|
|
154
|
+
router.back();
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`setParams` replaces the current history entry, preserving scroll and focus. undeclared query keys
|
|
158
|
+
are ignored.
|
|
159
|
+
|
|
160
|
+
### hooks
|
|
161
|
+
|
|
162
|
+
generate type-safe hooks bound to your route configuration using `createRouterHooks`:
|
|
163
|
+
|
|
164
|
+
```tsx
|
|
165
|
+
import { createRouterHooks } from '@oomfware/stacker';
|
|
166
|
+
|
|
167
|
+
const { useNavigate, useParams } = createRouterHooks(routes);
|
|
168
|
+
|
|
169
|
+
const Profile = () => {
|
|
170
|
+
const [{ actor }, setParams] = useParams('Profile');
|
|
171
|
+
const navigate = useNavigate();
|
|
172
|
+
|
|
173
|
+
return (
|
|
174
|
+
<>
|
|
175
|
+
<h1>@{actor}</h1>
|
|
176
|
+
<button onClick={() => setParams({ tab: 'media' })}>media</button>
|
|
177
|
+
<button onClick={() => navigate('Settings')}>settings</button>
|
|
178
|
+
</>
|
|
179
|
+
);
|
|
180
|
+
};
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
the package also exports registry-free hooks (`useLocation`, `useRoute`, `useRouter`) for components
|
|
184
|
+
that do not need type-safe route definitions.
|
|
185
|
+
|
|
186
|
+
### keeping screens alive
|
|
187
|
+
|
|
188
|
+
backward entries stay mounted behind the active screen. control memory usage and pinning behavior
|
|
189
|
+
during router setup:
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
const router = new Router({
|
|
193
|
+
history: new NavigationHistory(),
|
|
194
|
+
routes,
|
|
195
|
+
max: 5, // keep up to 5 backward entries mounted; older ones are evicted
|
|
196
|
+
pins: ["Home"], // keep specified singleton routes mounted indefinitely once visited
|
|
197
|
+
notFound: NotFound,
|
|
198
|
+
defaultFallback: <Spinner />,
|
|
199
|
+
});
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
use `router.dispose()` to detach the router from history when it is no longer needed.
|
|
203
|
+
|
|
204
|
+
### focus-aware effects
|
|
205
|
+
|
|
206
|
+
use focus hooks for work that should run when the screen becomes active, rather than when it mounts:
|
|
207
|
+
|
|
208
|
+
```tsx
|
|
209
|
+
import { useCallback } from 'react';
|
|
210
|
+
import { useFocusEffect, useIsFocused } from '@oomfware/stacker';
|
|
211
|
+
|
|
212
|
+
const Profile = () => {
|
|
213
|
+
const [{ actor }] = useParams('Profile');
|
|
214
|
+
|
|
215
|
+
useFocusEffect(
|
|
216
|
+
useCallback(() => {
|
|
217
|
+
document.title = `@${actor}`;
|
|
218
|
+
}, [actor]),
|
|
219
|
+
);
|
|
220
|
+
|
|
221
|
+
const focused = useIsFocused();
|
|
222
|
+
return <VideoPlayer paused={!focused} />;
|
|
223
|
+
};
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
`useFocusEffect` relies on reference identity; wrap the callback in `useCallback` to prevent it from
|
|
227
|
+
re-running on every render.
|
|
228
|
+
|
|
229
|
+
### server-owned URLs
|
|
230
|
+
|
|
231
|
+
exclude specific paths from in-app routing to let the browser handle them:
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
new NavigationHistory({
|
|
235
|
+
ignore: (url) => url.pathname.startsWith('/oauth/'),
|
|
236
|
+
});
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### metadata
|
|
240
|
+
|
|
241
|
+
declare custom route metadata using module augmentation:
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
import { layout, resolveMeta } from '@oomfware/stacker';
|
|
245
|
+
|
|
246
|
+
declare module '@oomfware/stacker' {
|
|
247
|
+
interface RouteMeta {
|
|
248
|
+
readonly requireAuth?: boolean;
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
layout({
|
|
253
|
+
component: AdminShell,
|
|
254
|
+
meta: { requireAuth: true },
|
|
255
|
+
children: {/* ... */},
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
// resolves metadata walking from leaf to root
|
|
259
|
+
resolveMeta(router.route, 'requireAuth');
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### conditional matching
|
|
263
|
+
|
|
264
|
+
use `when` to conditionally reject matches based on custom logic, such as feature flags or query
|
|
265
|
+
parameters:
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
route({
|
|
269
|
+
component: Beta,
|
|
270
|
+
path: '/feed',
|
|
271
|
+
when: ({ rawSearch }) => rawSearch.has('beta'),
|
|
272
|
+
});
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### testing
|
|
276
|
+
|
|
277
|
+
use `MemoryHistory` to test routing behavior in environments without a DOM:
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
import { MemoryHistory } from '@oomfware/stacker/testing';
|
|
281
|
+
|
|
282
|
+
const router = new Router({
|
|
283
|
+
history: new MemoryHistory({ initialEntries: ['/', '/profile/alice'] }),
|
|
284
|
+
routes,
|
|
285
|
+
});
|
|
286
|
+
```
|