@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,143 @@
+export {
+	type ApiCallOptions,
+	type ApiClient,
+	ApiError,
+	type ApiMethod,
+	createApiClient,
+	type GeneratedApiPaths,
+	isApiError,
+} from "./application/usecases/api-client";
+export {
+	type ApiRouteContext,
+	type ApiRouteHandler,
+	type ApiRouteModule,
+	type ApiRouteModules,
+	buildRouteManifest,
+	contentMeta,
+	createApiRouteHandler,
+	createLoaderHandler,
+	createRouteActionHandler,
+	DEFER_MARKER,
+	DEFERRED,
+	type DeferOptions,
+	type Deferred,
+	defer,
+	deferAll,
+	deferMarkerKey,
+	deferResolveScript,
+	deferredRegistry,
+	type ExtractParams,
+	expandStaticRoutes,
+	extractDeferred,
+	type FileRoute,
+	type FileRouteMatch,
+	type GeneratedRoutes,
+	type GeneratedSearch,
+	type GenerateStaticParamsFn,
+	generateApiTypes,
+	generateRouteTypes,
+	type HasParams,
+	isDeferred,
+	isLoaderError,
+	isLoaderRequest,
+	isNotFoundError,
+	type LeafMapped,
+	LOADER_ENDPOINT,
+	LoaderError,
+	loaderErrorBody,
+	matchAllFileRoutes,
+	matchFileRoute,
+	materializeDeferred,
+	NotFoundError,
+	notFound,
+	orderDeferred,
+	type ParamsFor,
+	pathFor,
+	type RouteActionContext,
+	type RouteActionFn,
+	type RouteLoaderFn,
+	type RouteManifest,
+	type RouteParamsFor,
+	type RoutePath,
+	readDeferredRegistry,
+	relativePath,
+	renderMarkdown,
+	resolveDeferred,
+	routePaths,
+	routePattern,
+	runFileRouteLoader,
+	type SearchFor,
+} from "./domain";
+export {
+	type AppLocation,
+	AppRoutes,
+	clearDevEvents,
+	clearLoaderCache,
+	configureLoaderCache,
+	content,
+	createLocation,
+	type DevEvent,
+	DevtoolsOverlay,
+	type DevtoolsOverlayProps,
+	devEvents,
+	type FileRoutesProps,
+	Form,
+	type FormProps,
+	type FormState,
+	getNavBudget,
+	isRouteDef,
+	Link,
+	type LinkProps,
+	type LoaderCacheConfig,
+	LocationContext,
+	link,
+	normalizeRouteModule,
+	type Optimistic,
+	Outlet,
+	type OutletProps,
+	ParamsContext,
+	PrefetchContext,
+	type PreloadRoute,
+	page,
+	preloadFileRoute,
+	type RouteComponentProps,
+	type RouteDef,
+	type RouteHeadContext,
+	type RouteHeadInput,
+	type RouteModule,
+	type RouteModules,
+	RouteStateContext,
+	type RouteStatus,
+	RouteStatusContext,
+	readHydrated,
+	recordDevEvent,
+	redirect,
+	runRouteLoader,
+	SearchContext,
+	ServerComponent,
+	type ServerComponentProps,
+	SlotContext,
+	SlotsContext,
+	setNavBudget,
+	startDevSpan,
+	timedDevEvent,
+	type UseAction,
+	type UseRoute,
+	useAction,
+	useFormState,
+	useLoaderRetry,
+	useLocation,
+	useNav,
+	useNavigate,
+	useNavTree,
+	useOptimistic,
+	useParams,
+	usePrefetch,
+	usePreloadRoute,
+	useRawRequest,
+	useRequestState,
+	useRoute,
+	useRouteData,
+	useSearchParams,
+	useSlot,
+} from "./presentation";

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

