@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/app/modules/file-routes/presentation/Form.tsx

@@ -0,0 +1,122 @@
+/**
+ * <Form> — progressive-enhancement form bound to a route action
+ * Renders a plain <form> (works without JS); on the client submit is
+ * intercepted and routed through useAction() — pending state,
+ * optimistic updates and result/error access via children function:
+ *
+ *   <Form optimistic={(form) => ({ user: form.get("user") })}>
+ *     {(state) => (
+ *       <>
+ *         <input name="user" />
+ *         <button disabled={state.pending()}>sign in</button>
+ *         {state.error() && <p>{String(state.error())}</p>}
+ *       </>
+ *     )}
+ *   </Form>
+ */
+
+import type { JSX } from "solid-js";
+import { createContext, splitProps, useContext } from "solid-js";
+import { isServer } from "solid-js/web";
+import { useAction } from "./use-action";
+
+const FormStatusContext = createContext<FormState<unknown>>();
+
+/**
+ * Nearest <Form>'s submit state — lets nested inputs/buttons read
+ * pending without the children render-prop:
+ *
+ *   <Form><SubmitButton /></Form>
+ *   const SubmitButton = () => {
+ *     const s = useFormState();
+ *     return <button disabled={s?.pending()}>go</button>;
+ *   };
+ */
+export const useFormState = <T = unknown>(): FormState<T> | undefined =>
+	useContext(FormStatusContext) as FormState<T> | undefined;
+
+/** @deprecated renamed to useFormState — useFormStatus is React's name */
+export const useFormStatus = useFormState;
+
+export interface FormState<T = unknown> {
+	pending: () => boolean;
+	error: () => unknown;
+	result: () => T | undefined;
+	/** Last optimistic value applied while pending */
+	optimistic: () => unknown;
+}
+
+export interface FormProps<T = unknown>
+	extends Omit<JSX.FormHTMLAttributes<HTMLFormElement>, "action" | "children"> {
+	/** Route path — defaults to the current pathname */
+	action?: string;
+	/** Named action — posts `__action=<name>` for page({ actions }) */
+	name?: string;
+	/** Optimistic value applied while the action runs */
+	optimistic?: (form: FormData) => unknown;
+	/** Called with the action's JSON result */
+	onResult?: (result: T | undefined) => void;
+	/** Called when the action throws or returns an error */
+	onError?: (error: unknown) => void;
+	/** Replace history on the post-submit navigation (default push) */
+	replace?: boolean;
+	children?: JSX.Element | ((state: FormState<T>) => JSX.Element);
+}
+
+export const Form = <T = unknown>(props: FormProps<T>): JSX.Element => {
+	const [local, rest] = splitProps(props, [
+		"action",
+		"name",
+		"optimistic",
+		"onResult",
+		"onError",
+		"replace",
+		"children",
+		"method",
+		"onSubmit",
+	]);
+	const action = useAction<T>(local.action);
+	let optimisticValue: unknown;
+
+	const state: FormState<T> = {
+		pending: action.pending,
+		error: action.error,
+		result: action.result,
+		optimistic: () => optimisticValue,
+	};
+
+	const onSubmit = async (e: SubmitEvent) => {
+		const handler = local.onSubmit as ((e: SubmitEvent) => void) | undefined;
+		handler?.(e);
+		if (e.defaultPrevented || isServer) return;
+		e.preventDefault();
+		const form = new FormData(e.currentTarget as HTMLFormElement);
+		// <button data-action="save"> — per-button named action (formaction)
+		const submitter = e.submitter as HTMLElement | null;
+		if (submitter?.dataset.action)
+			form.set("__action", submitter.dataset.action);
+		if (local.optimistic) optimisticValue = local.optimistic(form);
+		try {
+			const result = await action.submit(form);
+			local.onResult?.(result);
+		} catch (error) {
+			local.onError?.(error);
+		} finally {
+			optimisticValue = undefined;
+		}
+	};
+
+	return (
+		<FormStatusContext.Provider value={state as FormState<unknown>}>
+			<form method="post" {...rest} onSubmit={onSubmit}>
+				{local.name !== undefined && (
+					<input type="hidden" name="__action" value={local.name} />
+				)}
+				{local.replace && <input type="hidden" name="__replace" value="1" />}
+				{typeof local.children === "function"
+					? (local.children as (s: FormState<T>) => JSX.Element)(state)
+					: local.children}
+			</form>
+		</FormStatusContext.Provider>
+	);
+};

package/src/app/modules/file-routes/presentation/Link.tsx

