@lovrozagar/flare 0.1.0

package/src/history/index.ts

@@ -0,0 +1,210 @@
+export interface HistoryState {
+	historyIndex: number;
+	key: string;
+	params: Record<string, string | string[]>;
+	pathname: string;
+	scroll?: ScrollPosition;
+	search: string;
+	state?: unknown;
+}
+
+export interface ScrollPosition {
+	x: number;
+	y: number;
+}
+
+export interface HistoryNavigateEvent {
+	historyIndex: number;
+	key: string;
+	params: Record<string, string | string[]>;
+	pathname: string;
+	scroll?: ScrollPosition;
+	search: string;
+	state?: unknown;
+	type: "popstate";
+}
+
+export interface ScrollStore {
+	get(key: string): ScrollPosition | null;
+	save(key: string, position: ScrollPosition): void;
+}
+
+let keyCounter = 0;
+
+function generateKey(): string {
+	keyCounter = (keyCounter + 1) % Number.MAX_SAFE_INTEGER;
+	return `${Date.now().toString(36)}-${keyCounter.toString(36)}`;
+}
+
+export function createHistoryState(
+	pathname: string,
+	params: Record<string, string | string[]> = {},
+	search = "",
+	options?: { hash?: string; historyIndex?: number; state?: unknown },
+): HistoryState {
+	return {
+		historyIndex: options?.historyIndex ?? 0,
+		key: generateKey(),
+		params,
+		pathname,
+		search,
+		state: options?.state,
+	};
+}
+
+export function pushHistoryState(
+	pathname: string,
+	params: Record<string, string | string[]> = {},
+	search = "",
+	options?: { hash?: string; historyIndex?: number; state?: unknown },
+): HistoryState {
+	const state = createHistoryState(pathname, params, search, options);
+	const url = `${pathname}${search}${options?.hash ?? ""}`;
+	if (typeof history !== "undefined" && history) {
+		history.pushState(state, "", url);
+	}
+	return state;
+}
+
+export function replaceHistoryState(
+	pathname: string,
+	params: Record<string, string | string[]> = {},
+	search = "",
+	options?: { hash?: string; historyIndex?: number; state?: unknown },
+): HistoryState {
+	const state = createHistoryState(pathname, params, search, options);
+	const url = `${pathname}${search}${options?.hash ?? ""}`;
+	if (typeof history !== "undefined" && history) {
+		history.replaceState(state, "", url);
+	}
+	return state;
+}
+
+function isScrollPosition(raw: unknown): raw is ScrollPosition {
+	if (typeof raw !== "object" || raw === null) return false;
+	const obj = raw as Record<string, unknown>;
+	return typeof obj.x === "number" && typeof obj.y === "number" && Number.isFinite(obj.x) && Number.isFinite(obj.y);
+}
+
+export function parseHistoryState(raw: unknown): HistoryState | null {
+	if (raw === null || raw === undefined || typeof raw !== "object") return null;
+	if (Array.isArray(raw)) return null;
+
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.pathname !== "string") return null;
+	if (typeof obj.key !== "string") return null;
+
+	return {
+		historyIndex: typeof obj.historyIndex === "number" ? obj.historyIndex : 0,
+		key: obj.key,
+		params: (typeof obj.params === "object" && obj.params !== null ? obj.params : {}) as Record<
+			string,
+			string | string[]
+		>,
+		pathname: obj.pathname,
+		scroll: isScrollPosition(obj.scroll) ? obj.scroll : undefined,
+		search: typeof obj.search === "string" ? obj.search : "",
+		state: obj.state,
+	};
+}
+
+export function createHistoryListener(onNavigate: (event: HistoryNavigateEvent) => void): () => void {
+	if (typeof addEventListener !== "function") {
+		return () => {};
+	}
+
+	const handler = (event: { state?: unknown }) => {
+		const parsed = parseHistoryState(event.state);
+		if (!parsed) return;
+		onNavigate({
+			historyIndex: parsed.historyIndex,
+			key: parsed.key,
+			params: parsed.params,
+			pathname: parsed.pathname,
+			scroll: parsed.scroll,
+			search: parsed.search,
+			state: parsed.state,
+			type: "popstate",
+		});
+	};
+
+	addEventListener("popstate", handler as EventListener);
+	return () => removeEventListener("popstate", handler as EventListener);
+}
+
+const DEFAULT_SCROLL_TTL = 30 * 60 * 1000;
+
+export function createScrollStore(maxSize = 200, ttl = DEFAULT_SCROLL_TTL): ScrollStore {
+	const store = new Map<string, ScrollPosition>();
+	const timestamps = new Map<string, number>();
+
+	function evictStale(): void {
+		const now = Date.now();
+		for (const [key, ts] of timestamps) {
+			if (now - ts > ttl) {
+				store.delete(key);
+				timestamps.delete(key);
+			}
+		}
+	}
+
+	return {
+		get(key: string): ScrollPosition | null {
+			return store.get(key) ?? null;
+		},
+
+		save(key: string, position: ScrollPosition): void {
+			evictStale();
+			if (store.has(key)) {
+				store.delete(key);
+				timestamps.delete(key);
+			}
+			store.set(key, position);
+			timestamps.set(key, Date.now());
+			if (store.size > maxSize) {
+				const firstKey = store.keys().next().value;
+				if (firstKey !== undefined) {
+					store.delete(firstKey);
+					timestamps.delete(firstKey);
+				}
+			}
+		},
+	};
+}
+
+export function getCurrentScroll(): ScrollPosition {
+	return {
+		x: typeof scrollX === "number" ? scrollX : 0,
+		y: typeof scrollY === "number" ? scrollY : 0,
+	};
+}
+
+export function restoreScroll(position: ScrollPosition, behavior?: ScrollBehavior): void {
+	if (typeof scrollTo === "function") {
+		scrollTo({ behavior: behavior ?? "auto", left: position.x, top: position.y });
+	}
+}
+
+export function scrollToTop(): void {
+	if (typeof scrollTo === "function") {
+		scrollTo(0, 0);
+	}
+}
+
+let currentHistoryIndex = 0;
+
+export function getHistoryIndex(): number {
+	return currentHistoryIndex;
+}
+
+export function setHistoryIndex(index: number): void {
+	currentHistoryIndex = index;
+}
+
+export function incrementHistoryIndex(): void {
+	currentHistoryIndex++;
+}
+
+export function initHistoryIndex(index: number): void {
+	currentHistoryIndex = index;
+}

