@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,13 @@
+/**
+ * Route Status Context
+ * The render pipeline provides a mutable status slot; FileRoutes
+ * writes 404/500 into it so the HTTP response gets the right code
+ */
+
+import { createContext } from "solid-js";
+
+export interface RouteStatus {
+	status: number;
+}
+
+export const RouteStatusContext = createContext<RouteStatus>();

package/src/app/modules/file-routes/presentation/use-action.ts

@@ -0,0 +1,81 @@
+/**
+ * useAction — submit FormData to the current route's `action` export
+ * POSTs to the current URL; the server dispatches to the matched
+ * route's action and returns its Response (JSON or redirect)
+ */
+
+import { createSignal, onCleanup } from "solid-js";
+import { isServer } from "solid-js/web";
+import { readHydrationPayload } from "#render/modules/render/domain";
+import { timedDevEvent } from "./dev-events";
+import { useLocation } from "./location";
+
+export interface UseAction<T = unknown> {
+	/** Submit a FormData (or a form element) to the route action */
+	submit: (form: FormData | HTMLFormElement) => Promise<T | undefined>;
+	pending: () => boolean;
+	result: () => T | undefined;
+	error: () => unknown;
+}
+
+export const useAction = <T = unknown>(path?: string): UseAction<T> => {
+	const location = useLocation();
+	const [pending, setPending] = createSignal(false);
+	const [result, setResult] = createSignal<T>();
+	const [error, setError] = createSignal<unknown>();
+	let alive = true;
+	onCleanup(() => {
+		alive = false;
+	});
+
+	const submit = async (input: FormData | HTMLFormElement) => {
+		if (isServer) return undefined;
+		const form = input instanceof HTMLFormElement ? new FormData(input) : input;
+		// <Form replace> — history replace on redirect follow
+		const replace = form.get("__replace") === "1";
+		form.delete("__replace");
+		setPending(true);
+		setError(undefined);
+		const target = path ?? location.pathname();
+		try {
+			const response = await timedDevEvent("action", target, () =>
+				fetch(target, {
+					method: "POST",
+					headers: { "x-sf-flight": target },
+					body: form,
+				}),
+			);
+			if (response.redirected) {
+				location.navigate(new URL(response.url).pathname, { replace });
+				return undefined;
+			}
+			const data = (await response.json()) as T & {
+				__flight?: {
+					data?: unknown;
+					deferred?: Record<string, unknown>;
+				};
+			};
+			// Single-flight — loader data rides the mutation response;
+			// write it into the hydration payload and re-run the loader
+			const flight = data?.__flight;
+			if (flight && "data" in flight) {
+				const payload = readHydrationPayload();
+				payload.loaders[target] = flight.data;
+				if (flight.deferred) {
+					payload.deferred = { ...payload.deferred, ...flight.deferred };
+				}
+				location.refresh();
+				delete data.__flight;
+			}
+			if (alive) setResult(() => data as T);
+			return data as T;
+		} catch (e) {
+			if (alive) setError(e);
+			return undefined;
+		} finally {
+			if (alive) setPending(false);
+		}
+	};
+
+	return { submit, pending, result, error };
+};

package/src/app/modules/file-routes/presentation/use-optimistic.ts