@@ -0,0 +1,132 @@
+/**
+ * <Link> — client-side navigation for file routes
+ * Intercepts plain anchor clicks and routes through the location
+ * signal (no full reload); prefetch warms the lazy route module on
+ * hover/focus or when it scrolls into view
+ */
+
+import {
+	createContext,
+	createMemo,
+	createSignal,
+	type JSX,
+	onCleanup,
+	onMount,
+	splitProps,
+	useContext,
+} from "solid-js";
+import { isServer } from "solid-js/web";
+import type { RoutePath } from "../domain/operations/typed";
+import { useLocation, useNavigate } from "./location";
+
+/** Route prefetch function provided by <FileRoutes> */
+export const PrefetchContext =
+	createContext<(path: string, shellOnly?: boolean) => void>();
+
+export const usePrefetch = ():
+	| ((path: string, shellOnly?: boolean) => void)
+	| undefined => useContext(PrefetchContext);
+
+export interface LinkProps extends JSX.AnchorHTMLAttributes<HTMLAnchorElement> {
+	/** Typed path — constrained to generated route paths when `.solid/routes.d.ts` exists */
+	to: RoutePath;
+	replace?: boolean;
+	/**
+	 * Prefetch the matched route module — "hover"/"intent" (default,
+	 * pointer+focus), "viewport" (IntersectionObserver), "render"
+	 * (immediately on mount), or false
+	 */
+	prefetch?: "hover" | "intent" | "viewport" | "render" | "shell" | false;
+	/** View Transition on click — default true when supported */
+	transition?: boolean;
+	/** Render inert — no navigation, no prefetch, aria-disabled */
+	disabled?: boolean;
+	/** Class applied while the link points at the current path */
+	activeClass?: string;
+}
+
+const isModifiedClick = (e: MouseEvent): boolean =>
+	e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0;
+
+export const Link = (props: LinkProps): JSX.Element => {
+	const [local, rest] = splitProps(props, [
+		"to",
+		"replace",
+		"prefetch",
+		"transition",
+		"disabled",
+		"activeClass",
+		"children",
+		"onClick",
+	]);
+	const navigate = useNavigate();
+	const location = useLocation();
+	const prefetch = useContext(PrefetchContext);
+	const [el, setEl] = createSignal<HTMLAnchorElement>();
+
+	const isActive = createMemo(() => location.pathname() === local.to);
+
+	const doPrefetch = () =>
+		!local.disabled && prefetch?.(local.to, local.prefetch === "shell");
+
+	onMount(() => {
+		const target = el();
+		if (!target || isServer) return;
+		if (local.prefetch === "render") {
+			doPrefetch();
+			return;
+		}
+		if (local.prefetch !== "viewport") return;
+		const observer = new IntersectionObserver((entries) => {
+			if (entries.some((e) => e.isIntersecting)) {
+				doPrefetch();
+				observer.disconnect();
+			}
+		});
+		observer.observe(target);
+		onCleanup(() => observer.disconnect());
+	});
+
+	const onClick = (e: MouseEvent) => {
+		const handler = local.onClick as ((e: MouseEvent) => void) | undefined;
+		handler?.(e);
+		if (local.disabled) {
+			e.preventDefault();
+			return;
+		}
+		if (
+			e.defaultPrevented ||
+			isModifiedClick(e) ||
+			rest.target !== undefined ||
+			rest.download !== undefined ||
+			/^https?:\/\//.test(local.to)
+		) {
+			return;
+		}
+		e.preventDefault();
+		navigate(local.to, {
+			replace: local.replace,
+			transition: local.transition,
+		});
+	};
+
+	return (
+		<a
+			{...rest}
+			ref={setEl}
+			href={local.to}
+			class={
+				isActive() && local.activeClass
+					? `${rest.class ?? ""} ${local.activeClass}`.trim()
+					: rest.class
+			}
+			aria-current={isActive() ? "page" : undefined}
+			aria-disabled={local.disabled ? "true" : undefined}
+			onClick={onClick}
+			onPointerEnter={local.prefetch === "viewport" ? undefined : doPrefetch}
+			onFocus={local.prefetch === "viewport" ? undefined : doPrefetch}
+		>
+			{local.children}
+		</a>
+	);
+};

package/src/app/modules/file-routes/presentation/ServerComponent.tsx