package/src/hooks.ts

@@ -0,0 +1,61 @@
+import type { Accessor } from "solid-js";
+import type { ExtractT, Translator } from "./i18n/index.ts";
+import { useRouter } from "./outlet/index.tsx";
+import type { BlockerState, ClientMatch, FlareRouter, ProviderLocation } from "./outlet/types.ts";
+import type {
+	RouteLoaderData,
+	RoutePathParams,
+	RoutePreloaderContext,
+	RouteSearchParams,
+	RouteVirtualPaths,
+} from "./route-builder/register.ts";
+
+export function useBlocker(when: () => boolean): BlockerState {
+	return useRouter().useBlocker(when);
+}
+
+export function useLoaderData<TPath extends RouteVirtualPaths>(options: {
+	from: TPath;
+}): Accessor<RouteLoaderData<TPath>> {
+	return useRouter().useLoaderData(options);
+}
+
+export function useLoaderT<TPath extends RouteVirtualPaths>(options: {
+	from: TPath;
+}): Translator<ExtractT<RouteLoaderData<TPath>>> {
+	return useRouter().useLoaderT(options);
+}
+
+export function useLocation(): Accessor<ProviderLocation> {
+	return useRouter().location;
+}
+
+export function useMatch(options: { from: RouteVirtualPaths }): Accessor<ClientMatch | undefined> {
+	return useRouter().useMatch(options);
+}
+
+export function useNavigate(): FlareRouter["navigate"] {
+	return useRouter().navigate;
+}
+
+export function useParams<TPath extends RouteVirtualPaths>(options: { from: TPath }): Accessor<RoutePathParams<TPath>> {
+	return useRouter().useParams(options);
+}
+
+export function usePreloaderContext<TPath extends RouteVirtualPaths>(options: {
+	from: TPath;
+}): Accessor<RoutePreloaderContext<TPath>> {
+	return useRouter().usePreloaderContext(options);
+}
+
+export function usePreloaderT<TPath extends RouteVirtualPaths>(options: {
+	from: TPath;
+}): Translator<ExtractT<RoutePreloaderContext<TPath>>> {
+	return useRouter().usePreloaderT(options);
+}
+
+export function useSearch<TPath extends RouteVirtualPaths>(options: {
+	from: TPath;
+}): Accessor<RouteSearchParams<TPath>> {
+	return useRouter().useSearch(options);
+}