@@ -0,0 +1,50 @@
+/**
+ * useOptimistic — show a pending value while an action/server call
+ * is in flight; falls back to the committed value on settle:
+ *
+ *   const { value, pending, optimistic } = useOptimistic(() => count());
+ *   // in a submit handler:
+ *   await optimistic(count() + 1, () => save(count() + 1));
+ *
+ * `value()` returns the optimistic value while pending, the committed
+ * value otherwise.
+ */
+
+import { type Accessor, createSignal } from "solid-js";
+
+export interface Optimistic<T> {
+	/** Committed or optimistic value */
+	value: Accessor<T>;
+	pending: Accessor<boolean>;
+	/** Rejection from the last commit — cleared on the next optimistic call */
+	error: Accessor<unknown>;
+	/**
+	 * Apply `next` optimistically, run `commit`, then clear — the
+	 * committed source is expected to update during/after commit; a
+	 * rejected commit is exposed via `error` (the error is swallowed)
+	 */
+	optimistic: (next: T, commit: () => Promise<unknown>) => Promise<void>;
+}
+
+export const useOptimistic = <T>(committed: Accessor<T>): Optimistic<T> => {
+	const [pending, setPending] = createSignal(false);
+	const [error, setError] = createSignal<unknown>();
+	const [optimisticValue, setOptimisticValue] = createSignal<T>();
+	return {
+		value: () => (pending() ? (optimisticValue() as T) : committed()),
+		pending,
+		error,
+		optimistic: async (next, commit) => {
+			setOptimisticValue(() => next);
+			setPending(true);
+			setError(undefined);
+			try {
+				await commit();
+			} catch (e) {
+				setError(() => e);
+			} finally {
+				setPending(false);
+			}
+		},
+	};
+};

package/src/app/modules/file-routes/presentation/use-preload.ts

@@ -0,0 +1,38 @@
+/**
+ * usePreloadRoute — preload a route's module (and `/_server/loader`
+ * data on the client) on pointer intent. Returns props to spread on
+ * a link or an imperative `preload()`:
+ *
+ *   const preload = usePreloadRoute("/blog");
+ *   <a {...preload.props} href="/blog">…</a>
+ *   preload.now();
+ */
+
+import { usePrefetch } from "./Link";
+
+export interface PreloadRoute {
+	/** Props for hover/focus intent prefetching */
+	props: { onPointerEnter: () => void; onFocus: () => void };
+	/** Preload immediately */
+	now: () => void;
+}
+
+export const usePreloadRoute = (path: string): PreloadRoute => {
+	const prefetch = usePrefetch();
+	let done = false;
+	const run = () => {
+		if (done) return;
+		done = true;
+		prefetch?.(path);
+		// Warm the loader endpoint too — renders are instant on nav
+		if (typeof fetch !== "undefined") {
+			void fetch(`/_server/loader?path=${encodeURIComponent(path)}`).catch(
+				() => {},
+			);
+		}
+	};
+	return {
+		props: { onPointerEnter: run, onFocus: run },
+		now: run,
+	};
+};

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

