@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/file-routes/presentation/loader-data.ts

@@ -0,0 +1,207 @@
+/**
+ * Loader Data — page `loader` export results, resolved per navigation
+ * On the server the loader runs inline during SSR and its result is
+ * written into the render context's hydration payload; on the client
+ * the first read comes from that payload and later navigations fetch
+ * `/_server/loader`
+ */
+
+import {
+	createContext,
+	createMemo,
+	createResource,
+	type Resource,
+	useContext,
+} from "solid-js";
+import { isServer } from "solid-js/web";
+import { readHydrationPayload } from "#render/modules/render/domain";
+import type { HydrationPayload } from "#render/types";
+import { LoaderError } from "../domain/errors";
+import {
+	DEFERRED,
+	deferMarkerKey,
+	deferredRegistry,
+	extractDeferred,
+	isDeferred,
+	type LeafMapped,
+	materializeDeferred,
+} from "../domain/operations/defer";
+import type { RouteLoaderFn } from "../domain/operations/loader";
+import { LOADER_ENDPOINT } from "../domain/operations/loader";
+import { timedDevEvent } from "./dev-events";
+import {
+	type LoaderCacheConfig,
+	requestState,
+	runLoaderCached,
+} from "./loader-cache";
+
+export type LoaderDataContextValue = Resource<unknown> | undefined;
+export const LoaderDataContext = createContext<LoaderDataContextValue>();
+
+/** Re-runs the current route's loader chain — error.tsx `retry` */
+export const LoaderRetryContext = createContext<() => void>();
+
+/** Retry the current route loader — typically inside error.tsx */
+export const useLoaderRetry = (): (() => void) | undefined =>
+	useContext(LoaderRetryContext);
+
+/**
+ * The live hydration payload during SSR — provided by the routed
+ * server entry so loader results serialize into the document
+ */
+export const HydrationContext = createContext<HydrationPayload>();
+
+/** Promise source for a deferred key — payload map or stream wait */
+const deferSource = (key: string): Promise<unknown> => {
+	const resolved = readHydrationPayload().deferred;
+	if (resolved && key in resolved) return Promise.resolve(resolved[key]);
+	return (
+		window.__sfDeferWait?.(key) ??
+		Promise.reject(new Error(`[solid-framework] deferred key ${key} lost`))
+	);
+};
+
+/**
+ * Deep-walk loader data — replace Deferred leaves (server) and defer
+ * markers (client payload) with per-leaf Resources so each field
+ * suspends independently under the user's <Suspense> boundaries
+ */
+const toLeafResources = (value: unknown): unknown => {
+	if (isDeferred(value)) {
+		const [r] = createResource(() => value[DEFERRED]);
+		return r;
+	}
+	const marker = deferMarkerKey(value);
+	if (marker !== undefined) {
+		const [r] = createResource(() => deferSource(marker));
+		return r;
+	}
+	if (Array.isArray(value)) return value.map(toLeafResources);
+	if (value !== null && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value)) {
+			out[k] = toLeafResources(v);
+		}
+		return out;
+	}
+	return value;
+};
+
+/**
+ * Read the current route's loader data — reactive accessor; every
+ * defer() leaf is its own Resource so fast fields render while slow
+ * fields still stream in:
+ *
+ *   const data = useRouteData<Awaited<ReturnType<typeof loader>>>();
+ *   <p>{data()?.fast}</p>
+ *   <Suspense fallback="…">{data()?.slow?.()}</Suspense>
+ */
+export const useRouteData = <T = unknown>(): (() =>
+	| LeafMapped<T>
+	| undefined) => {
+	const resource = useContext(LoaderDataContext);
+	const mapped = createMemo(() => toLeafResources(resource?.()));
+	return () => mapped() as LeafMapped<T> | undefined;
+};
+
+/** @deprecated renamed to useRouteData — own-brand naming */
+export const useLoaderData = useRouteData;
+
+/** Read a path's loader data from the serialized hydration payload */
+export const readHydrated = (path: string): unknown =>
+	readHydrationPayload().loaders?.[path];
+
+/**
+ * Page-level `schema` export — validate route params / request body
+ * before the loader runs; a throwing assert → 400 response
+ *
+ *   export const schema = {
+ *     params: (p) => { if (!p.id) throw new Error("id required"); return p; },
+ *   };
+ */
+export interface RouteSchema {
+	params?: (raw: Record<string, string>) => unknown;
+	body?: (raw: unknown) => unknown;
+}
+
+/**
+ * Resolve a route module's loader export:
+ *   server → run it directly with the live Request, write into hydration
+ *   client → hydration payload first, else fetch the loader endpoint
+ */
+export const runRouteLoader = async (
+	loader: RouteLoaderFn | undefined,
+	key: string,
+	params: Record<string, string>,
+	request: Request | undefined,
+	hydration?: HydrationPayload,
+	parent?: unknown,
+	/** Route path to fetch on the client — layouts pass undefined */
+	fetchPath?: string,
+	/** Page-level `loaderCache` export — in-memory tagged cache */
+	cache?: LoaderCacheConfig,
+	/** Page-level `schema` export — params/body assertions (server only) */
+	schema?: RouteSchema,
+): Promise<unknown> => {
+	if (!loader) return parent;
+
+	if (isServer) {
+		if (!request) return parent;
+		// Schema validation — params first (cheap), body for non-GET
+		if (schema?.params)
+			params = schema.params(params) as Record<string, string>;
+		if (schema?.body && request.method !== "GET" && request.method !== "HEAD") {
+			const raw = await request
+				.clone()
+				.json()
+				.catch(() => null);
+			schema.body(raw);
+		}
+		const run = cache
+			? runLoaderCached(loader, key, params, request, parent, cache)
+			: loader({ request, params, parent, state: requestState() });
+		const data = await run;
+		// Deferred leaves become markers in the payload (streamed tail
+		// scripts resolve them); the component gets the raw shape —
+		// useLoaderData turns each Deferred leaf into its own resource
+		// so fields suspend independently
+		if (hydration) {
+			hydration.loaders[key] = extractDeferred(
+				data,
+				deferredRegistry(hydration),
+			);
+		}
+		return data;
+	}
+
+	const hydrated = readHydrated(key);
+	if (hydrated !== undefined) {
+		// Raw markers — leaf resources resolve each key lazily via
+		// hydration.deferred (ssr) or __sfDeferWait (stream)
+		return hydrated;
+	}
+
+	// Layout loader data only exists in the hydration payload — client
+	// navigations re-fetch the page path and the endpoint runs the
+	// full chain server-side
+	if (!fetchPath) return parent;
+
+	const response = await timedDevEvent("loader", fetchPath, () =>
+		fetch(`${LOADER_ENDPOINT}?path=${encodeURIComponent(fetchPath)}`),
+	);
+	if (!response.ok) {
+		const body = (await response.json().catch(() => null)) as {
+			error?: { code?: string; message?: string };
+		} | null;
+		throw new LoaderError(
+			body?.error?.code ?? "LOADER_ERROR",
+			body?.error?.message ?? `loader failed for ${fetchPath}`,
+			response.status,
+		);
+	}
+	const body = (await response.json()) as {
+		data: unknown;
+		deferred?: Record<string, unknown>;
+	};
+	return materializeDeferred(body.data, body.deferred);
+};