@@ -0,0 +1,100 @@
+/**
+ * ServerComponent (SSC-lite)
+ * Renders children to static markup on the server - on the client the
+ * markup is injected verbatim from the hydration payload and never
+ * hydrated, so its code never ships or runs in the browser. This is
+ * the zero-JS component boundary (RSC-like, without a wire protocol).
+ *
+ *   <ServerComponent name="sidebar"><HeavyMenu /></ServerComponent>
+ *   <ServerComponent name="nav" cache={300}><Nav /></ServerComponent>
+ */
+
+import type { JSX } from "solid-js";
+import { createSignal, onMount, Show, useContext } from "solid-js";
+import { isServer, renderToString } from "solid-js/web";
+import { sharedPrerenderCache } from "#app/modules/server-entry/application/usecases/prerender-cache";
+import { registerIsland } from "#render/presentation/Island";
+import { startDevSpan } from "./dev-events";
+import { HydrationContext } from "./loader-data";
+
+let autoId = 0;
+
+export interface ServerComponentProps {
+	/** Stable id - required for hydration matching; auto-indexed otherwise */
+	name?: string;
+	/** Cache the rendered markup for N seconds (per name) */
+	cache?: number;
+	/**
+	 * Remote island — the server renders `fallback` only; on the client
+	 * the live fragment is fetched from `/_island/<name>` on mount and
+	 * injected (ppr mode's dynamic hole)
+	 */
+	remote?: boolean;
+	/** Client fallback when the payload has no markup for this id */
+	fallback?: JSX.Element;
+	children?: JSX.Element;
+}
+
+const renderCached = (
+	id: string,
+	ttl: number,
+	render: () => string,
+): string => {
+	const key = `sc:${id}`;
+	const hit = sharedPrerenderCache.get(key);
+	if (hit && sharedPrerenderCache.isFresh(hit, ttl)) return hit.html;
+	const html = render();
+	sharedPrerenderCache.set(key, {
+		html,
+		status: 200,
+		headers: {},
+		tags: [`sc:${id}`],
+	});
+	return html;
+};
+
+export const ServerComponent = (props: ServerComponentProps): JSX.Element => {
+	const id = props.name ?? `sc_${autoId++}`;
+	const hydration = useContext(HydrationContext);
+
+	if (props.remote) {
+		// Register children as a fetchable island; the static shell only
+		// ships the fallback — the live fragment arrives via /_island
+		registerIsland(id, () => props.children);
+		if (isServer) {
+			return <div data-sf-remote={id}>{props.fallback ?? ""}</div>;
+		}
+		const [html, setHtml] = createSignal<string>();
+		onMount(() => {
+			const end = startDevSpan("island", id);
+			void fetch(`/_island/${encodeURIComponent(id)}`)
+				.then((r) => (r.ok ? r.text() : undefined))
+				.then((fragment) => setHtml(fragment))
+				.finally(() => end(html() !== undefined ? "ok" : "error"));
+		});
+		return (
+			<div data-sf-remote={id}>
+				<Show when={html() !== undefined} fallback={props.fallback}>
+					<div innerHTML={html()} />
+				</Show>
+			</div>
+		);
+	}
+
+	if (isServer) {
+		const render = () => renderToString(() => props.children);
+		const html = props.cache ? renderCached(id, props.cache, render) : render();
+		if (hydration) {
+			hydration.components = hydration.components ?? {};
+			hydration.components[id] = html;
+		}
+		return <div data-sf-sc={id} innerHTML={html} />;
+	}
+
+	// Client: inject the server-rendered markup - never hydrated
+	const html = hydration?.components?.[id];
+	if (html === undefined) {
+		return <div data-sf-sc={id}>{props.fallback}</div>;
+	}
+	return <div data-sf-sc={id} innerHTML={html} />;
+};

package/src/app/modules/file-routes/presentation/content-page.tsx

@@ -0,0 +1,26 @@
+/**
+ * Content page helper — turn raw markdown into a route def.
+ * `.md` files map to `kind: "content"` routes; pair with `?raw`
+ * imports or the vite plugin's content transform:
+ *
+ *   // src/routes/docs/intro.tsx (or .md via plugin)
+ *   export default content(raw)
+ */
+import type { JSX } from "solid-js";
+import { contentMeta, renderMarkdown } from "../domain/operations/content";
+import { page, type RouteDef } from "./route-def";
+
+export const content = (
+	raw: string,
+	overrides: Partial<RouteDef<unknown, Record<string, string>>> = {},
+): RouteDef<unknown, Record<string, string>> => {
+	const meta = contentMeta(raw);
+	const html = renderMarkdown(raw);
+	return page({
+		title: meta.title,
+		component: (): JSX.Element => (
+			<article class="sf-content" innerHTML={html} />
+		),
+		...overrides,
+	});
+};

package/src/app/modules/file-routes/presentation/dev-events.ts