@@ -0,0 +1,234 @@
+/**
+ * DevtoolsOverlay
+ * Dev-only diagnostics panel — lists the route manifest, the active
+ * match and its status. Mount inside <FileRoutes>-aware trees during
+ * development (tree-shakeable for production builds)
+ */
+
+import type { JSX } from "solid-js";
+import { createSignal, For, onCleanup, Show, useContext } from "solid-js";
+import { isServer } from "solid-js/web";
+import { readHydrationPayload } from "#render/modules/render/domain";
+import { inspectQueries } from "#stores/modules/query/query-manager";
+import type { RouteManifest } from "../domain/models";
+import { devEvents } from "./dev-events";
+import { useLocation, useParams } from "./location";
+import { RouteStatusContext } from "./status";
+
+export interface DevtoolsOverlayProps {
+	manifest: RouteManifest;
+	/** Start collapsed — default true */
+	collapsed?: boolean;
+}
+
+export const DevtoolsOverlay = (props: DevtoolsOverlayProps): JSX.Element => {
+	const location = useLocation();
+	const params = useParams();
+	const status = useContext(RouteStatusContext);
+	const [open, setOpen] = createSignal(props.collapsed !== false);
+	type Tab = "routes" | "queries" | "events" | "errors" | "islands";
+	const [tab, setTab] = createSignal<Tab>("routes");
+	const tabs: Tab[] = ["routes", "queries", "events", "errors", "islands"];
+	// Query cache snapshot — non-reactive store; poll while open
+	const [queries, setQueries] = createSignal<ReturnType<typeof inspectQueries>>(
+		[],
+	);
+	if (!isServer) {
+		const poll = setInterval(() => {
+			if (open()) setQueries(inspectQueries());
+		}, 1000);
+		onCleanup(() => clearInterval(poll));
+	}
+
+	// Diagnostics snapshot — loader keys, hydrated islands, render mode
+	const diagnostics = () => {
+		if (isServer) return { loaders: [], islands: 0 };
+		const payload = readHydrationPayload();
+		return {
+			loaders: Object.keys(payload.loaders ?? {}),
+			islands: document.querySelectorAll("[data-solid-island]").length,
+		};
+	};
+
+	const matched = () =>
+		props.manifest.find((r) => {
+			const segments = r.path.split("/").filter(Boolean);
+			const actual = location.pathname().split("/").filter(Boolean);
+			if (segments.length !== actual.length) return false;
+			return segments.every(
+				(s, i) => s.startsWith(":") || s.startsWith("*") || s === actual[i],
+			);
+		});
+
+	// Island markers in the live DOM — local islands, remotes, server comps
+	const islandEls = (): { label: string; color: string }[] => {
+		if (isServer) return [];
+		return (
+			[
+				["data-solid-island", "", "#64748b"],
+				["data-sf-remote", "remote: ", "#a78bfa"],
+				["data-sf-sc", "server: ", "#38bdf8"],
+			] as const
+		).flatMap(([attr, prefix, color]) =>
+			[...document.querySelectorAll(`[${attr}]`)].map((el) => ({
+				label: `${prefix}${el.getAttribute(attr) ?? "?"}`,
+				color,
+			})),
+		);
+	};
+
+	return (
+		<div
+			style={{
+				position: "fixed",
+				bottom: "12px",
+				right: "12px",
+				"z-index": 9999,
+				background: "#0f172a",
+				color: "#e2e8f0",
+				"font-family": "ui-monospace,monospace",
+				"font-size": "12px",
+				"border-radius": "8px",
+				border: "1px solid #334155",
+				overflow: "hidden",
+				"max-width": "360px",
+			}}
+		>
+			<button
+				type="button"
+				style={{
+					width: "100%",
+					padding: "6px 10px",
+					background: "none",
+					border: "none",
+					color: "#38bdf8",
+					cursor: "pointer",
+					"text-align": "left",
+				}}
+				onClick={() => setOpen(!open())}
+			>
+				solid devtools {open() ? "▾" : "▸"} {location.pathname()}
+			</button>
+			<Show when={open()}>
+				<div
+					style={{
+						display: "flex",
+						"border-bottom": "1px solid #334155",
+					}}
+				>
+					<For each={tabs}>
+						{(t) => (
+							<button
+								type="button"
+								style={{
+									flex: 1,
+									padding: "4px 6px",
+									background: "none",
+									border: "none",
+									"border-bottom": `2px solid ${tab() === t ? "#38bdf8" : "transparent"}`,
+									color: tab() === t ? "#38bdf8" : "#94a3b8",
+									cursor: "pointer",
+									"font-size": "11px",
+								}}
+								onClick={() => setTab(t)}
+							>
+								{t}
+							</button>
+						)}
+					</For>
+				</div>
+				<div
+					style={{
+						padding: "8px 10px",
+						"max-height": "260px",
+						overflow: "auto",
+					}}
+				>
+					<Show when={tab() === "routes"}>
+						<div style={{ color: "#94a3b8" }}>
+							match: {matched()?.path ?? "—"} params: {JSON.stringify(params)}
+						</div>
+						<div style={{ "margin-top": "4px", color: "#94a3b8" }}>
+							status: {status?.status ?? 200} · loaders:{" "}
+							{diagnostics().loaders.join(", ") || "—"} · islands:{" "}
+							{diagnostics().islands}
+						</div>
+						<div style={{ "margin-top": "6px", color: "#94a3b8" }}>routes:</div>
+						<For each={props.manifest}>
+							{(route) => (
+								<div
+									style={{
+										color:
+											route.path === matched()?.path ? "#38bdf8" : "#64748b",
+									}}
+								>
+									{route.kind === "api" ? "[api] " : ""}
+									{route.path}
+								</div>
+							)}
+						</For>
+					</Show>
+					<Show when={tab() === "queries"}>
+						<Show when={queries().length === 0}>
+							<div style={{ color: "#64748b" }}>no queries</div>
+						</Show>
+						<For each={queries()}>
+							{(q) => (
+								<div style={{ color: "#64748b" }}>
+									<span
+										style={{
+											color: q.error
+												? "#f87171"
+												: q.isFetching
+													? "#fbbf24"
+													: "#34d399",
+										}}
+									>
+										{q.error ? "✗" : q.isFetching ? "…" : "✓"}
+									</span>{" "}
+									{q.key}
+									{q.error ? ` · ${q.error}` : ""}
+								</div>
+							)}
+						</For>
+					</Show>
+					<Show when={tab() === "events"}>
+						<Show when={devEvents().length === 0}>
+							<div style={{ color: "#64748b" }}>no events</div>
+						</Show>
+						<For each={devEvents().slice(-16).reverse()}>
+							{(event) => (
+								<div style={{ color: "#64748b" }}>
+									<span style={{ color: "#38bdf8" }}>{event.type}</span>{" "}
+									{event.path} · {Math.round(event.ms ?? 0)}ms
+								</div>
+							)}
+						</For>
+					</Show>
+					<Show when={tab() === "errors"}>
+						<For each={devEvents().filter((e) => e.type === "error")}>
+							{(event) => (
+								<div style={{ color: "#f87171" }}>
+									{event.path} · {String(event.detail ?? "error")}
+								</div>
+							)}
+						</For>
+						<Show
+							when={devEvents().filter((e) => e.type === "error").length === 0}
+						>
+							<div style={{ color: "#64748b" }}>no errors</div>
+						</Show>
+					</Show>
+					<Show when={tab() === "islands"}>
+						<Show when={islandEls().length === 0}>
+							<div style={{ color: "#64748b" }}>no islands</div>
+						</Show>
+						<For each={islandEls()}>
+							{(item) => <div style={{ color: item.color }}>{item.label}</div>}
+						</For>
+					</Show>
+				</div>
+			</Show>
+		</div>
+	);
+};

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

