@k8ordo/router 0.1.0

package/dist/navigation.mjs

@@ -0,0 +1,123 @@
+"use client";
+import { normalizePathname } from "./paths.mjs";
+import { createContext, startTransition, useEffect, useRef, useState } from "react";
+//#region src/navigation.ts
+/**
+* Whether this navigation is the application's to handle at all.
+*
+* A reload is a request for a fresh document, and a POST submission carries a
+* body only the server can act on: intercepting either means silently doing
+* nothing where the platform would have done the obvious thing. A GET form
+* has no `formData`, so the search-shaped navigations `@k8ordo/state` builds
+* still come through here.
+*/
+const isOurs = (event) => event.canIntercept && !event.hashChange && event.downloadRequest === null && event.navigationType !== "reload" && event.formData === null;
+const scrollPlanFor = (navigationType, hash) => {
+	if (navigationType === "traverse") return null;
+	if (hash.length > 1) {
+		let id = hash.slice(1);
+		try {
+			id = decodeURIComponent(id);
+		} catch {}
+		return {
+			kind: "fragment",
+			id
+		};
+	}
+	return { kind: "top" };
+};
+const applyScroll = (plan) => {
+	if (plan.kind === "fragment") {
+		const selector = `#${CSS.escape(plan.id)}, [name=${JSON.stringify(plan.id)}]`;
+		const target = document.querySelector(selector);
+		if (target !== null) {
+			target.scrollIntoView();
+			return;
+		}
+	}
+	window.scrollTo({
+		left: 0,
+		top: -1
+	});
+};
+/**
+* Which navigation put the tree on screen — a number that changes exactly
+* when a new tree is applied, and not when only the URL moved. It is the
+* identity an error boundary keys on: leaving the page that failed is what
+* should clear the failure, and the URL commits before the tree arrives, so
+* the pathname would clear it one render too early and let the old tree
+* fail again under the new key.
+*/
+const NavigationGeneration = createContext(-1);
+/**
+* The navigation half of the router, on its own: intercept, load, apply in a
+* transition, and resolve the platform's handler only once the new tree is on
+* screen — which is what makes `navigation.navigate().finished` mean "the
+* page is showing", and what `@k8ordo/state`'s `update().finished` inherits.
+*
+* What gets loaded is the caller's business: a route table match for a plain
+* client app, an RSC payload under the framework. Neither has to teach this
+* hook anything about the other.
+*/
+function useInterceptedNavigation(handler) {
+	const latest = useRef(handler);
+	latest.current = handler;
+	const pending = useRef(/* @__PURE__ */ new Map());
+	const count = useRef(0);
+	const [applied, setApplied] = useState(-1);
+	const shown = useRef(null);
+	useEffect(() => {
+		shown.current = normalizePathname(location.pathname);
+		const onNavigate = (event) => {
+			if (!isOurs(event)) return;
+			const url = new URL(event.destination.url);
+			const pathname = normalizePathname(url.pathname);
+			if (pathname === shown.current) {
+				event.intercept({
+					scroll: "manual",
+					focusReset: "manual"
+				});
+				return;
+			}
+			if (!latest.current.claim(url)) return;
+			const id = count.current++;
+			const scroll = scrollPlanFor(event.navigationType, url.hash);
+			event.intercept({
+				scroll: scroll === null ? "after-transition" : "manual",
+				handler: async () => {
+					const value = await latest.current.load(url, event.signal);
+					if (event.signal.aborted) throw event.signal.reason;
+					await new Promise((resolve, reject) => {
+						pending.current.set(id, {
+							resolve,
+							scroll
+						});
+						event.signal.addEventListener("abort", () => {
+							pending.current.delete(id);
+							reject(event.signal.reason);
+						}, { once: true });
+						startTransition(() => {
+							shown.current = pathname;
+							latest.current.apply(value);
+							setApplied(id);
+						});
+					});
+				}
+			});
+		};
+		navigation.addEventListener("navigate", onNavigate);
+		return () => {
+			navigation.removeEventListener("navigate", onNavigate);
+		};
+	}, []);
+	useEffect(() => {
+		const entry = pending.current.get(applied);
+		if (entry === void 0) return;
+		pending.current.delete(applied);
+		if (entry.scroll !== null) applyScroll(entry.scroll);
+		entry.resolve();
+	}, [applied]);
+	return { generation: applied };
+}
+//#endregion
+export { NavigationGeneration, isOurs, scrollPlanFor, useInterceptedNavigation };

package/dist/paths.d.mts