@@ -0,0 +1,112 @@
+/**
+ * Dev Events — request waterfall instrumentation
+ * Lightweight pub/sub for dev-only diagnostics: loader fetches, action
+ * submissions and navigations record timings here; DevtoolsOverlay
+ * renders the waterfall
+ */
+
+import { createSignal } from "solid-js";
+
+export interface DevEvent {
+	id: number;
+	type:
+		| "loader"
+		| "action"
+		| "navigate"
+		| "server-fn"
+		| "island"
+		| "cache"
+		| "middleware"
+		| "error";
+	path: string;
+	/** Duration in ms — undefined while in-flight */
+	ms?: number;
+	status?: number;
+	/** Freeform detail — cache hit/miss, error text, span note */
+	detail?: string;
+	at: number;
+}
+
+const MAX_EVENTS = 50;
+const [events, setEvents] = createSignal<DevEvent[]>([]);
+let nextId = 0;
+
+/** Slow-navigation budget — events over this get flagged "slow" */
+let navBudgetMs = 500;
+
+/** `setNavBudget(800)` — ms threshold for the dev "slow" flag */
+export const setNavBudget = (ms: number): void => {
+	navBudgetMs = ms;
+};
+
+export const getNavBudget = (): number => navBudgetMs;
+
+export const devEvents = events;
+
+/** Record a dev event — returns the event id for later updates */
+export const recordDevEvent = (event: Omit<DevEvent, "at" | "id">): number => {
+	const id = nextId++;
+	setEvents((list) => [
+		...list.slice(-MAX_EVENTS + 1),
+		{ ...event, id, at: Date.now() },
+	]);
+	return id;
+};
+
+/** Patch an in-flight event — set ms/detail when a span completes */
+export const updateDevEvent = (
+	id: number,
+	patch: Partial<Omit<DevEvent, "id" | "at">>,
+): void => {
+	setEvents((list) => list.map((e) => (e.id === id ? { ...e, ...patch } : e)));
+};
+
+/**
+ * Start a dev span — records an in-flight event immediately and
+ * returns an `end` fn that fills in the duration (+ optional detail):
+ *
+ *   const end = startDevSpan("island", name);
+ *   try { await fetch(...) } finally { end("200") }
+ */
+export const startDevSpan = (
+	type: DevEvent["type"],
+	path: string,
+): ((detail?: string) => void) => {
+	const start = performance.now();
+	const id = recordDevEvent({ type, path });
+	return (detail) =>
+		updateDevEvent(id, { ms: performance.now() - start, detail });
+};
+
+/** Time an async operation and record it as a dev event */
+export const timedDevEvent = async <T>(
+	type: DevEvent["type"],
+	path: string,
+	op: () => Promise<T>,
+): Promise<T> => {
+	const start = performance.now();
+	try {
+		return await op();
+	} finally {
+		const ms = performance.now() - start;
+		recordDevEvent({
+			type,
+			path,
+			ms,
+			...(ms > navBudgetMs ? { detail: `slow (>${navBudgetMs}ms)` } : {}),
+		});
+		if (ms > navBudgetMs) {
+			console.warn(
+				`[solid-framework] slow ${type}: ${path} took ${Math.round(ms)}ms (budget ${navBudgetMs}ms)`,
+			);
+		}
+	}
+};
+
+export const clearDevEvents = (): void => {
+	setEvents([]);
+};
+
+/** Navigation events only — `navEvents()` for history UI/devtools */
+export const navEvents = (): DevEvent[] =>
+	events().filter((e) => e.type === "navigate");

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