@@ -0,0 +1,254 @@
+/**
+ * `useRoute()` — the one route hook. Replaces the useParams/useLoaderData/
+ * useNavigate/useSearchParams/useRequestState/useLoaderRetry set with a
+ * single accessor object:
+ *
+ *   const r = useRoute<User>();
+ *   r.data()?.name        // loader data
+ *   r.params.id           // route params
+ *   r.search.page         // search params
+ *   r.state("user")       // middleware/request state bag
+ *   r.retry()             // re-run loader after error
+ *   r.navigate("/x")      // client nav
+ *   r.path                // current pathname
+ */
+
+import {
+	type Accessor,
+	createEffect,
+	createRoot,
+	on,
+	useContext,
+} from "solid-js";
+import type { LeafMapped } from "../domain/operations/defer";
+import {
+	link,
+	type ParamsFor,
+	type RoutePath,
+	type SearchFor,
+} from "../domain/operations/typed";
+import { type DevEvent, navEvents } from "./dev-events";
+import { PrefetchContext } from "./Link";
+import { clearLoaderCache } from "./loader-cache";
+import { useLoaderRetry, useRouteData } from "./loader-data";
+import {
+	type AppLocation,
+	useLocation,
+	useNavigate,
+	useParams,
+	useRequestState,
+	useSearchParams,
+} from "./location";
+import { RouteActionsContext, RouteMetaContext } from "./route-contexts";
+import { useAction } from "./use-action";
+
+export interface UseRoute<
+	D = unknown,
+	P = Record<string, string>,
+	S = Record<string, unknown>,
+	Q = Record<string, string>,
+> {
+	/** Loader data accessor — `r.data()` reactive (deferred leaves resolved) */
+	data: Accessor<LeafMapped<D> | undefined>;
+	/** Route params — `r.params.id` */
+	params: P;
+	/** Search/query — `r.search.page`; typed via `page({ search })` */
+	search: Q;
+	/** Middleware/request state bag — `r.state.user` */
+	state: S;
+	/** Current pathname */
+	path: string;
+	location: AppLocation;
+	navigate: ReturnType<typeof useNavigate>;
+	/** Re-run the loader (after an error boundary) */
+	retry: (() => void) | undefined;
+	/** Warm a route's module + loader ahead of navigation */
+	preload: (path: string) => void;
+	/** Route metadata from `page({ meta })` */
+	meta: Record<string, unknown>;
+	/** Call a named `page({ actions })` entry — `r.submit("save", {x:1})` */
+	submit: (
+		name: string,
+		fields?: Record<string, unknown> | FormData,
+	) => Promise<unknown>;
+	/** Serializable {path, params, search, data} — share/debug */
+	snapshot: () => {
+		path: string;
+		params: unknown;
+		search: unknown;
+		data: unknown;
+	};
+	/** Clear loader cache then re-run the loader chain */
+	revalidate: () => void;
+	/** Bump the route version — re-run loaders without cache clear */
+	refresh: () => void;
+	/** Previous pathname — `r.prev()` for back UX */
+	prev: () => string | undefined;
+	/** Merge a patch into the current query — `r.searchWith({page: 2})` */
+	searchWith: (patch: Record<string, string | number | boolean>) => string;
+	/** Active check — `r.is("/users")` or prefix match `r.is("/users", true)` */
+	is: (path: string, prefix?: boolean) => boolean;
+	/** Current full path + query — for "copy link" UI */
+	share: () => string;
+	/** Reactive parsed query record — `r.query().page` */
+	query: Accessor<Record<string, string>>;
+	/** Back navigation — goes to `prev()` or `fallback` */
+	back: (fallback?: string) => void;
+	/** Shallow state — modal/drawer state in the history entry */
+	historyState: Accessor<Record<string, unknown>>;
+	pushState: (url: string, state: Record<string, unknown>) => void;
+	replaceState: (state: Record<string, unknown>) => void;
+	/** Single typed param accessor — `r.param("id")` */
+	param: <K extends keyof P>(name: K) => string | undefined;
+	/** Resolves once on the next location change — nav/redirect awaits */
+	wait: () => Promise<void>;
+	/** Runs `cb` once when the location changes away — form/draft cleanup */
+	onLeave: (cb: () => void) => void;
+	/** True while a navigation is being applied — loading bars */
+	navigating: Accessor<boolean>;
+	/**
+	 * Typed href — `r.to("/users/[id]", { id: "1" }, { tab: "t" })`
+	 * (same resolution as `link()`; literal-checked when
+	 * `.solid/routes.d.ts` is generated)
+	 */
+	to: <R extends RoutePath>(
+		path: R,
+		params?: ParamsFor<R>,
+		search?: SearchFor<R>,
+	) => string;
+	/**
+	 * AbortSignal aborted when the route unloads — pass to `fetch`
+	 * and listeners so they cancel on navigation
+	 */
+	signal: AbortSignal;
+	/** Named `page({ actions })` keys — for rendering submit buttons */
+	actions: string[];
+	/** Reactive navigate-type dev events — history/debug UI */
+	navEvents: Accessor<DevEvent[]>;
+}
+
+export const useRoute = <
+	D = unknown,
+	P extends string | Record<string, string> = Record<string, string>,
+	S extends Record<string, unknown> = Record<string, unknown>,
+	Q = Record<string, string>,
+>(): UseRoute<D, P extends string ? never : P, S, Q> => {
+	const data = useRouteData<D>();
+	const params = useParams<P>() as P extends string ? never : P;
+	const search = useSearchParams<Q>();
+	const state = useRequestState() as S;
+	const location = useLocation();
+	const navigate = useNavigate();
+	const retry = useLoaderRetry();
+	const prefetch = useContext(PrefetchContext);
+	const meta = useContext(RouteMetaContext);
+	const actionNames = useContext(RouteActionsContext);
+	const action = useAction();
+	// Aborted when the location changes away — caller passes it to
+	// fetch()/listeners for automatic cleanup
+	const signalCtl = new AbortController();
+	createRoot((dispose) => {
+		createEffect(
+			on(
+				() => `${location.pathname()}${location.search()}`,
+				() => {
+					dispose();
+					signalCtl.abort();
+				},
+				{ defer: true },
+			),
+		);
+	});
+	return {
+		data,
+		params,
+		search,
+		state,
+		get path() {
+			return location.pathname();
+		},
+		location,
+		navigate,
+		retry,
+		preload: (path: string) => prefetch?.(path),
+		meta,
+		submit: (name: string, fields?: Record<string, unknown> | FormData) => {
+			const form = fields instanceof FormData ? fields : new FormData();
+			if (!(fields instanceof FormData) && fields) {
+				for (const [k, v] of Object.entries(fields)) {
+					form.set(k, String(v));
+				}
+			}
+			form.set("__action", name);
+			return action.submit(form);
+		},
+		snapshot: () => ({
+			path: location.pathname(),
+			params,
+			search,
+			data: data(),
+		}),
+		revalidate: () => {
+			clearLoaderCache();
+			(retry ?? location.refresh)();
+		},
+		refresh: location.refresh,
+		prev: () => location.prev(),
+		searchWith: (patch) => {
+			const q = new URLSearchParams(location.search());
+			for (const [k, v] of Object.entries(patch)) q.set(k, String(v));
+			return `${location.pathname()}?${q}`;
+		},
+		is: (path, prefix) =>
+			prefix
+				? location.pathname().startsWith(path)
+				: location.pathname() === path,
+		share: () => `${location.pathname()}${location.search()}`,
+		query: () =>
+			Object.fromEntries(new URLSearchParams(location.search()).entries()),
+		back: (fallback = "/") =>
+			location.navigate(location.prev() ?? fallback, { replace: true }),
+		historyState: location.state,
+		pushState: location.pushState,
+		replaceState: location.replaceState,
+		param: (name) => (params as Record<string, string>)[name as string],
+		navigating: location.navigating,
+		onLeave: (cb) => {
+			createRoot((dispose) => {
+				createEffect(
+					on(
+						() => `${location.pathname()}${location.search()}`,
+						() => {
+							dispose();
+							cb();
+						},
+						{ defer: true },
+					),
+				);
+			});
+		},
+		to: (path, p, q) => link(path, p, q),
+		get signal() {
+			return signalCtl.signal;
+		},
+		get actions() {
+			return actionNames;
+		},
+		navEvents,
+		wait: () =>
+			new Promise<void>((resolve) => {
+				createRoot((dispose) => {
+					createEffect(
+						on(
+							() => `${location.pathname()}${location.search()}`,
+							() => {
+								dispose();
+								resolve();
+							},
+							{ defer: true },
+						),
+					);
+				});
+			}),
+	};
+};