@@ -0,0 +1,67 @@
+//#region src/paths.d.ts
+/**
+ * The type half of the route table: everything here is derived from the
+ * pattern strings by inference alone — no code generation. A pattern like
+ * `'/:locale/products/:id'` yields its params (`{ locale, id }`), its
+ * concrete-path type (`` `/${string}/products/${string}` ``), and its place
+ * in the app-wide route union.
+ */
+type SegParam<Segment extends string> = Segment extends `:${infer Name}` ? Record<Name, string> : Record<never, never>;
+type SegListParams<Rest extends string> = Rest extends `${infer Segment}/${infer Tail}` ? SegParam<Segment> & SegListParams<Tail> : SegParam<Rest>;
+/** `'/:locale/products/:id'` → `{ locale: string; id: string }` */
+type ParamsOf<Pattern extends string> = Pattern extends `/${infer Rest}` ? SegListParams<Rest> : Record<never, never>;
+/**
+ * The shape every validation library agrees on (Standard Schema): a value
+ * under `~standard` whose `types` carry the input and output. Only the
+ * output is read here — the router itself never runs a schema; the framework
+ * does, and this package only has to type what comes out.
+ */
+type StandardSchemaLike<Output = unknown> = {
+  readonly '~standard': {
+    readonly types?: {
+      readonly output: Output;
+    } | undefined;
+  };
+};
+/** What a schema produces. */
+type SchemaOutput<Schema> = Schema extends StandardSchemaLike<infer Output> ? Output : never;
+/**
+ * A schema a route file may declare for the params its pattern names: its
+ * output is an object whose keys are a subset of those params — a key the
+ * pattern does not name has nothing to validate.
+ */
+type ParamsSchemaFor<Pattern extends string> = StandardSchemaLike<Partial<Record<keyof ParamsOf<Pattern> & string, unknown>>>;
+type MergedOutput<Schemas extends readonly unknown[]> = Schemas extends readonly [infer Head, ...infer Tail] ? Omit<MergedOutput<Tail>, keyof SchemaOutput<Head>> & SchemaOutput<Head> : Record<never, never>;
+/**
+ * A pattern's params after the schemas along its stack have run — outer
+ * layouts first, the page last — each replacing the strings it names with
+ * what it produced. Params no schema names stay strings.
+ */
+type ParsedParams<Pattern extends string, Schemas extends readonly unknown[]> = Omit<ParamsOf<Pattern>, keyof MergedOutput<Schemas>> & MergedOutput<Schemas>;
+/** `{ '/products/:id': [schema, …] }` → `{ '/products/:id': { id: number } }` */
+type ParsedParamsMap<Schemas extends Record<string, readonly unknown[]>> = { [Pattern in keyof Schemas & string]: ParsedParams<Pattern, Schemas[Pattern]>; };
+type SegPath<Segment extends string> = Segment extends `:${string}` ? string : Segment;
+type SegListPath<Rest extends string> = Rest extends `${infer Segment}/${infer Tail}` ? `${SegPath<Segment>}/${SegListPath<Tail>}` : SegPath<Rest>;
+/** `'/:locale/products/:id'` → `` `/${string}/products/${string}` `` */
+type PathFor<Pattern extends string> = Pattern extends `/${infer Rest}` ? `/${SegListPath<Rest>}` : never;
+/**
+ * Keys that address the parent's own place instead of a place below it:
+ * `'/'` (the branch's index) and `'/(name)'` (a group, which structures the
+ * table — its own layout, its own subtree — without touching the URL).
+ */
+type Transparent<Key extends string> = Key extends '/' ? true : Key extends `/(${string})` ? true : false;
+/** Composes a parent prefix with a child key. */
+type Join<Prefix extends string, Key extends string> = Transparent<Key> extends true ? Prefix extends '' ? '/' : Prefix : `${Prefix}${Key}`;
+declare const isGroupKey: (key: string) => boolean;
+declare const joinPattern: (prefix: string, key: string) => string;
+/**
+ * URLPattern treats `/products` and `/products/` as different pathnames; the
+ * router does not. Everything is matched against the slashless canonical
+ * form, root excepted.
+ */
+declare const normalizePathname: (pathname: string) => string;
+/** What a param value may be on the way into a link: anything with one spelling. */
+type ParamValue = string | number | bigint | boolean;
+declare const buildHref: (pattern: string, params: Readonly<Record<string, unknown>> | undefined) => string;
+//#endregion
+export { Join, ParamValue, ParamsOf, ParamsSchemaFor, ParsedParams, ParsedParamsMap, PathFor, SchemaOutput, StandardSchemaLike, buildHref, isGroupKey, joinPattern, normalizePathname };