@@ -0,0 +1,254 @@
+/**
+ * FileRoutes
+ * Renders the matched file route nested inside its layout chain —
+ * ErrorBoundary → Suspense → layouts → page. Plain createComponent
+ * (no JSX) so the module loads in plain node/test environments.
+ */
+
+import {
+	type Component,
+	createComponent,
+	createMemo,
+	ErrorBoundary,
+	type JSX,
+	Suspense,
+	useContext,
+} from "solid-js";
+import { Dynamic, isServer } from "solid-js/web";
+import {
+	type I18nConfig,
+	stripLocale,
+} from "../../i18n/domain/operations/locale";
+import { LocaleContext } from "../../i18n/presentation/use-locale";
+import {
+	type FileRouteMatch,
+	matchAllFileRoutes,
+	matchFileRoute,
+	type RouteManifest,
+} from "../domain";
+import { PrefetchContext } from "./Link";
+import { HydrationContext } from "./loader-data";
+import {
+	createLocation,
+	LocationContext,
+	ParamsContext,
+	RequestContext,
+} from "./location";
+import { createPageTree } from "./page-tree";
+import { computeNavItems, NavContext } from "./route-contexts";
+import { renderErrorView, renderNotFoundView } from "./route-fallbacks";
+import {
+	createRoutePrefetch,
+	lazyModule,
+	peekModule,
+	type RouteModules,
+} from "./route-modules";
+import { SlotContext, SlotsContext } from "./slot";
+import { RouteStatusContext } from "./status";
+
+export interface FileRoutesProps {
+	manifest: RouteManifest;
+	/** import.meta.glob map over routesDir (lazy or eager) */
+	modules: RouteModules;
+	/** Request path on the server — defaults to window.location */
+	url?: string;
+	/** Loading fallback while route modules resolve */
+	fallback?: JSX.Element;
+	/** 404 component used when no route matches */
+	notFound?: Component;
+	/** i18n routing — strips locale prefixes and provides useLocale() */
+	i18n?: I18nConfig;
+}
+
+export const AppRoutes = (props: FileRoutesProps): JSX.Element => {
+	const request = useContext(RequestContext);
+	const requestUrl = request ? new URL(request.url) : undefined;
+	const url = props.url ?? requestUrl?.pathname ?? "/";
+	const location = createLocation(url, requestUrl?.search ?? "");
+	const status = useContext(RouteStatusContext);
+	const hydration = useContext(HydrationContext);
+	const stripped = createMemo(() =>
+		props.i18n
+			? stripLocale(location.pathname(), props.i18n)
+			: { locale: "", path: location.pathname() },
+	);
+	const match = createMemo(() => {
+		const m = matchFileRoute(stripped().path, props.manifest);
+		// Prefer the non-slot route as the primary match when a @slot
+		// route scored the same path (slots render alongside, not primary)
+		if (m?.route.slot) {
+			const primary = matchAllFileRoutes(stripped().path, props.manifest).find(
+				(x) => !x.route.slot,
+			);
+			if (primary) return primary;
+		}
+		return m;
+	});
+	// `@slot` parallel routes matching the same path — rendered as
+	// siblings, each under its own SlotContext (consumed by <Outlet>)
+	const slotMatches = createMemo(() =>
+		matchAllFileRoutes(stripped().path, props.manifest).filter(
+			(m) => m.route.slot,
+		),
+	);
+
+	const renderMatch = (m: FileRouteMatch): JSX.Element =>
+		createComponent(ErrorBoundary, {
+			fallback: (error: unknown, reset: () => void) =>
+				renderErrorView(
+					{
+						modules: props.modules,
+						status,
+						notFound: props.notFound,
+					},
+					m,
+					error,
+					reset,
+				),
+			get children() {
+				return createComponent(Suspense, {
+					get fallback() {
+						// page({ loading }) / page({ shell }) beat the
+						// loading.tsx convention, which beats props.fallback
+						const pageMod = peekModule(props.modules, m.route.file) as
+							| { loading?: Component; shell?: Component }
+							| undefined;
+						const inlineFallback = pageMod?.loading ?? pageMod?.shell;
+						if (inlineFallback) return createComponent(inlineFallback, {});
+						const loading = m.route.loading;
+						return loading
+							? createComponent(lazyModule(props.modules, loading), {})
+							: props.fallback;
+					},
+					get children() {
+						return createPageTree(
+							{
+								modules: props.modules,
+								location,
+								request,
+								hydration,
+							},
+							m,
+						);
+					},
+				});
+			},
+		});
+
+	// Last non-intercepted match — kept mounted behind an intercepted
+	// modal during client-side navigation (Next-style `(.)` behavior)
+	let lastFull: FileRouteMatch | undefined;
+
+	// Nav items — routes whose (loaded) module declares `meta.nav`,
+	// ordered by `page({ order })` (unordered last, then by path)
+	const navItems = computeNavItems(props.manifest, props.modules);
+
+	const content = (): JSX.Element =>
+		createComponent(NavContext.Provider, {
+			value: navItems,
+			get children() {
+				return createComponent(SlotsContext.Provider, {
+					value: slotMap,
+					get children() {
+						return createComponent(PrefetchContext.Provider, {
+							value: prefetch,
+							get children() {
+								const m = match();
+								if (!m) {
+									return renderNotFoundView(
+										{
+											modules: props.modules,
+											status,
+											notFound: props.notFound,
+										},
+										null,
+									);
+								}
+								const body = createComponent(ParamsContext.Provider, {
+									value: m.params,
+									get children() {
+										return renderMatch(m);
+									},
+								});
+								if (!m.route.intercepted) {
+									lastFull = m;
+									return body;
+								}
+								// Direct hit / SSR — render as a full page (no backdrop)
+								if (isServer || lastFull === undefined) return body;
+								// Soft navigation — previous page stays mounted underneath,
+								// intercepted route renders in a dialog wrapper
+								const base = lastFull;
+								return [
+									createComponent(ParamsContext.Provider, {
+										value: base.params,
+										get children() {
+											return renderMatch(base);
+										},
+									}),
+									createComponent(Dynamic, {
+										component: "div",
+										"data-sf-intercept": "",
+										role: "dialog",
+										"aria-modal": "true",
+										get children() {
+											return body;
+										},
+									}),
+								];
+							},
+						});
+					},
+				});
+			},
+		});
+
+	// Parallel slot map — each @slot route renders under its own
+	// SlotContext; layouts place them via <Outlet name="x">
+	const slotMap = (): Record<string, JSX.Element> => {
+		const out: Record<string, JSX.Element> = {};
+		for (const m of slotMatches()) {
+			if (!m.route.slot) continue;
+			out[m.route.slot] = createComponent(SlotContext.Provider, {
+				value: () => m.route.slot,
+				get children() {
+					return createComponent(ParamsContext.Provider, {
+						value: m.params,
+						get children() {
+							return renderMatch(m);
+						},
+					});
+				},
+			});
+		}
+		return out;
+	};
+
+	const prefetch = createRoutePrefetch(
+		props.manifest,
+		props.modules,
+		props.i18n,
+	);
+
+	const tree = (): JSX.Element =>
+		props.i18n
+			? createComponent(LocaleContext.Provider, {
+					get value() {
+						return stripped().locale;
+					},
+					get children() {
+						return content();
+					},
+				})
+			: content();
+
+	return createComponent(LocationContext.Provider, {
+		value: location,
+		get children() {
+			return tree();
+		},
+	});
+};
+
+/** @deprecated renamed to AppRoutes — FileRoutes is SolidStart's name */
+export const FileRoutes = AppRoutes;