@ilha/router 0.1.1 → 0.2.0

package/dist/index.js

@@ -2,6 +2,54 @@ import ilha, { context, html, mount } from "ilha";
 import { addRoute, createRouter, findRoute } from "rou3";
 //#region src/index.ts
 const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+/**
+* Identity function for declaring a loader. Exists purely as a type anchor and
+* a marker for the Vite plugin to detect by export name.
+*/
+function loader(fn) {
+	return fn;
+}
+var Redirect = class {
+	__ilhaRedirect = true;
+	to;
+	status;
+	constructor(to, status = 302) {
+		this.to = to;
+		this.status = status;
+	}
+};
+var LoaderError = class {
+	__ilhaLoaderError = true;
+	status;
+	message;
+	constructor(status, message) {
+		this.status = status;
+		this.message = message;
+	}
+};
+function redirect(to, status = 302) {
+	throw new Redirect(to, status);
+}
+function error(status, message) {
+	throw new LoaderError(status, message);
+}
+/**
+* Compose a list of loaders into a single loader. Later loaders win on key
+* collision (page loader overrides layout loader for the same key). All loaders
+* run concurrently within a chain since they share the same abort signal and
+* request — re-fetching is cheap with a request-scoped cache (future work).
+*
+* For v1 we run them in parallel via `Promise.all`. If a loader throws a
+* `Redirect` or `LoaderError`, the composed loader re-throws it unchanged.
+*/
+function composeLoaders(loaders) {
+	if (loaders.length === 0) return async () => ({});
+	if (loaders.length === 1) return loaders[0];
+	return async (ctx) => {
+		const results = await Promise.all(loaders.map((l) => l(ctx)));
+		return Object.assign({}, ...results);
+	};
+}
 function wrapLayout(layout, page) {
 	return layout(page);
 }
@@ -44,33 +92,114 @@ function wrapError(handler, page) {
 	};
 	return wrapper;
 }
+function defineLayout(layout) {
+	return layout;
+}
 function buildReverseRegistry(registry) {
 	const map = /* @__PURE__ */ new Map();
 	for (const [name, island] of Object.entries(registry)) if (!map.has(island)) map.set(island, name);
 	return map;
 }
+/** Path of the loader endpoint served by the Vite plugin / production adapter. */
+const LOADER_ENDPOINT = "/__ilha/loader";
+/** In-memory cache for prefetched loader data, keyed by path+search. */
+const prefetchCache = /* @__PURE__ */ new Map();
+async function fetchLoaderData(pathWithSearch, signal) {
+	const cached = prefetchCache.get(pathWithSearch);
+	if (cached) {
+		prefetchCache.delete(pathWithSearch);
+		try {
+			return await cached;
+		} catch {}
+	}
+	const url = `${LOADER_ENDPOINT}?path=${encodeURIComponent(pathWithSearch)}`;
+	try {
+		const res = await fetch(url, {
+			signal,
+			headers: { accept: "application/json" }
+		});
+		if (!res.ok) {
+			try {
+				const body = await res.json();
+				if (body && typeof body === "object" && "kind" in body) return body;
+			} catch {}
+			return {
+				kind: "error",
+				status: res.status,
+				message: res.statusText
+			};
+		}
+		return await res.json();
+	} catch (e) {
+		if (e?.name === "AbortError") throw e;
+		return {
+			kind: "error",
+			status: 0,
+			message: e?.message ?? "network error"
+		};
+	}
+}
+/**
+* Prefetch loader data for a given path. Safe to call repeatedly — a single
+* inflight request is reused until it either resolves (and is consumed by
+* navigation) or is superseded by another prefetch.
+*/
+function prefetch(pathWithSearch) {
+	if (!isBrowser) return;
+	if (prefetchCache.has(pathWithSearch)) return;
+	const pathOnly = pathWithSearch.split("?")[0] ?? "";
+	if (!findRoute(_rou3, "GET", pathOnly)?.data?.loader) return;
+	const promise = fetchLoaderData(pathWithSearch).catch((e) => {
+		return {
+			kind: "error",
+			status: 0,
+			message: e?.message ?? "prefetch failed"
+		};
+	});
+	prefetchCache.set(pathWithSearch, promise);
+}
 /**
 * Mounts a route island with proper hydration for client-side navigation.
-* Looks up the island in the reverse registry, renders it with hydration
-* markers, and mounts it for interactivity.
+* Looks up the island in the reverse registry, runs the loader (via fetch),
+* renders it with hydration markers, and mounts it for interactivity.
 */