package/dist/paths.mjs

@@ -0,0 +1,26 @@
+//#region src/paths.ts
+const isGroupKey = (key) => /^\/\([^)]+\)$/u.test(key);
+const joinPattern = (prefix, key) => key === "/" || isGroupKey(key) ? prefix === "" ? "/" : prefix : `${prefix}${key}`;
+/**
+* URLPattern treats `/products` and `/products/` as different pathnames; the
+* router does not. Everything is matched against the slashless canonical
+* form, root excepted.
+*/
+const normalizePathname = (pathname) => {
+	let end = pathname.length;
+	while (end > 1 && pathname.charAt(end - 1) === "/") end -= 1;
+	return pathname.slice(0, end);
+};
+const buildHref = (pattern, params) => {
+	if (pattern.includes("*")) throw new TypeError(`"${pattern}" is a wildcard — it has no href`);
+	return pattern.split("/").map((segment) => {
+		if (!segment.startsWith(":")) return segment;
+		const name = segment.slice(1);
+		const value = params?.[name];
+		if (value === void 0) throw new TypeError(`"${pattern}" needs a value for ":${name}"`);
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "bigint" && typeof value !== "boolean") throw new TypeError(`"${pattern}" got a value for ":${name}" that has no URL spelling`);
+		return encodeURIComponent(String(value));
+	}).join("/");
+};
+//#endregion
+export { buildHref, isGroupKey, joinPattern, normalizePathname };

package/dist/register.d.mts

@@ -0,0 +1,46 @@
+import { ParamValue, ParamsOf } from "./paths.mjs";
+import { NavigablePatternOf, PatternOf, Routes, RoutesRecord } from "./define-routes.mjs";
+//#region src/register.d.ts
+/**
+ * The app-side hook for the route table's type. An application augments this
+ * once:
+ *
+ * ```ts
+ * declare module '@k8ordo/router' {
+ *   interface Register { routes: typeof routes }
+ * }
+ * ```
+ *
+ * and `href` / `navigateTo` / `useParams` verify their pattern against the
+ * table everywhere — without any component importing the table's value.
+ * Only `<Router>` touches the value; everything else needs just the string
+ * pattern, so the routes-module → pages → routes-module import cycle never
+ * forms. Declared as an interface — the one exception to the repository's
+ * type-only rule — because declaration merging is the entire mechanism.
+ */
+interface Register {}
+/** Every pattern in the registered table; any `/`-pattern before Register. */
+type RegisteredPattern = Register extends {
+  routes: Routes<infer R extends RoutesRecord>;
+} ? PatternOf<R> : `/${string}`;
+/** Linkable patterns of the registered table (wildcards excluded). */
+type RegisteredNavigablePattern = Register extends {
+  routes: Routes<infer R extends RoutesRecord>;
+} ? NavigablePatternOf<R> : `/${string}`;
+type RegisteredParamsMap = Register extends {
+  params: infer M;
+} ? M : null;
+/** The pattern's params as anything with one spelling, before any schema. */
+type LooseParamsOf<P extends string> = { [K in keyof ParamsOf<P>]: ParamValue; };
+/**
+ * A pattern's params as a link takes them: where the registered `params`
+ * map — written by the framework from the schemas the route files declared
+ * — says a page receives something, a link takes that same value (a number
+ * in, a number's one spelling out); a param no schema covers takes anything
+ * with one spelling. Before `Register` is augmented — a client application
+ * that has not, or the framework's generated file not yet written — the
+ * same loose shape applies, so a link written for a schema still compiles.
+ */
+type RegisteredParams<P extends string> = RegisteredParamsMap extends null ? LooseParamsOf<P> : P extends keyof RegisteredParamsMap ? Omit<LooseParamsOf<P>, keyof RegisteredParamsMap[P]> & RegisteredParamsMap[P] : LooseParamsOf<P>;
+//#endregion
+export { Register, RegisteredNavigablePattern, RegisteredParams, RegisteredPattern };

package/dist/register.mjs

@@ -0,0 +1 @@
+export {};

package/dist/router.d.mts