package/src/app/modules/flash/domain/operations/flash.ts

@@ -0,0 +1,70 @@
+/**
+ * Flash — one-time message across a redirect (toast pattern):
+ *
+ *   // in an action, before redirecting:
+ *   const res = redirect("/dashboard");
+ *   setFlash(res.headers, { kind: "success", text: "Saved" });
+ *   return res;
+ *
+ *   // in the target page loader:
+ *   const flash = readFlash(ctx.request, ctx.headers?); → {kind,text}
+ *   // and in components:
+ *   const flash = useFlash();
+ */
+
+import { useRouteState } from "#app/modules/file-routes/presentation/location";
+import type { AppMiddleware } from "#app/types";
+import {
+	deleteCookie,
+	getCookie,
+	setCookie,
+} from "#server/modules/http/domain/operations/cookies";
+
+export const FLASH_COOKIE = "__flash";
+
+/** Queue a one-time flash payload on a (redirect) response */
+export const setFlash = (headers: Headers, data: unknown): void => {
+	setCookie(headers, FLASH_COOKIE, encodeURIComponent(JSON.stringify(data)), {
+		httpOnly: true,
+		sameSite: "lax",
+		path: "/",
+		// short-lived — it should be consumed on the next request
+		maxAge: 60,
+	});
+};
+
+/**
+ * Read + clear the flash for this request — `headers` (the response)
+ * gets a Max-Age=0 so the cookie self-destructs after being read
+ */
+export const readFlash = <T = unknown>(
+	request: Request,
+	responseHeaders?: Headers,
+): T | null => {
+	const raw = getCookie(request, FLASH_COOKIE);
+	if (raw === undefined) return null;
+	if (responseHeaders)
+		deleteCookie(responseHeaders, FLASH_COOKIE, { path: "/" });
+	try {
+		return JSON.parse(decodeURIComponent(raw)) as T;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * Middleware — moves the flash cookie into `state.flash` (serialized
+ * into the hydration payload, so components can read it). The cookie
+ * is short-lived (60s) so it self-expires after one navigation
+ */
+export const flashMiddleware = (): AppMiddleware => {
+	return async (ctx) => {
+		const value = readFlash(ctx.request);
+		if (value !== null) ctx.state.flash = value;
+		return undefined;
+	};
+};
+
+/** Read the flashed payload in components — from route state/hydration */
+export const useFlash = <T = unknown>(): T | null =>
+	(useRouteState<{ flash?: T | null }>().flash ?? null) as T | null;

package/src/app/modules/flash/index.ts

@@ -0,0 +1 @@
+export * from "./domain/operations/flash";

package/src/app/modules/fonts/domain/operations/font.ts

@@ -0,0 +1,91 @@
+/**
+ * Fonts — `defineFont()` produces head tags for self-hosted or
+ * Google fonts: preload link + stylesheet link + @font-face style.
+ *
+ *   const inter = defineFont({
+ *     family: "Inter",
+ *     src: "/fonts/inter.woff2",        // self-hosted
+ *     weight: "400 700",
+ *   });
+ *   const gfont = defineFont({
+ *     google: { family: "Inter", weights: [400, 700] },
+ *   });
+ *   useHead(...inter.head);
+ */
+
+import { createHeadTag, linkTag } from "#head/modules/head/domain";
+
+export interface FontDef {
+	/** Self-hosted: font file URL(s) under public/ */
+	src?: string | string[];
+	/** Google Fonts shortcut — generates css2 link, no self-host */
+	google?: { family: string; weights?: number[]; display?: string };
+	/** Family name (required with src; optional override for google) */
+	family?: string;
+	weight?: string | number;
+	style?: string;
+}
+
+export interface DefinedFont {
+	/** CSS family name to reference in stylesheets */
+	family: string;
+	/** HeadTag[] — spread into useHead() */
+	head: ReturnType<typeof createHeadTag>[];
+}
+
+export const defineFont = (def: FontDef): DefinedFont => {
+	const family = def.family ?? def.google?.family ?? "sans";
+	const head: DefinedFont["head"] = [];
+
+	if (def.google) {
+		const weights = (def.google.weights ?? [400]).sort().join(";");
+		const display = def.google.display ?? "swap";
+		head.push(
+			linkTag({ rel: "preconnect", href: "https://fonts.googleapis.com" }),
+			createHeadTag("link", {
+				rel: "preconnect",
+				href: "https://fonts.gstatic.com",
+				crossorigin: "anonymous",
+			}),
+			linkTag({
+				rel: "stylesheet",
+				href: `https://fonts.googleapis.com/css2?family=${encodeURIComponent(def.google.family)}:wght@${weights}&display=${display}`,
+			}),
+		);
+		return { family, head };
+	}
+
+	const files = [def.src ?? []].flat();
+	for (const src of files) {
+		head.push(
+			createHeadTag("link", {
+				rel: "preload",
+				href: src,
+				as: "font",
+				type: `font/${src.split(".").pop()}`,
+				crossorigin: "anonymous",
+			}),
+		);
+	}
+	head.push(
+		createHeadTag(
+			"style",
+			{},
+			files
+				.map(
+					(src) =>
+						`@font-face{font-family:"${family}";src:url("${src}") format("${
+							src.endsWith("woff2")
+								? "woff2"
+								: src.endsWith("woff")
+									? "woff"
+									: "truetype"
+						}");${def.weight !== undefined ? `font-weight:${def.weight};` : ""}${
+							def.style ? `font-style:${def.style};` : ""
+						}font-display:swap;}`,
+				)
+				.join("\n"),
+		),
+	);
+	return { family, head };
+};

package/src/app/modules/fonts/index.ts

@@ -0,0 +1 @@
+export * from "./domain/operations/font";

package/src/app/modules/i18n/domain/operations/i18n-middleware.ts

@@ -0,0 +1,76 @@
+/**
+ * i18n Middleware
+ * Detects the request locale → state.locale: path prefix first,
+ * then Accept-Language, then the default. With `redirect: true`
+ * unprefixed non-default hits 302 to the localized path (the
+ * nuxt-i18n detectBrowserLanguage equivalent):
+ *
+ *   middleware: [i18nMiddleware({ locales: ["en","th"], defaultLocale: "en" })]
+ */
+
+import type { AppMiddleware } from "#app/types";
+import type { I18nConfig } from "./locale";
+import { stripLocale } from "./locale";
+
+export interface I18nMiddlewareOptions extends I18nConfig {
+	/** Redirect unprefixed urls to the detected locale — default false */
+	redirect?: boolean;
+	/** Cookie persisting the user's choice — read before Accept-Language */
+	cookie?: string;
+}
+
+const fromAcceptLanguage = (
+	header: string,
+	locales: string[],
+): string | undefined => {
+	for (const part of header.split(",")) {
+		const tag = part.split(";")[0].trim().toLowerCase();
+		const base = tag.split("-")[0];
+		const hit = locales.find(
+			(l) => l.toLowerCase() === tag || l.toLowerCase() === base,
+		);
+		if (hit) return hit;
+	}
+	return undefined;
+};
+
+export const i18nMiddleware = (
+	options: I18nMiddlewareOptions,
+): AppMiddleware => {
+	const locales = options.locales.map((l) => l.toLowerCase());
+	return async (ctx) => {
+		const path = stripLocale(ctx.url.pathname, options);
+		// Explicit prefix wins
+		let locale = path.locale;
+		if (
+			path.locale === options.defaultLocale &&
+			path.path === ctx.url.pathname
+		) {
+			// No prefix — cookie → Accept-Language → default
+			const cookie = options.cookie
+				? ctx.request.headers
+						.get("cookie")
+						?.match(new RegExp(`${options.cookie}=([^;]+)`))?.[1]
+				: undefined;
+			locale =
+				(cookie && locales.includes(cookie.toLowerCase())
+					? cookie
+					: undefined) ??
+				fromAcceptLanguage(
+					ctx.request.headers.get("accept-language") ?? "",
+					options.locales,
+				) ??
+				options.defaultLocale;
+			if (options.redirect && locale !== options.defaultLocale) {
+				return new Response(null, {
+					status: 302,
+					headers: {
+						Location: `/${locale}${ctx.url.pathname === "/" ? "" : ctx.url.pathname}${ctx.url.search}`,
+					},
+				});
+			}
+		}
+		ctx.state.locale = locale;
+		return undefined;
+	};
+};