-async function mountRouteWithHydration(island, host, registry, reverseRegistry) {
+async function mountRouteWithHydration(island, host, pathWithSearch, signal, registry, reverseRegistry) {
 	if (!island) {
 		host.innerHTML = `<div data-router-empty></div>`;
 		return () => {};
 	}
+	const hasLoader = !!findRoute(_rou3, "GET", pathWithSearch.split("?")[0] ?? "")?.data?.loader;
+	let props = {};
+	const loaderResult = hasLoader ? await fetchLoaderData(pathWithSearch, signal) : {
+		kind: "data",
+		data: {}
+	};
+	if (loaderResult.kind === "redirect") {
+		navigate(loaderResult.to, { replace: true });
+		return () => {};
+	}
+	if (loaderResult.kind === "error") {
+		const escaped = String(loaderResult.message).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+		host.innerHTML = `<div data-router-view data-router-error="${loaderResult.status}">${escaped}</div>`;
+		return () => {};
+	}
+	if (loaderResult.kind === "not-found") {
+		host.innerHTML = `<div data-router-empty></div>`;
+		return () => {};
+	}
+	props = loaderResult.data;
 	if (!registry) {
 		console.warn("[ilha-router] No registry provided for client-side navigation. Island will not be interactive.");
-		host.innerHTML = `<div data-router-view>${island.toString()}</div>`;
+		host.innerHTML = `<div data-router-view>${island.toString(props)}</div>`;
 		return () => {};
 	}
 	const name = reverseRegistry?.get(island) ?? Object.entries(registry).find(([, v]) => v === island)?.[0];
 	if (!name) {
 		console.warn("[ilha-router] Island not found in registry for client-side navigation.");
-		host.innerHTML = `<div data-router-view>${island.toString()}</div>`;
+		host.innerHTML = `<div data-router-view>${island.toString(props)}</div>`;
 		return () => {};
 	}
-	host.innerHTML = `<div data-router-view>${await island.hydratable({}, {
+	host.innerHTML = `<div data-router-view>${await island.hydratable(props, {
 		name,
 		as: "div",
 		snapshot: true
@@ -95,6 +224,7 @@ const activeIsland = context("router.active", null);
 let _records = [];
 let _rou3 = createRouter();
 let _islandToPattern = /* @__PURE__ */ new Map();
+let _patternToData = /* @__PURE__ */ new Map();
 function extractParams(matchParams) {
 	const params = {};
 	if (matchParams) for (const [k, v] of Object.entries(matchParams)) params[k] = decodeURIComponent(v);
@@ -107,7 +237,7 @@ function syncRouteFromURL(url) {
 	routeParams(extractParams(match?.params));
 	routeSearch(parsed.search);
 	routeHash(parsed.hash);
-	activeIsland(match?.data ?? null);
+	activeIsland(match?.data?.island ?? null);
 }
 /** Client-only fast path — reads directly from `location` instead of parsing a URL. */
 function syncRouteFromLocation() {
@@ -116,25 +246,12 @@ function syncRouteFromLocation() {
 	routeParams(extractParams(match?.params));
 	routeSearch(location.search);
 	routeHash(location.hash);
-	activeIsland(match?.data ?? null);
+	activeIsland(match?.data?.island ?? null);
 }
 /**
 * Prime route context signals from the current `location` so that islands
 * hydrated by `ilha.mount()` see the correct route values on their first
 * render — preventing a mismatch morph that would destroy hydrated bindings.
-*
-* Call this **before** `ilha.mount()` and **after** all routes have been
-* registered (i.e. after the `router().route(…).route(…)` chain).
-*
-* ```ts
-* import { mount } from "ilha";
-* import { pageRouter } from "ilha:pages";
-* import { registry } from "ilha:registry";
-*
-* pageRouter.prime();              // ← sync signals first
-* mount(registry, { root: … });   // ← then hydrate islands
-* pageRouter.mount("#app", { hydrate: true });
-* ```
 */
 function prime() {
 	if (isBrowser) syncRouteFromLocation();
@@ -146,25 +263,42 @@ function navigate(to, opts = {}) {
 	else history.pushState(null, "", to);
 	syncRouteFromLocation();
 }
-function enableLinkInterception(root = document) {
+function enableLinkInterception(root = document, options = {}) {
 	if (!isBrowser) return () => {};
-	const handler = (e) => {
-		if (e.defaultPrevented) return;
-		const target = e.target.closest("a");
-		if (!target) return;
+	const prefetchEnabled = options.prefetch !== false;
+	/** Determine whether this anchor is a same-origin in-app link we should handle. */
+	function eligibleLink(target, e) {
 		const href = target.getAttribute("href");
-		if (!href) return;
+		if (!href) return false;
 		const isAnchorOnly = href.startsWith("#");
 		const isBlank = target.getAttribute("target") === "_blank";
-		const hasModifier = e.ctrlKey || e.metaKey || e.shiftKey;
+		const hasModifier = !!e && (e.ctrlKey || e.metaKey || e.shiftKey);
 		const isExternal = !!target.hostname && (target.hostname !== location.hostname || target.protocol !== location.protocol);
 		const hasNoIntercept = target.hasAttribute("data-no-intercept");
-		if (isExternal || isAnchorOnly || isBlank || hasModifier || hasNoIntercept) return;
+		return !(isExternal || isAnchorOnly || isBlank || hasModifier || hasNoIntercept);
+	}
+	const clickHandler = (e) => {
+		if (e.defaultPrevented) return;
+		const target = e.target.closest("a");
+		if (!target) return;
+		if (!eligibleLink(target, e)) return;
 		e.preventDefault();
 		navigate(target.pathname + target.search + target.hash);
 	};
-	root.addEventListener("click", handler);
-	return () => root.removeEventListener("click", handler);
+	const hoverHandler = (e) => {
+		const target = e.target.closest("a");
+		if (!target) return;
+		const flag = target.getAttribute("data-prefetch");
+		if (flag === null || flag === "false") return;
+		if (!eligibleLink(target)) return;
+		prefetch(target.pathname + target.search);
+	};
+	root.addEventListener("click", clickHandler);
+	if (prefetchEnabled) root.addEventListener("mouseover", hoverHandler, { passive: true });
+	return () => {
+		root.removeEventListener("click", clickHandler);
+		if (prefetchEnabled) root.removeEventListener("mouseover", hoverHandler);
+	};
 }
 const RouterView = ilha.render(() => {
 	const island = activeIsland();
@@ -174,28 +308,100 @@ const RouterView = ilha.render(() => {
 const RouterLink = ilha.state("href", "").state("label", "").on("[data-link]@click", ({ state, event }) => {
 	event.preventDefault();
 	navigate(state.href());
-}).render(({ state }) => html`<a data-link href="${state.href}">${state.label}</a>`);
+}).on("[data-link]@mouseenter", ({ state }) => {
+	const href = state.href();
+	if (!href) return;
+	if (/^https?:\/\//i.test(href)) try {
+		const u = new URL(href);
+		if (u.origin !== location.origin) return;
+		prefetch(u.pathname + u.search);
+		return;
+	} catch {
+		return;
+	}
+	prefetch(href);
+}).render(({ state }) => html`<a data-link data-prefetch href="${state.href}">${state.label}</a>`);
 function isActive(pattern) {
 	const match = findRoute(_rou3, "GET", routePath());
 	if (!match) return false;
-	return _islandToPattern.get(match.data) === pattern;
+	return _islandToPattern.get(match.data.island) === pattern;
+}
+function parsedURL(url) {
+	return typeof url === "string" ? new URL(url, "http://localhost") : url;
+}
+function defaultRequest(url) {
+	try {
+		return new Request(url.toString());
+	} catch {
+		return {
+			url: url.toString(),
+			headers: new Headers()
+		};
+	}
+}
+async function executeLoader(loader, url, params, request, signal) {
+	try {
+		return {
+			kind: "data",
+			data: await loader({
+				params,
+				request,
+				url,
+				signal
+			}) ?? {}
+		};
+	} catch (e) {
+		if (e instanceof Redirect) return {
+			kind: "redirect",
+			to: e.to,
+			status: e.status
+		};
+		if (e instanceof LoaderError) return {
+			kind: "error",
+			status: e.status,
+			message: e.message
+		};
+		return {
+			kind: "error",
+			status: e?.status ?? 500,
+			message: e?.message ?? "Loader failed"
+		};
+	}
 }
 function router() {
 	_records = [];
 	_rou3 = createRouter();
 	_islandToPattern = /* @__PURE__ */ new Map();
+	_patternToData = /* @__PURE__ */ new Map();
 	let _popstateCleanup = null;
 	let _linkCleanup = null;
 	const builder = {
-		route(pattern, island) {
+		route(pattern, island, loader) {
+			const data = {
+				island,
+				loader
+			};
 			_records.push({
 				pattern,
-				island
+				island,
+				loader
 			});
-			addRoute(_rou3, "GET", pattern, island);
+			addRoute(_rou3, "GET", pattern, data);
+			_patternToData.set(pattern, data);
 			if (!_islandToPattern.has(island)) _islandToPattern.set(island, pattern);
 			return builder;
 		},
+		attachLoader(pattern, loader) {
+			const data = _patternToData.get(pattern);
+			if (!data) {
+				console.warn(`[ilha-router] attachLoader("${pattern}", …): pattern was never registered via .route(). The loader will be ignored.`);
+				return builder;
+			}
+			data.loader = loader;
+			const rec = _records.find((r) => r.pattern === pattern);
+			if (rec) rec.loader = loader;
+			return builder;
+		},
 		prime,
 		mount(target, { hydrate = false, registry } = {}) {
 			if (!isBrowser) {
@@ -213,6 +419,7 @@ function router() {
 			_popstateCleanup = () => window.removeEventListener("popstate", popHandler);
 			_linkCleanup = enableLinkInterception(document);
 			let unmountView = null;
+			let navAbort = null;
 			if (hydrate) {
 				const viewHost = host.querySelector("[data-router-view]") ?? host;
 				let currentMountedIsland = activeIsland();
@@ -222,10 +429,18 @@ function router() {
 					const current = activeIsland();
 					if (current !== currentMountedIsland) {
 						const thisNav = ++navVersion;
+						navAbort?.abort();
+						navAbort = new AbortController();
+						const signal = navAbort.signal;
 						queueMicrotask(async () => {
 							if (thisNav !== navVersion) return;
 							unmountView?.();
-							unmountView = await mountRouteWithHydration(current, viewHost, registry, reverseRegistry);
+							try {
+								unmountView = await mountRouteWithHydration(current, viewHost, location.pathname + location.search, signal, registry, reverseRegistry);
+							} catch (e) {
+								if (e?.name === "AbortError") return;
+								throw e;
+							}
 							currentMountedIsland = current;
 						});
 					}
@@ -237,6 +452,7 @@ function router() {
 				const unmountNavHandler = navHandler.mount(navHost);
 				return () => {
 					++navVersion;
+					navAbort?.abort();
 					unmountNavHandler();
 					navHost.remove();
 					unmountView?.();
@@ -250,23 +466,43 @@ function router() {
 			let currentMountedIsland = null;
 			let navVersion = 0;
 			unmountView = RouterView.mount(host);
-			/** Mount the active island onto the [data-router-view] container for interactivity. */
-			function mountActiveIsland(island) {
+			/**
+			* Fetch loader data and mount the active island. SPA mode also fetches
+			* from the loader endpoint — otherwise navigation after the initial SSR
+			* render would have no access to loader data.
+			*/
+			async function mountActiveIsland(island, signal) {
 				unmountIsland?.();
 				unmountIsland = null;
 				currentMountedIsland = island;
 				if (!island) return;
 				const viewHost = host?.querySelector("[data-router-view]");
-				if (viewHost) unmountIsland = island.mount(viewHost);
+				if (!viewHost) return;
+				const result = !!findRoute(_rou3, "GET", location.pathname)?.data?.loader ? await fetchLoaderData(location.pathname + location.search, signal) : {
+					kind: "data",
+					data: {}
+				};
+				if (signal.aborted) return;
+				if (result.kind === "redirect") {
+					navigate(result.to, { replace: true });
+					return;
+				}
+				const props = result.kind === "data" ? result.data : {};
+				viewHost.innerHTML = island.toString(props);
+				unmountIsland = island.mount(viewHost, props);
 			}
-			mountActiveIsland(activeIsland());
+			navAbort = new AbortController();
+			mountActiveIsland(activeIsland(), navAbort.signal);
 			const navHandler = ilha.render(() => {
 				const current = activeIsland();
 				if (current !== currentMountedIsland) {
 					const thisNav = ++navVersion;
+					navAbort?.abort();
+					navAbort = new AbortController();
+					const signal = navAbort.signal;
 					queueMicrotask(() => {
 						if (thisNav !== navVersion) return;
-						mountActiveIsland(current);
+						mountActiveIsland(current, signal);
 					});
 				}
 				return "";
@@ -277,6 +513,7 @@ function router() {
 			const unmountNavHandler = navHandler.mount(navHost);
 			return () => {
 				++navVersion;
+				navAbort?.abort();
 				unmountIsland?.();
 				unmountNavHandler();
 				navHost.remove();
@@ -291,21 +528,74 @@ function router() {
 			syncRouteFromURL(url);
 			return RouterView.toString();
 		},
-		async renderHydratable(url, registry, options = {}) {
-			syncRouteFromURL(url);
-			const island = activeIsland();
-			if (!island) return `<div data-router-empty></div>`;
+		async renderHydratable(url, registry, options = {}, request) {
+			const response = await this.renderResponse(url, registry, options, request);
+			if (response.kind === "html") return response.html;
+			if (response.kind === "error") return response.html;
+			return `<meta http-equiv="refresh" content="0; url=${response.to}">`;
+		},
+		async renderResponse(url, registry, options = {}, request) {
+			const parsed = parsedURL(url);
+			syncRouteFromURL(parsed);
+			const match = findRoute(_rou3, "GET", parsed.pathname);
+			const island = match?.data?.island ?? null;
+			if (!island) return {
+				kind: "html",
+				html: `<div data-router-empty></div>`,
+				status: 404
+			};
+			let props = {};
+			if (match?.data?.loader) {
+				const req = request ?? defaultRequest(parsed);
+				const ctrl = new AbortController();
+				const result = await executeLoader(match.data.loader, parsed, routeParams(), req, ctrl.signal);
+				if (result.kind === "redirect") return {
+					kind: "redirect",
+					to: result.to,
+					status: result.status
+				};
+				if (result.kind === "error") {
+					const escapedMessage = String(result.message).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+					const html = `<div data-router-view data-router-error="${result.status}">${escapedMessage}</div>`;
+					return {
+						kind: "error",
+						status: result.status,
+						message: result.message,
+						html
+					};
+				}
+				props = result.data;
+			}
 			const name = buildReverseRegistry(registry).get(island);
 			if (!name) {
 				console.warn(`[ilha-router] renderHydratable: active island for "${routePath()}" is not in the registry. Falling back to plain SSR — the island will not be interactive on the client.`);
-				return `<div data-router-view>${island.toString()}</div>`;
+				return {
+					kind: "html",
+					html: `<div data-router-view>${island.toString(props)}</div>`
+				};
 			}
-			return `<div data-router-view>${await island.hydratable({}, {
-				name,
-				as: "div",
-				snapshot: true,
-				...options
-			})}</div>`;
+			return {
+				kind: "html",
+				html: `<div data-router-view>${await island.hydratable(props, {
+					name,
+					as: "div",
+					snapshot: true,
+					...options
+				})}</div>`
+			};
+		},
+		async runLoader(url, request) {
+			const parsed = parsedURL(url);
+			const match = findRoute(_rou3, "GET", parsed.pathname);
+			if (!match?.data?.island) return { kind: "not-found" };
+			if (!match.data.loader) return {
+				kind: "data",
+				data: {}
+			};
+			const params = extractParams(match.params);
+			const req = request ?? defaultRequest(parsed);
+			const ctrl = new AbortController();
+			return executeLoader(match.data.loader, parsed, params, req, ctrl.signal);
 		},
 		hydrate(registry, options = {}) {
 			if (!isBrowser) {
@@ -335,8 +625,13 @@ var src_default = {
 	isActive,
 	enableLinkInterception,
 	prime,
+	prefetch,
 	RouterView,
-	RouterLink
+	RouterLink,
+	loader,
+	redirect,
+	error,
+	composeLoaders
 };
 //#endregion
-export { RouterLink, RouterView, src_default as default, enableLinkInterception, isActive, navigate, prime, routeHash, routeParams, routePath, routeSearch, router, useRoute, wrapError, wrapLayout };
+export { LOADER_ENDPOINT, LoaderError, Redirect, RouterLink, RouterView, composeLoaders, src_default as default, defineLayout, enableLinkInterception, error, isActive, loader, navigate, prefetch, prime, redirect, routeHash, routeParams, routePath, routeSearch, router, useRoute, wrapError, wrapLayout };