@@ -0,0 +1,98 @@
+export { content } from "./content-page";
+export {
+	DevtoolsOverlay,
+	type DevtoolsOverlayProps,
+} from "./DevtoolsOverlay";
+export {
+	clearDevEvents,
+	type DevEvent,
+	devEvents,
+	getNavBudget,
+	navEvents,
+	recordDevEvent,
+	setNavBudget,
+	startDevSpan,
+	timedDevEvent,
+	updateDevEvent,
+} from "./dev-events";
+export {
+	AppRoutes,
+	type FileRoutesProps,
+} from "./FileRoutes";
+export {
+	Form,
+	type FormProps,
+	type FormState,
+	useFormState,
+} from "./Form";
+export { Link, type LinkProps, PrefetchContext, usePrefetch } from "./Link";
+export {
+	clearLoaderCache,
+	configureLoaderCache,
+	type LoaderCacheConfig,
+	type LoaderCacheEntry,
+} from "./loader-cache";
+export {
+	HydrationContext,
+	LoaderDataContext,
+	LoaderRetryContext,
+	readHydrated,
+	runRouteLoader,
+	useLoaderRetry,
+	useRouteData,
+} from "./loader-data";
+export {
+	type AppLocation,
+	createLocation,
+	LocationContext,
+	ParamsContext,
+	RequestContext,
+	RouteStateContext,
+	SearchContext,
+	useLocation,
+	useNavigate,
+	useNavigating,
+	useParams,
+	useRawRequest,
+	useRequestState,
+	useSearchParams,
+} from "./location";
+export { normalizeRouteModule } from "./normalize-route";
+export {
+	NavContext,
+	RouteActionsContext,
+	RouteMetaContext,
+	useNav,
+	useNavTree,
+} from "./route-contexts";
+export {
+	isRouteDef,
+	link,
+	page,
+	type RouteComponentProps,
+	type RouteDef,
+	type RouteHeadContext,
+	type RouteHeadInput,
+	redirect,
+} from "./route-def";
+export {
+	preloadFileRoute,
+	type RouteModule,
+	type RouteModules,
+} from "./route-modules";
+export {
+	ServerComponent,
+	type ServerComponentProps,
+} from "./ServerComponent";
+export {
+	Outlet,
+	type OutletProps,
+	SlotContext,
+	SlotsContext,
+	useSlot,
+} from "./slot";
+export { type RouteStatus, RouteStatusContext } from "./status";
+export { type UseAction, useAction } from "./use-action";
+export { type Optimistic, useOptimistic } from "./use-optimistic";
+export { type PreloadRoute, usePreloadRoute } from "./use-preload";
+export { type UseRoute, useRoute } from "./use-route";

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

@@ -0,0 +1,96 @@
+/**
+ * Loader Cache — page-exported `loaderCache` config backed by a
+ * pluggable in-memory store; busted by revalidateTag/revalidatePath
+ * via the tag-invalidator registry in #app/modules/cache
+ */
+
+import { isServer } from "solid-js/web";
+import {
+	onRevalidatePath,
+	onRevalidateTag,
+} from "#app/modules/cache/domain/operations/tags";
+import { useRequestEvent as requestEvent } from "#server/modules/http";
+import type { RouteLoaderFn } from "../domain/operations/loader";
+
+/** Page-exported loader cache config — `export const loaderCache = {ttl, tags}` */
+export interface LoaderCacheConfig {
+	/** Freshness window in seconds */
+	ttl?: number;
+	/** Tags for grouped invalidation via revalidateTag */
+	tags?: string[];
+}
+
+export interface LoaderCacheEntry {
+	value: unknown;
+	at: number;
+	tags: string[];
+}
+
+let loaderCache = new Map<string, LoaderCacheEntry>();
+
+/** Middleware state bag for loader ctx — empty off-server/no-event */
+export const requestState = (): Record<string, unknown> =>
+	isServer ? (requestEvent()?.state ?? {}) : {};
+
+/** Swap the loader-cache backend (e.g. shared KV in multi-instance) */
+export const configureLoaderCache = (
+	store: Map<string, LoaderCacheEntry>,
+): void => {
+	loaderCache = store;
+};
+
+onRevalidateTag((tag) => {
+	let n = 0;
+	for (const [key, entry] of loaderCache) {
+		if (entry.tags.includes(tag)) {
+			loaderCache.delete(key);
+			n++;
+		}
+	}
+	return n;
+});
+
+// revalidatePath("/users") busts loader entries keyed by that path
+onRevalidatePath((pathname) => {
+	let n = 0;
+	for (const key of loaderCache.keys()) {
+		if (key === pathname || key.startsWith(`${pathname}:`)) {
+			loaderCache.delete(key);
+			n++;
+		}
+	}
+	return n;
+});
+
+export const runLoaderCached = async (
+	loader: RouteLoaderFn,
+	key: string,
+	params: Record<string, string>,
+	request: Request,
+	parent: unknown,
+	cache: LoaderCacheConfig,
+): Promise<unknown> => {
+	const cacheKey = `${key}:${JSON.stringify(params)}`;
+	const hit = loaderCache.get(cacheKey);
+	if (
+		hit &&
+		(cache.ttl === undefined || (Date.now() - hit.at) / 1000 < cache.ttl)
+	) {
+		return hit.value;
+	}
+	const value = await loader({
+		request,
+		params,
+		parent,
+		state: requestState(),
+	});
+	loaderCache.set(cacheKey, {
+		value,
+		at: Date.now(),
+		tags: cache.tags ?? [],
+	});
+	return value;
+};
+
+/** Test hook — drop all cached loader results */
+export const clearLoaderCache = (): void => loaderCache.clear();