package/src/app/modules/file-routes/presentation/location.ts

@@ -0,0 +1,217 @@
+/**
+ * Location Context
+ * Minimal reactive location for file routing — history navigation
+ * on the client, static request path on the server
+ */
+
+import {
+	type Accessor,
+	createContext,
+	createSignal,
+	onCleanup,
+	useContext,
+} from "solid-js";
+import { isServer } from "solid-js/web";
+import type { RouteParamsFor, RoutePath } from "../domain/operations/typed";
+import { recordDevEvent } from "./dev-events";
+
+export interface AppLocation {
+	pathname: Accessor<string>;
+	/** Query string including "?" — reactive on the client */
+	search: Accessor<string>;
+	navigate: (
+		to: string,
+		options?: {
+			replace?: boolean;
+			/** View Transition — default true when the browser supports it */
+			transition?: boolean;
+			/** Scroll to top on nav (default true) — false keeps position */
+			scroll?: boolean;
+			/** Re-run the destination loader after the nav lands */
+			invalidate?: boolean;
+		},
+	) => void;
+	/** True while a client navigation is being applied (loading bars) */
+	navigating: Accessor<boolean>;
+	/** Previous pathname — last navigation source, for "back" UX */
+	prev: Accessor<string | undefined>;
+	/**
+	 * Shallow routing — associate state with the history entry without
+	 * navigating (modals, drawers). `state()` reads it reactively.
+	 */
+	pushState: (url: string, state: Record<string, unknown>) => void;
+	replaceState: (state: Record<string, unknown>) => void;
+	state: Accessor<Record<string, unknown>>;
+	/**
+	 * Revalidation counter — bumped by refresh() so route loader
+	 * resources re-run after mutations (single-flight)
+	 */
+	version: Accessor<number>;
+	/** Re-run the current route's loader (post-mutation refresh) */
+	refresh: () => void;
+	/** Saved scrollY for a path — used by `page({ scroll: false })` */
+	savedScroll: (path: string) => number | undefined;
+}
+
+export const LocationContext = createContext<AppLocation>();
+export const ParamsContext = createContext<Record<string, string>>({});
+/** Current Request during SSR — provided by the routed server entry */
+export const RequestContext = createContext<Request>();
+
+export const createLocation = (
+	initial = "/",
+	initialSearch = "",
+): AppLocation => {
+	const [version, setVersion] = createSignal(0);
+	const [prev, setPrev] = createSignal<string | undefined>();
+	const [state, setState] = createSignal<Record<string, unknown>>({});
+	const [navigating, setNavigating] = createSignal(false);
+	if (isServer) {
+		return {
+			pathname: () => initial,
+			search: () => initialSearch,
+			prev,
+			navigating,
+			state,
+			pushState: () => {},
+			replaceState: () => {},
+			version,
+			navigate: () => {
+				/* no-op on server */
+			},
+			refresh: () => setVersion((v) => v + 1),
+			savedScroll: () => undefined,
+		};
+	}
+
+	const [pathname, setPathname] = createSignal(
+		window.location.pathname || initial,
+	);
+	const [search, setSearch] = createSignal(window.location.search);
+
+	// Scroll restoration — save position per path, restore on back/forward
+	const positions = new Map<string, number>();
+	window.history.scrollRestoration = "manual";
+
+	const onPop = () => {
+		const path = window.location.pathname || "/";
+		setNavigating(true);
+		setPrev(pathname());
+		setPathname(path);
+		setSearch(window.location.search);
+		setState((window.history.state as Record<string, unknown>) ?? {});
+		const saved = positions.get(path);
+		queueMicrotask(() => {
+			window.scrollTo(0, saved ?? 0);
+			setNavigating(false);
+		});
+	};
+	window.addEventListener("popstate", onPop);
+	onCleanup(() => window.removeEventListener("popstate", onPop));
+
+	return {
+		pathname,
+		search,
+		prev,
+		navigating,
+		state,
+		pushState: (url, s) => {
+			window.history.pushState(s, "", url || undefined);
+			setState(s);
+		},
+		replaceState: (s) => {
+			window.history.replaceState(s, "");
+			setState(s);
+		},
+		version,
+		refresh: () => setVersion((v) => v + 1),
+		savedScroll: (path) => positions.get(path),
+		navigate: (to, options) => {
+			positions.set(pathname(), window.scrollY);
+			recordDevEvent({ type: "navigate", path: to });
+			setNavigating(true);
+			const apply = () => {
+				setPrev(pathname());
+				if (options?.replace) window.history.replaceState(null, "", to);
+				else window.history.pushState(null, "", to);
+				setPathname(window.location.pathname);
+				setSearch(window.location.search);
+				if (options?.scroll !== false) window.scrollTo(0, 0);
+				if (options?.invalidate) setVersion((v) => v + 1);
+				// one frame for the router to swap — Suspense may still show
+				// fallbacks for loaders, but the URL nav itself is done
+				requestAnimationFrame(() => setNavigating(false));
+			};
+			// View Transitions — progressive enhancement when supported,
+			// `transition: false` opts out for this navigation
+			const startViewTransition = (
+				document as Document & {
+					startViewTransition?: (cb: () => void) => void;
+				}
+			).startViewTransition;
+			if (startViewTransition && options?.transition !== false)
+				startViewTransition.call(document, apply);
+			else apply();
+		},
+	};
+};
+
+/**
+ * Middleware-written request state — provided by the routed server
+ * entry; empty object on the client. `useRouteState<T>()` reads it
+ * with the consumer's own state type
+ */
+export const RouteStateContext = createContext<Record<string, unknown>>({});
+
+/**
+ * Validated search params — route modules export `validateSearch`
+ * to parse/coerce `?query`; FileRoutes provides the result here.
+ * Defaults to the raw Record<string,string> when no validator
+ */
+export const SearchContext = createContext<unknown>({});
+
+/** Typed search params — `useSearchParams<{ page: number }>()` */
+export const useSearchParams = <T = Record<string, string>>(): T =>
+	useContext(SearchContext) as T;
+
+/** Raw Request from the client-side render context (empty post-hydration) */
+export const useRawRequest = (): Request | undefined =>
+	useContext(RequestContext);
+
+/** @deprecated renamed to useRawRequest — avoids confusion with useRequestEvent */
+export const useRequest = useRawRequest;
+
+/**
+ * Read middleware-written request state (client side) — the same
+ * state bag as server `useRequestState`, typed by the consumer
+ */
+export const useRequestState = <
+	T extends Record<string, unknown> = Record<string, unknown>,
+>(): T => useContext(RouteStateContext) as T;
+
+/** @deprecated renamed to useRequestState — same state bag both sides */
+export const useRouteState = useRequestState;
+
+export const useLocation = (): AppLocation => {
+	const ctx = useContext(LocationContext);
+	if (!ctx) {
+		throw new Error("[solid-framework] useLocation must be inside FileRoutes");
+	}
+	return ctx;
+};
+
+export const useNavigate = (): AppLocation["navigate"] =>
+	useLocation().navigate;
+
+/** True while a client navigation is in flight — for loading bars */
+export const useNavigating = (): Accessor<boolean> => useLocation().navigating;
+
+/**
+ * Typed params — `useParams<{ id: string }>()` for an ad-hoc shape or
+ * `useParams<"/users/[id]">()` for params derived from the route path
+ * (uses GeneratedRoutes when `.solid/routes.d.ts` is generated)
+ */
+export const useParams = <
+	P extends string | Record<string, string> = Record<string, string>,
+>(): P extends RoutePath ? RouteParamsFor<P> : P =>
+	useContext(ParamsContext) as never;