@@ -0,0 +1,32 @@
+import { ParamsOf } from "./paths.mjs";
+import { Match, Routes } from "./define-routes.mjs";
+import { RegisteredPattern } from "./register.mjs";
+import { FC, ReactNode } from "react";
+//#region src/router.d.ts
+/** Renders the next element of the matched stack — a layout's hole. */
+declare const Outlet: FC;
+/**
+ * Mounts a route table on the Navigation API: every same-origin navigation
+ * that the table claims is handled in the client, and the rest is left to the
+ * server. Layout components render their children through `<Outlet />`.
+ *
+ * This is the whole router for an application that renders on the client.
+ * Under the framework the tree comes from the server instead, and what is
+ * shared is `useInterceptedNavigation` and the `<PathnameProvider>` this
+ * mounts.
+ */
+declare function Router({ routes }: {
+  routes: Routes;
+}): ReactNode;
+/** The winning pattern and its params, untyped — `useParams` narrows. */
+declare function useRoute(): Pick<Match, 'pattern' | 'params'>;
+/**
+ * Typed params for the pattern this component believes it renders under —
+ * inferred from the pattern literal, verified against `Register`, and read
+ * from context at runtime, so no component imports the route table. The
+ * belief is checked: rendering under any other pattern throws instead of
+ * silently returning params of the wrong shape.
+ */
+declare function useParams<P extends RegisteredPattern>(pattern: P): ParamsOf<P>;
+//#endregion
+export { Outlet, Router, useParams, useRoute };

package/dist/router.mjs

@@ -0,0 +1,89 @@
+"use client";
+import { NavigationGeneration, useInterceptedNavigation } from "./navigation.mjs";
+import { setBoundaryOutlet } from "./define-routes.mjs";
+import { PathnameProvider } from "./location.mjs";
+import { createContext, use, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/router.tsx
+const RouterContext = createContext(null);
+const StackContext = createContext(null);
+const RenderStack = ({ stack, index }) => {
+	const value = useMemo(() => ({
+		stack,
+		index: index + 1
+	}), [stack, index]);
+	const next = stack[index];
+	if (next === void 0) return null;
+	return /* @__PURE__ */ jsx(StackContext, {
+		value,
+		children: /* @__PURE__ */ jsx(next, {})
+	});
+};
+/** Renders the next element of the matched stack — a layout's hole. */
+const Outlet = () => {
+	const ctx = use(StackContext);
+	if (ctx === null) throw new Error("Outlet must render inside <Router>");
+	return /* @__PURE__ */ jsx(RenderStack, {
+		stack: ctx.stack,
+		index: ctx.index
+	});
+};
+setBoundaryOutlet(() => /* @__PURE__ */ jsx(Outlet, {}));
+/**
+* Mounts a route table on the Navigation API: every same-origin navigation
+* that the table claims is handled in the client, and the rest is left to the
+* server. Layout components render their children through `<Outlet />`.
+*
+* This is the whole router for an application that renders on the client.
+* Under the framework the tree comes from the server instead, and what is
+* shared is `useInterceptedNavigation` and the `<PathnameProvider>` this
+* mounts.
+*/
+function Router({ routes }) {
+	const [match, setMatch] = useState(() => routes.match(location.pathname));
+	const { generation } = useInterceptedNavigation({
+		claim: (url) => routes.match(url.pathname) !== null,
+		load: (url) => routes.match(url.pathname),
+		apply: setMatch
+	});
+	const value = useMemo(() => ({
+		routes,
+		match
+	}), [routes, match]);
+	return /* @__PURE__ */ jsx(PathnameProvider, {
+		pathname: location.pathname,
+		children: /* @__PURE__ */ jsx(NavigationGeneration, {
+			value: generation,
+			children: /* @__PURE__ */ jsx(RouterContext, {
+				value,
+				children: match === null ? null : /* @__PURE__ */ jsx(RenderStack, {
+					stack: match.stack,
+					index: 0
+				})
+			})
+		})
+	});
+}
+/** The winning pattern and its params, untyped — `useParams` narrows. */
+function useRoute() {
+	const current = use(RouterContext)?.match ?? null;
+	if (current === null) throw new Error("useRoute must render inside a matched <Router>");
+	return {
+		pattern: current.pattern,
+		params: current.params
+	};
+}
+/**
+* Typed params for the pattern this component believes it renders under —
+* inferred from the pattern literal, verified against `Register`, and read
+* from context at runtime, so no component imports the route table. The
+* belief is checked: rendering under any other pattern throws instead of
+* silently returning params of the wrong shape.
+*/
+function useParams(pattern) {
+	const { pattern: current, params } = useRoute();
+	if (current !== pattern) throw new Error(`useParams("${pattern}") rendered under "${current}"`);
+	return params;
+}
+//#endregion
+export { Outlet, Router, useParams, useRoute };