@oomfware/stacker 0.2.0 → 0.2.1
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 +10 -0
- package/dist/index.d.mts +32 -4
- package/dist/index.mjs +61 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -206,6 +206,16 @@ const label = (target: RouteTarget<typeof routes>): string => {
|
|
|
206
206
|
because a target spells its params alongside `name`, a route cannot declare a param called `name`;
|
|
207
207
|
`defineRoutes` rejects it.
|
|
208
208
|
|
|
209
|
+
wrap route components in stacker's `lazy` to allow the router to preload them ahead of time.
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
const Profile = lazy(() => import('./screens/profile.tsx'));
|
|
213
|
+
|
|
214
|
+
<Link onPointerEnter={() => void router.preload('Profile')} to="/profile/alice">
|
|
215
|
+
alice
|
|
216
|
+
</Link>;
|
|
217
|
+
```
|
|
218
|
+
|
|
209
219
|
### hooks
|
|
210
220
|
|
|
211
221
|
generate type-safe hooks bound to your route configuration using `createRouterHooks`:
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { a as HistoryLocation, c as HistoryUpdate, i as HistoryListener, n as HistoryAction, o as HistoryNavigateOptions, r as HistoryEntry, s as HistoryScrollBehavior, t as History } from "./types-KOb6CZ7N.mjs";
|
|
2
|
-
import { AnchorHTMLAttributes, ComponentType, EffectCallback, ReactElement, ReactNode } from "react";
|
|
2
|
+
import { AnchorHTMLAttributes, ComponentType, EffectCallback, LazyExoticComponent, ReactElement, ReactNode } from "react";
|
|
3
3
|
//#region src/codec.d.ts
|
|
4
4
|
/**
|
|
5
5
|
* a bidirectional codec for a single route parameter.
|
|
@@ -199,11 +199,11 @@ declare const route: <const Params extends CodecRecord = Empty, const Query exte
|
|
|
199
199
|
declare const layout: <const Children extends RouteChildren, const Params extends CodecRecord = Empty>(config: LayoutConfig<Children, Params>) => LayoutNode<Children, Params>;
|
|
200
200
|
/** a node resolved with an id and normalized parameters. */
|
|
201
201
|
interface ResolvedNode {
|
|
202
|
+
readonly kind: 'layout' | 'route';
|
|
202
203
|
/** unique dot-separated node path. */
|
|
203
204
|
readonly id: string;
|
|
204
205
|
/** key name within the parent record. */
|
|
205
206
|
readonly key: string;
|
|
206
|
-
readonly kind: 'layout' | 'route';
|
|
207
207
|
readonly node: RouteNode;
|
|
208
208
|
/** local parameter codecs. */
|
|
209
209
|
readonly params: CodecRecord;
|
|
@@ -285,9 +285,9 @@ type QueryPatchOf<R, K extends RouteName<R>> = LeafQueryPatch<LeavesMap<R>[K]>;
|
|
|
285
285
|
//#region src/match.d.ts
|
|
286
286
|
/** a node on a matched chain paired with its instance parameters. */
|
|
287
287
|
interface MatchedNode {
|
|
288
|
+
readonly node: ResolvedNode;
|
|
288
289
|
/** parameters used for instance keying. */
|
|
289
290
|
readonly params: Readonly<Record<string, unknown>>;
|
|
290
|
-
readonly node: ResolvedNode;
|
|
291
291
|
}
|
|
292
292
|
/** the result of matching a URL, containing the chain, leaf, name, and parameters. */
|
|
293
293
|
interface RouteMatch {
|
|
@@ -364,6 +364,26 @@ interface View {
|
|
|
364
364
|
readonly roots: readonly InstanceNode[];
|
|
365
365
|
}
|
|
366
366
|
//#endregion
|
|
367
|
+
//#region src/lazy.d.ts
|
|
368
|
+
/** a preloadable lazily-loaded component. */
|
|
369
|
+
type LazyComponent<T extends ComponentType<any>> = LazyExoticComponent<T> & {
|
|
370
|
+
/**
|
|
371
|
+
* start loading the component code.
|
|
372
|
+
*
|
|
373
|
+
* @returns promise that settles once loading finishes
|
|
374
|
+
*/
|
|
375
|
+
preload(): Promise<void>;
|
|
376
|
+
};
|
|
377
|
+
/**
|
|
378
|
+
* defines a lazily-loaded component that can be preloaded.
|
|
379
|
+
*
|
|
380
|
+
* @param init component module loader
|
|
381
|
+
* @returns lazy component
|
|
382
|
+
*/
|
|
383
|
+
declare const lazy: <T extends ComponentType<any>>(init: () => Promise<{
|
|
384
|
+
default: T;
|
|
385
|
+
}>) => LazyComponent<T>;
|
|
386
|
+
//#endregion
|
|
367
387
|
//#region src/router.d.ts
|
|
368
388
|
/** options for a navigation. */
|
|
369
389
|
interface NavigateOptions<R extends RouteRegistry<unknown>> extends HistoryNavigateOptions {
|
|
@@ -446,6 +466,14 @@ declare class Router<R extends RouteRegistry<unknown>> {
|
|
|
446
466
|
* @param options where to go, and how to get there
|
|
447
467
|
*/
|
|
448
468
|
navigate(options: NavigateOptions<R>): void;
|
|
469
|
+
/**
|
|
470
|
+
* loads the code a route needs, without navigating to it.
|
|
471
|
+
*
|
|
472
|
+
* @param name route name
|
|
473
|
+
* @returns promise that settles once loading finishes
|
|
474
|
+
* @throws when `name` is not in the registry
|
|
475
|
+
*/
|
|
476
|
+
preload(name: RouteName<R>): Promise<void>;
|
|
449
477
|
/**
|
|
450
478
|
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
451
479
|
*
|
|
@@ -592,4 +620,4 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'
|
|
|
592
620
|
*/
|
|
593
621
|
declare const Link: ({ children, onClick, replace, to, ...rest }: LinkProps) => ReactElement;
|
|
594
622
|
//#endregion
|
|
595
|
-
export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryScrollBehavior, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LeafType, Link, type LinkProps, type MatchedNode, type MatchedTarget, type NavigateOptions, NavigationHistory, type NavigationHistoryOptions, type OptionalCodec, Outlet, type ParamsOf, type QueryPatchOf, type ReadonlyURLSearchParams, type ResolvedLeaf, type ResolvedNode, type RouteChildren, type RouteConfig, type RouteLeaf, type RouteMatch, type RouteMeta, type RouteName, type RouteNode, type RouteRegistry, type RouteTarget, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
|
|
623
|
+
export { type BuildParamsOf, type Codec, type DefaultedCodec, type History, type HistoryAction, type HistoryEntry, type HistoryListener, type HistoryLocation, type HistoryNavigateOptions, type HistoryScrollBehavior, type HistoryUpdate, type Infer, type InstanceNode, type LayoutConfig, type LayoutNode, type LazyComponent, type LeafType, Link, type LinkProps, type MatchedNode, type MatchedTarget, type NavigateOptions, NavigationHistory, type NavigationHistoryOptions, type OptionalCodec, Outlet, type ParamsOf, type QueryPatchOf, type ReadonlyURLSearchParams, type ResolvedLeaf, type ResolvedNode, type RouteChildren, type RouteConfig, type RouteLeaf, type RouteMatch, type RouteMeta, type RouteName, type RouteNode, type RouteRegistry, type RouteTarget, Router, type RouterHooks, type RouterOptions, RouterView, type View, type WhenContext, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
|
package/dist/index.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as parsePath, i as encodeSegment, n as decodeRemainder, o as resolvePath, r as encodeRemainder, t as createPath } from "./url-DerpiRjh.mjs";
|
|
2
|
+
import { Suspense, createContext, lazy as lazy$1, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
|
|
2
3
|
import { SimpleEventEmitter } from "@mary-ext/simple-event-emitter";
|
|
3
|
-
import { Suspense, createContext, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
|
|
4
4
|
import { Fragment, jsx, jsxs } from "react/jsx-runtime";
|
|
5
5
|
//#region src/codec.ts
|
|
6
6
|
const OPTIONAL = Symbol("stacker.optional");
|
|
@@ -81,9 +81,9 @@ const nonEmpty = () => ({
|
|
|
81
81
|
* @returns the optional codec
|
|
82
82
|
*/
|
|
83
83
|
const optional = (codec) => ({
|
|
84
|
+
[OPTIONAL]: true,
|
|
84
85
|
decode: (raw) => codec.decode(raw),
|
|
85
|
-
encode: (value) => codec.encode(value)
|
|
86
|
-
[OPTIONAL]: true
|
|
86
|
+
encode: (value) => codec.encode(value)
|
|
87
87
|
});
|
|
88
88
|
/**
|
|
89
89
|
* wraps a codec with a default value.
|
|
@@ -93,9 +93,9 @@ const optional = (codec) => ({
|
|
|
93
93
|
* @returns the defaulted codec
|
|
94
94
|
*/
|
|
95
95
|
const withDefault = (codec, fallback) => ({
|
|
96
|
+
[DEFAULT]: fallback,
|
|
96
97
|
decode: (raw) => codec.decode(raw),
|
|
97
|
-
encode: (value) => codec.encode(value)
|
|
98
|
-
[DEFAULT]: fallback
|
|
98
|
+
encode: (value) => codec.encode(value)
|
|
99
99
|
});
|
|
100
100
|
const isOptional = (codec) => {
|
|
101
101
|
return OPTIONAL in codec;
|
|
@@ -182,9 +182,9 @@ const defineRoutes = (tree) => {
|
|
|
182
182
|
if (ids.has(id)) throw new Error(`stacker: duplicate node id '${id}'`);
|
|
183
183
|
const params = node.params ?? {};
|
|
184
184
|
const resolved = {
|
|
185
|
+
kind: node.kind,
|
|
185
186
|
id,
|
|
186
187
|
key,
|
|
187
|
-
kind: node.kind,
|
|
188
188
|
node,
|
|
189
189
|
params,
|
|
190
190
|
path: node.kind === "route" ? node.path : void 0
|
|
@@ -520,6 +520,45 @@ const toRelative = (url) => {
|
|
|
520
520
|
return `${pathname}${search}${hash}`;
|
|
521
521
|
};
|
|
522
522
|
//#endregion
|
|
523
|
+
//#region src/lazy.ts
|
|
524
|
+
const noop = () => {};
|
|
525
|
+
/**
|
|
526
|
+
* defines a lazily-loaded component that can be preloaded.
|
|
527
|
+
*
|
|
528
|
+
* @param init component module loader
|
|
529
|
+
* @returns lazy component
|
|
530
|
+
*/
|
|
531
|
+
const lazy = (init) => {
|
|
532
|
+
const component = lazy$1(init);
|
|
533
|
+
return Object.assign(component, { preload() {
|
|
534
|
+
try {
|
|
535
|
+
const internals = component;
|
|
536
|
+
internals._init(internals._payload);
|
|
537
|
+
} catch {}
|
|
538
|
+
return Promise.try(init).then(noop, noop);
|
|
539
|
+
} });
|
|
540
|
+
};
|
|
541
|
+
const isPreloadable = (component) => {
|
|
542
|
+
return typeof component.preload === "function";
|
|
543
|
+
};
|
|
544
|
+
/**
|
|
545
|
+
* loads every preloadable component in a list.
|
|
546
|
+
*
|
|
547
|
+
* @param components components to load
|
|
548
|
+
* @returns promise that settles once loading finishes
|
|
549
|
+
*/
|
|
550
|
+
const preloadAll = (chain) => {
|
|
551
|
+
const pending = [];
|
|
552
|
+
for (const node of chain) {
|
|
553
|
+
const component = node.node.component;
|
|
554
|
+
if (!isPreloadable(component)) continue;
|
|
555
|
+
try {
|
|
556
|
+
pending.push(component.preload().then(noop, noop));
|
|
557
|
+
} catch {}
|
|
558
|
+
}
|
|
559
|
+
return Promise.all(pending).then(noop);
|
|
560
|
+
};
|
|
561
|
+
//#endregion
|
|
523
562
|
//#region src/build.ts
|
|
524
563
|
const SEGMENT = /:([A-Za-z_]\w*)/g;
|
|
525
564
|
var Builder = class {
|
|
@@ -808,6 +847,18 @@ var Router = class {
|
|
|
808
847
|
else this.#history.push(url, rest);
|
|
809
848
|
}
|
|
810
849
|
/**
|
|
850
|
+
* loads the code a route needs, without navigating to it.
|
|
851
|
+
*
|
|
852
|
+
* @param name route name
|
|
853
|
+
* @returns promise that settles once loading finishes
|
|
854
|
+
* @throws when `name` is not in the registry
|
|
855
|
+
*/
|
|
856
|
+
preload(name) {
|
|
857
|
+
const leaf = this.#routes.leaves.get(name);
|
|
858
|
+
if (leaf === void 0) throw new Error(`stacker: unknown route '${name}'`);
|
|
859
|
+
return preloadAll(leaf.chain);
|
|
860
|
+
}
|
|
861
|
+
/**
|
|
811
862
|
* returns to the nearest existing history entry for a route, or pushes if none exists.
|
|
812
863
|
*
|
|
813
864
|
* @param to route target, or a relative URL resolved against the active location
|
|
@@ -940,6 +991,7 @@ var Router = class {
|
|
|
940
991
|
}
|
|
941
992
|
#record(location, scrollPos) {
|
|
942
993
|
const match = this.#match(location);
|
|
994
|
+
preloadAll(match.leaf.chain);
|
|
943
995
|
const entry = {
|
|
944
996
|
index: location.index,
|
|
945
997
|
key: location.key,
|
|
@@ -999,17 +1051,17 @@ const toTarget = (match) => ({
|
|
|
999
1051
|
});
|
|
1000
1052
|
const makeNotFound = (component) => {
|
|
1001
1053
|
const leafNode = {
|
|
1002
|
-
component,
|
|
1003
1054
|
kind: "route",
|
|
1055
|
+
component,
|
|
1004
1056
|
params: {},
|
|
1005
1057
|
path: "*",
|
|
1006
1058
|
query: {},
|
|
1007
1059
|
type: "page"
|
|
1008
1060
|
};
|
|
1009
1061
|
const node = {
|
|
1062
|
+
kind: "route",
|
|
1010
1063
|
id: " notFound",
|
|
1011
1064
|
key: " notFound",
|
|
1012
|
-
kind: "route",
|
|
1013
1065
|
node: leafNode,
|
|
1014
1066
|
params: {},
|
|
1015
1067
|
path: "*"
|
|
@@ -1244,4 +1296,4 @@ const Link = ({ children, onClick, replace, to, ...rest }) => {
|
|
|
1244
1296
|
});
|
|
1245
1297
|
};
|
|
1246
1298
|
//#endregion
|
|
1247
|
-
export { Link, NavigationHistory, Outlet, Router, RouterView, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
|
|
1299
|
+
export { Link, NavigationHistory, Outlet, Router, RouterView, boolean, createRouterHooks, defineRoutes, enumOf, integer, layout, lazy, nonEmpty, optional, resolveMeta, route, string, useFocusEffect, useIsFocused, useLocation, useParams, useRoute, useRouter, withDefault };
|