package/src/hydrate/index.tsx

@@ -0,0 +1,381 @@
+/* @refresh skip */
+import swConfig from "virtual:flare-sw-config";
+
+declare const __FLARE_IS_DEV__: boolean | undefined;
+const isDevDefault = typeof __FLARE_IS_DEV__ === "boolean" ? __FLARE_IS_DEV__ : false;
+import type { JSX } from "solid-js";
+import { createComponent, render, hydrate as solidHydrate } from "solid-js/web";
+import { createChannel } from "../broadcast/channel.ts";
+import { BroadcastProvider } from "../broadcast/provider.tsx";
+import type { MatchCache } from "../caches/index.ts";
+import { createMatchCache, createPrefetchCache } from "../caches/index.ts";
+import { DirectionProvider } from "../direction.ts";
+import { NotFoundError, UnauthenticatedError, UnauthorizedError } from "../errors/index.ts";
+import { replaceHistoryState } from "../history/index.ts";
+import {
+	buildInitialMatches,
+	extractRootBoundaries,
+	hydrateHeadState,
+	loadRouteModules,
+	populateMatchCache,
+} from "../hydration/index.ts";
+import { onceIdle } from "../internal/once-idle.ts";
+import { setupNavigation } from "../navigation/index.ts";
+import type { LoadedRouteModule } from "../navigation/types.ts";
+import { FlareProvider, Outlet, useRouter } from "../outlet/index.tsx";
+import type { FlareProviderContext, ProviderLocation, RenderProps } from "../outlet/types.ts";
+import type { LocationRewrite } from "../rewrite/index.ts";
+import { composeRewrites, executeRewriteInput, rewriteBasePath } from "../rewrite/index.ts";
+import type { createRouter, MarkedRouterConfig } from "../router-config/index.ts";
+import {
+	hydrateFlareState,
+	installDeferredResolver,
+	installQueryCacheResolver,
+	parseFlareState,
+} from "../state-parser/index.ts";
+import { enableDomInjection, finishHydration } from "../styles/index.ts";
+import { ThemeProvider } from "../theme.ts";
+import { parseSearchParams } from "../url/index.ts";
+
+function reconstructError(name: string): Error {
+	if (name === "NotFoundError") return new NotFoundError();
+	if (name === "UnauthenticatedError") return new UnauthenticatedError();
+	if (name === "UnauthorizedError") return new UnauthorizedError();
+	const err = new Error();
+	err.name = name;
+	return err;
+}
+
+export interface HydrateOptions {
+	/** @internal override for testing — auto-resolved from virtual module */
+	devOverlay?: boolean;
+	onContextReady?: (ctx: FlareProviderContext) => void;
+	onHydrated?: () => void;
+	onIdle?: () => void;
+	onInteraction?: () => void;
+}
+
+/**
+ * Matches SSR's Hydration component depth.
+ * Hydration is a single-child-passthrough, Dummy matches its depth
+ * so hydration keys align between SSR and client.
+ */
+function Dummy(props: { children: JSX.Element }): JSX.Element {
+	return props.children;
+}
+
+function RootRenderer(props: {
+	data: unknown;
+	location: ProviderLocation;
+	preloaderContext: Record<string, unknown> | undefined;
+	renderFn: (p: RenderProps) => JSX.Element;
+}): JSX.Element {
+	const router = useRouter();
+	return props.renderFn({
+		children: <Outlet />,
+		loaderData: props.data,
+		location: props.location,
+		preloaderContext: props.preloaderContext,
+		router,
+	});
+}
+
+function buildComposedRewrite(r: MarkedRouterConfig): LocationRewrite | undefined {
+	const rewrites: LocationRewrite[] = [];
+	if (r.basePath) {
+		rewrites.push(rewriteBasePath({ basePath: r.basePath, caseSensitive: r.caseSensitive }));
+	}
+	if (r.rewrite) {
+		rewrites.push(r.rewrite);
+	}
+	if (rewrites.length === 0) return undefined;
+	if (rewrites.length === 1) return rewrites[0];
+	return composeRewrites(rewrites);
+}
+
+declare const self: { flare?: unknown };
+
+export type RouterArg = MarkedRouterConfig | (() => MarkedRouterConfig | Promise<MarkedRouterConfig>);
+
+export async function hydrate(router: RouterArg, options?: HydrateOptions): Promise<void> {
+	enableDomInjection();
+	const r = typeof router === "function" ? await router() : router;
+	const raw = parseFlareState(self.flare);
+	if (!raw) return;
+
+	const state = hydrateFlareState(raw);
+	installDeferredResolver(state.resolvers);
+
+	/* Forward SSR-captured server logs to browser console */
+	if (raw.g) {
+		const logPrefix = "%c[server]";
+		const logStyle = "color:#60a5fa;font-weight:bold";
+		const srcStyle = "color:#9ca3af";
+		for (const entry of raw.g) {
+			const args = Array.isArray(entry.a) ? entry.a : [];
+			const prefix = entry.s
+				? [logPrefix, logStyle, `%c ${entry.s}`, srcStyle, ...args]
+				: [logPrefix, logStyle, ...args];
+			switch (entry.l) {
+				case "warn":
+					console.warn(...prefix);
+					break;
+				case "error":
+					console.error(...prefix);
+					break;
+				default:
+					console.log(...prefix);
+					break;
+			}
+		}
+	}
+
+	const matchCache: MatchCache = createMatchCache(r.routeCacheMaxEntries);
+	const prefetchCache = createPrefetchCache();
+
+	populateMatchCache(matchCache, state.matches, raw.ph);
+
+	if (raw.ph) {
+		hydrateHeadState({
+			ph: raw.ph.map((h) => ({
+				head: { ...h.head },
+				matchId: h.matchId,
+			})),
+		});
+	}
+
+	/* Hydrate TanStack Query cache from FlareState.q (spec 33) */
+	let QCP: ((props: { children: JSX.Element; client: unknown }) => JSX.Element) | undefined;
+	let queryClientInstance: unknown;
+	if (r.queryClientGetter) {
+		queryClientInstance = r.queryClientGetter();
+		const qEntries = raw.q;
+		if (qEntries && Array.isArray(qEntries) && qEntries.length > 0) {
+			const { hydrateQueryCache } = await import("../query-client");
+			hydrateQueryCache(queryClientInstance as Parameters<typeof hydrateQueryCache>[0], qEntries);
+		}
+		const { QueryClientProvider } = await import("../query-client");
+		QCP = QueryClientProvider as typeof QCP;
+		installQueryCacheResolver(queryClientInstance);
+	}
+
+	/* Build composed rewrite: basePath (if any) + user rewrite */
+	const composedRewrite = buildComposedRewrite(r);
+
+	const hydrateUrl = new URL(state.pathname, "http://localhost");
+	const hydratePathname = composedRewrite ? executeRewriteInput(composedRewrite, hydrateUrl).pathname : state.pathname;
+	let modules = await loadRouteModules(hydratePathname, r.routeTree, r.layouts, r.caseSensitive, r.locale);
+	/* Same fuzzy fallback as the server: unmatched URLs still hydrate the
+	   root index so NotFoundError from FlareState maps onto `_root_/`
+	   instead of a greedy `[locale]` param (which would render with no
+	   loaderData and throw on `.t`). */
+	if (!modules && (r.notFoundMode ?? "fuzzy") !== "root") {
+		modules = await loadRouteModules("/", r.routeTree, r.layouts, r.caseSensitive, r.locale);
+	}
+
+	if (modules) {
+		const search = parseSearchParams(new URL(window.location.href).searchParams);
+		const rootLayout = modules.layouts.find((m) => m._type === "root-layout");
+		const nonRootLayouts = modules.layouts.filter((m) => m._type !== "root-layout");
+		const allModules: LoadedRouteModule[] = [...nonRootLayouts, modules.page];
+
+		/* Build error map from per-match error names (survives serialization) */
+		const errorMap = new Map<string, Error>();
+		for (const hm of state.matches) {
+			if (hm.errorName) {
+				errorMap.set(hm.virtualPath, reconstructError(hm.errorName));
+			}
+		}
+
+		const rootBoundaries = extractRootBoundaries(rootLayout);
+		const initialMatches = buildInitialMatches(allModules, matchCache, modules.params, search, errorMap);
+
+		let resolveCtx: (ctx: FlareProviderContext) => void = () => {};
+		const ctxReady = new Promise<FlareProviderContext>((resolve) => {
+			resolveCtx = resolve;
+		});
+
+		/* Root layout data from FlareState (populated by SSR) */
+		const rootMatchState = rootLayout ? state.matches.find((m) => m.virtualPath === rootLayout.virtualPath) : undefined;
+
+		/*
+		 * Full-document hydration: providers wrap root layout so components
+		 * inside root layout (e.g. NavigationProgress) have RouterContext.
+		 *
+		 * SSR:    Hydration > QCP? > Theme > Direction > Broadcast > FlareProvider > rootRenderFn({children: Outlet})
+		 * Client: Dummy     > QCP? > Theme > Direction > Broadcast > FlareProvider > rootRenderFn({children: Outlet})
+		 */
+		const channel = createChannel();
+		const renderInner = () => (
+			<ThemeProvider config={r.theme}>
+				<DirectionProvider config={r.direction}>
+					<BroadcastProvider value={channel}>
+						<FlareProvider
+							boundaries={rootBoundaries}
+							caseSensitive={r.caseSensitive}
+							layouts={r.layouts}
+							localeConfig={r.locale}
+							matchCache={matchCache}
+							matches={initialMatches}
+							onContextReady={(ctx) => {
+								resolveCtx(ctx);
+							}}
+							params={state.params}
+							prefetchCache={prefetchCache}
+							resolvers={state.resolvers}
+							routerCacheDefaults={r.cache?.client || undefined}
+							routeTree={r.routeTree}
+							search={search}
+						>
+							{rootLayout?.render ? (
+								<RootRenderer
+									data={rootMatchState?.loaderData}
+									location={{
+										hash: window.location.hash,
+										params: state.params,
+										pathname: state.pathname,
+										search,
+										url: new URL(window.location.href),
+										variablePath: "",
+										virtualPath: rootLayout.virtualPath,
+									}}
+									preloaderContext={rootMatchState?.preloaderContext}
+									renderFn={rootLayout.render}
+								/>
+							) : (
+								<Outlet />
+							)}
+						</FlareProvider>
+					</BroadcastProvider>
+				</DirectionProvider>
+			</ThemeProvider>
+		);
+
+		solidHydrate(
+			() => (
+				<Dummy>
+					{QCP && queryClientInstance
+						? createComponent(QCP, {
+								get children() {
+									return renderInner();
+								},
+								client: queryClientInstance,
+							})
+						: renderInner()}
+				</Dummy>
+			),
+			document,
+		);
+		finishHydration();
+
+		replaceHistoryState(window.location.pathname, state.params, window.location.search, {
+			hash: window.location.hash,
+			historyIndex: 0,
+		});
+
+		if (options?.onHydrated) {
+			options.onHydrated();
+		}
+
+		if (options?.onIdle) {
+			const cb = options.onIdle;
+			if (typeof requestIdleCallback === "function") {
+				requestIdleCallback(() => cb());
+			} else {
+				setTimeout(cb, 0);
+			}
+		}
+
+		if (options?.onInteraction) {
+			const cb = options.onInteraction;
+			const events = ["mousemove", "touchstart", "scroll", "keydown"] as const;
+			const handler = () => {
+				for (const e of events) removeEventListener(e, handler, { capture: true });
+				cb();
+			};
+			for (const e of events) {
+				addEventListener(e, handler, { capture: true, once: true, passive: true });
+			}
+		}
+
+		const providerCtx = await ctxReady;
+
+		if (options?.onContextReady) {
+			options.onContextReady(providerCtx);
+		}
+
+		const initialRouteIds = allModules.map((mod) => mod.virtualPath);
+		if (rootLayout) initialRouteIds.push(rootLayout.virtualPath);
+
+		setupNavigation(
+			providerCtx,
+			async (pathname, tree, lyts) => {
+				const result = await loadRouteModules(
+					pathname,
+					tree as ReturnType<typeof createRouter>["routeTree"],
+					lyts,
+					r.caseSensitive,
+					r.locale,
+				);
+				if (!result)
+					throw new Error(
+						`No route modules found for "${pathname}". Verify the route file exists and the build completed successfully.`,
+					);
+				return result;
+			},
+			{
+				caseSensitive: r.caseSensitive,
+				direction: r.direction,
+				initialRouteIds,
+				keepalive: (raw.c.router as Record<string, unknown> | undefined)?.keepalive as false | number | undefined,
+				locale: r.locale,
+				notFoundMode: r.notFoundMode ?? "fuzzy",
+				queryClient: queryClientInstance,
+				rewrite: composedRewrite,
+				scrollRestoration: r.scrollRestoration,
+				scrollRestorationBehavior: r.scrollRestorationBehavior,
+				scrollRestorationMaxEntries: r.scrollRestorationMaxEntries,
+				viewTransitions: r.viewTransitions ?? false,
+			},
+		);
+
+		const showDevOverlay = options?.devOverlay ?? isDevDefault;
+		if (showDevOverlay) {
+			const { DevErrorOverlay } = await import("../components/dev-error-overlay");
+			let overlayRoot = document.getElementById("flare-dev-overlay-root");
+			if (!overlayRoot) {
+				overlayRoot = document.createElement("div");
+				overlayRoot.id = "flare-dev-overlay-root";
+				document.body.appendChild(overlayRoot);
+			}
+			overlayRoot.textContent = "";
+			render(() => <DevErrorOverlay />, overlayRoot);
+		}
+
+		document.documentElement.setAttribute("data-hydrated", "");
+	}
+
+	/* Service worker registration / unregistration */
+	if ("serviceWorker" in navigator) {
+		if ((swConfig as { enabled: boolean }).enabled) {
+			const cfg = swConfig as { enabled: boolean; path: string; scope: string };
+			onceIdle(() => {
+				navigator.serviceWorker
+					.register(cfg.path, {
+						scope: cfg.scope,
+						updateViaCache: "none" as ServiceWorkerUpdateViaCache,
+					})
+					.catch(() => {});
+			});
+		} else {
+			onceIdle(() => {
+				navigator.serviceWorker
+					.getRegistrations()
+					.then((regs) => {
+						for (const reg of regs) reg.unregister();
+					})
+					.catch(() => {});
+			});
+		}
+	}
+}