package/src/app/modules/file-routes/presentation/normalize-route.ts

@@ -0,0 +1,155 @@
+/**
+ * Route Module Normalization
+ * Lifts a `page()` definition into the flat module shape the runtime
+ * expects — `{ default: component, loader, beforeLoad, schema, ... }` —
+ * wrapping the component with head/transition handling
+ */
+
+import { type Component, createComponent } from "solid-js";
+import { seoTags, useHeadEffect } from "#head/presentation/useHead";
+import type { SeoMetaInput } from "#head/types";
+import type { RouteActionContext } from "../domain/operations/actions";
+import type { LoaderContext } from "../domain/operations/loader";
+import {
+	isRouteDef,
+	type RouteComponentProps,
+	type RouteDef,
+	redirect,
+} from "./route-def";
+
+/** `page({ actions })` → flat `action` export dispatching by __action */
+const dispatchActions = (
+	actions: NonNullable<RouteDef["actions"]>,
+): ((ctx: RouteActionContext) => Promise<unknown>) => {
+	return async (ctx) => {
+		const keys = Object.keys(actions);
+		const name =
+			String(ctx.form.get("__action") ?? "") ||
+			(keys.length === 1 ? keys[0] : "default");
+		const fn = actions[name] ?? actions.default;
+		if (!fn)
+			throw new Error(
+				`[solid-framework] unknown action "${name}" (have: ${keys.join(", ")})`,
+			);
+		return fn(ctx);
+	};
+};
+
+/** Wrap the route component so `page({ head })` reaches the head sink */
+const withHead = <D, Q>(
+	def: RouteDef<D, Q>,
+): Component<RouteComponentProps<D, Q>> => {
+	if (
+		!def.head &&
+		!def.robots &&
+		!def.title &&
+		!def.canonical &&
+		!def.description &&
+		!def.keywords &&
+		!def.image
+	)
+		return def.component;
+	const head = def.head;
+	const extra: SeoMetaInput = {
+		...(def.robots ? { robots: def.robots } : {}),
+		...(def.title ? { title: def.title } : {}),
+		...(def.canonical ? { canonical: def.canonical } : {}),
+		...(def.description ? { description: def.description } : {}),
+		...(def.keywords ? { keywords: def.keywords } : {}),
+		...(def.image ? { ogImage: def.image, twitterImage: def.image } : {}),
+	};
+	return (props: RouteComponentProps<D, Q>) => {
+		useHeadEffect(() => {
+			const out = head
+				? head({ params: props.params, search: props.search, data: props.data })
+				: {};
+			const tags = Array.isArray(out) ? out : seoTags(out);
+			return [...tags, ...seoTags(extra)];
+		});
+		return createComponent(def.component, props);
+	};
+};
+
+/** head + transition-name wrapper around `page({ component })` */
+const wrapPage = <D, Q>(
+	def: RouteDef<D, Q>,
+): Component<RouteComponentProps<D, Q>> => {
+	const Headed = withHead(def);
+	if (!def.transition) return Headed;
+	return (props: RouteComponentProps<D, Q>) =>
+		createComponent("div" as unknown as Component<{ children?: unknown }>, {
+			get children() {
+				return createComponent(Headed, props);
+			},
+			style: { "view-transition-name": def.transition } as never,
+		});
+};
+
+/**
+ * Normalize a resolved route module - if `default` is a page() def,
+ * lift its fields into the flat module shape the runtime expects
+ */
+export const normalizeRouteModule = <M extends Record<string, unknown>>(
+	mod: M,
+): M => {
+	const def = mod.default;
+	if (!isRouteDef(def)) return mod;
+	return {
+		...mod,
+		default: wrapPage(def),
+		...(def.load ? { loader: def.load } : {}),
+		...(def.guard?.length || def.before || def.redirect
+			? {
+					beforeLoad: async (ctx: LoaderContext) => {
+						if (def.redirect) return redirect(def.redirect);
+						for (const g of def.guard ?? []) {
+							const r = await g(ctx);
+							if (r instanceof Response) return r;
+						}
+						return def.before?.(ctx);
+					},
+				}
+			: {}),
+		...(def.cache || def.ttl !== undefined
+			? {
+					loaderCache: {
+						...(def.cache ?? {}),
+						...(def.ttl !== undefined ? { ttl: def.ttl } : {}),
+					},
+				}
+			: {}),
+		...(def.params || def.body
+			? { schema: { params: def.params, body: def.body } }
+			: {}),
+		...(def.search ? { validateSearch: def.search } : {}),
+		...(def.actions
+			? {
+					action: dispatchActions(def.actions),
+					actionNames: Object.keys(def.actions),
+				}
+			: {}),
+		...(def.shell ? { shell: def.shell } : {}),
+		...(def.error ? { error: def.error } : {}),
+		...(def.loading ? { loading: def.loading } : {}),
+		...(def.poll
+			? {
+					poll: typeof def.poll === "number" ? def.poll : def.poll.every,
+					...(typeof def.poll === "object" && def.poll.pauseHidden
+						? { pollPauseHidden: true }
+						: {}),
+				}
+			: {}),
+		...(def.transition ? { transition: def.transition } : {}),
+		...(def.staleTime !== undefined ? { staleTime: def.staleTime } : {}),
+		...(def.offline !== undefined ? { offline: def.offline } : {}),
+		...(def.robots ? { robots: def.robots } : {}),
+		...(def.scripts !== undefined ? { scripts: def.scripts } : {}),
+		...(def.layout === false ? { layout: false } : {}),
+		...(def.scroll === false ? { scroll: false } : {}),
+		...(def.order !== undefined ? { order: def.order } : {}),
+		...(def.meta ? { meta: def.meta } : {}),
+		...(def.streaming !== undefined ? { streaming: def.streaming } : {}),
+		...(def.prerender ? { prerender: def.prerender } : {}),
+		...(def.staticParams ? { staticParams: def.staticParams } : {}),
+	};
+};