vorma 0.0.0-pre.0 → 0.83.0

package/internal/framework/_typescript/client/src/links.ts

@@ -0,0 +1,218 @@
+import { getAnchorDetailsFromEvent, getHrefDetails } from "vorma/kit/url";
+import { navigationStateManager, vormaNavigate } from "./client.ts";
+import { saveScrollState } from "./scroll_state_manager.ts";
+
+type LinkOnClickCallback<E extends Event> = (event: E) => void | Promise<void>;
+
+type LinkOnClickCallbacks<E extends Event> = {
+	beforeBegin?: LinkOnClickCallback<E>;
+	beforeRender?: LinkOnClickCallback<E>;
+	afterRender?: LinkOnClickCallback<E>;
+};
+
+type GetPrefetchHandlersInput<E extends Event> = LinkOnClickCallbacks<E> & {
+	href: string;
+	delayMs?: number;
+	scrollToTop?: boolean;
+	replace?: boolean;
+	search?: string;
+	hash?: string;
+	state?: unknown;
+};
+
+export function __getPrefetchHandlers<E extends Event>(
+	input: GetPrefetchHandlersInput<E>,
+) {
+	const hrefDetails = getHrefDetails(input.href);
+	if (!hrefDetails.isHTTP) {
+		return;
+	}
+
+	// TypeScript type guard -- after this check, we know relativeURL exists
+	const { relativeURL } = hrefDetails;
+	if (!relativeURL || hrefDetails.isExternal) {
+		return;
+	}
+
+	let timer: number | undefined;
+	let prefetchStarted = false;
+	const delayMs = input.delayMs ?? 100;
+
+	async function prefetch(e: E): Promise<void> {
+		if (prefetchStarted) return;
+		prefetchStarted = true;
+
+		if (input.beforeBegin) {
+			await input.beforeBegin(e);
+		}
+
+		const fullUrl = new URL(relativeURL, window.location.href);
+		if (input.search !== undefined) fullUrl.search = input.search;
+		if (input.hash !== undefined) fullUrl.hash = input.hash;
+
+		// Use the navigation system
+		await navigationStateManager.navigate({
+			href: fullUrl.href,
+			navigationType: "prefetch",
+			state: input.state,
+		});
+	}
+
+	function start(e: E): void {
+		if (prefetchStarted) return;
+		timer = window.setTimeout(() => prefetch(e), delayMs);
+	}
+
+	function stop(): void {
+		if (timer) {
+			clearTimeout(timer);
+			timer = undefined;
+		}
+
+		// Abort prefetch if it exists and hasn't been upgraded
+		const targetUrl = new URL(relativeURL, window.location.href).href;
+		const nav = navigationStateManager.getNavigation(targetUrl);
+		if (nav && nav.type === "prefetch" && nav.intent === "none") {
+			nav.control.abortController?.abort();
+			navigationStateManager.removeNavigation(targetUrl);
+		}
+
+		prefetchStarted = false;
+	}
+
+	async function onClick(e: E): Promise<void> {
+		if (e.defaultPrevented) return;
+
+		const anchorDetails = getAnchorDetailsFromEvent(
+			e as unknown as MouseEvent,
+		);
+		if (!anchorDetails) return;
+
+		const { isEligibleForDefaultPrevention, isInternal } = anchorDetails;
+		if (!isEligibleForDefaultPrevention || !isInternal) return;
+
+		if (isJustAHashChange(anchorDetails)) {
+			saveScrollState();
+			return;
+		}
+
+		e.preventDefault();
+
+		if (timer) {
+			clearTimeout(timer);
+			timer = undefined;
+		}
+
+		// Execute callbacks
+		if (input.beforeBegin && !prefetchStarted) {
+			await input.beforeBegin(e);
+		}
+
+		if (input.beforeRender) {
+			await input.beforeRender(e);
+		}
+
+		// Use standard navigation -- it will upgrade the prefetch if it exists
+		await vormaNavigate(relativeURL, {
+			scrollToTop: input.scrollToTop,
+			replace: input.replace,
+			search: input.search,
+			hash: input.hash,
+			state: input.state,
+		});
+
+		if (input.afterRender) {
+			await input.afterRender(e);
+		}
+	}
+
+	return {
+		...hrefDetails,
+		start,
+		stop,
+		onClick,
+	};
+}
+
+export function __makeLinkOnClickFn<E extends Event>(
+	callbacks: LinkOnClickCallbacks<E> & {
+		scrollToTop?: boolean;
+		replace?: boolean;
+		state?: unknown;
+	},
+) {
+	return async (e: E) => {
+		if (e.defaultPrevented) return;
+
+		const anchorDetails = getAnchorDetailsFromEvent(
+			e as unknown as MouseEvent,
+		);
+		if (!anchorDetails) return;
+
+		const { anchor, isEligibleForDefaultPrevention, isInternal } =
+			anchorDetails;
+		if (!anchor) return;
+
+		if (isJustAHashChange(anchorDetails)) {
+			saveScrollState();
+			return;
+		}
+
+		if (isEligibleForDefaultPrevention && isInternal) {
+			e.preventDefault();
+
+			await callbacks.beforeBegin?.(e);
+
+			const control = navigationStateManager.beginNavigation({
+				href: anchor.href,
+				navigationType: "userNavigation",
+				scrollToTop: callbacks.scrollToTop,
+				replace: callbacks.replace,
+				state: callbacks.state,
+			});
+
+			if (!control.promise) return;
+
+			const res = await control.promise;
+
+			if (!res) {
+				// If not here, loading indicator can get stuck on
+				// following redirects
+				const targetUrl = new URL(anchor.href, window.location.href)
+					.href;
+				navigationStateManager.removeNavigation(targetUrl);
+				return;
+			}
+
+			await callbacks.beforeRender?.(e);
+
+			const targetUrl = new URL(anchor.href, window.location.href).href;
+			const entry = navigationStateManager.getNavigation(targetUrl);
+			if (entry) {
+				await navigationStateManager["processNavigationResult"](
+					res,
+					entry,
+				);
+			}
+
+			await callbacks.afterRender?.(e);
+		}
+	};
+}
+
+function isJustAHashChange(
+	anchorDetails: ReturnType<typeof getAnchorDetailsFromEvent>,
+): boolean {
+	if (!anchorDetails) return false;
+
+	const { pathname, search, hash } = new URL(
+		anchorDetails.anchor.href,
+		window.location.href,
+	);
+
+	return !!(
+		hash &&
+		pathname === window.location.pathname &&
+		search === window.location.search
+	);
+}

package/internal/framework/_typescript/client/src/redirects/redirects.ts

@@ -0,0 +1,203 @@
+import {
+	getHrefDetails,
+	getIsGETRequest,
+	type HrefDetails,
+} from "vorma/kit/url";
+import { navigationStateManager, type NavigateProps } from "../client.ts";
+import { VORMA_HARD_RELOAD_QUERY_PARAM } from "../hard_reload.ts";
+import { logError, logInfo } from "../utils/logging.ts";
+
+export type RedirectData = { href: string; hrefDetails: HrefDetails } & (
+	| {
+			status: "did";
+	  }
+	| {
+			status: "should";
+			shouldRedirectStrategy: "hard" | "soft";
+			latestBuildID: string;
+	  }
+);
+
+export function getBuildIDFromResponse(response: Response | undefined) {
+	return response?.headers.get("X-Vorma-Build-Id") || "";
+}
+
+export function parseFetchResponseForRedirectData(
+	reqInit: RequestInit,
+	res: Response,
+): RedirectData | null {
+	const latestBuildID = getBuildIDFromResponse(res);
+
+	const vormaReloadTarget = res.headers.get("X-Vorma-Reload");
+	if (vormaReloadTarget) {
+		const newURL = new URL(vormaReloadTarget, window.location.href);
+		const hrefDetails = getHrefDetails(newURL.href);
+		if (!hrefDetails.isHTTP) {
+			return null;
+		}
+
+		return {
+			hrefDetails,
+			status: "should",
+			href: vormaReloadTarget,
+			shouldRedirectStrategy: "hard",
+			latestBuildID,
+		};
+	}
+
+	if (res.redirected) {
+		const newURL = new URL(res.url, window.location.href);
+		const hrefDetails = getHrefDetails(newURL.href);
+		if (!hrefDetails.isHTTP) {
+			return null;
+		}
+
+		const isCurrent = newURL.href === window.location.href;
+		if (isCurrent) {
+			return { hrefDetails, status: "did", href: newURL.href };
+		}
+
+		const wasGETRequest = getIsGETRequest(reqInit);
+		if (!wasGETRequest) {
+			logInfo("Not a GET request. No way to handle.");
+			return null;
+		}
+
+		return {
+			hrefDetails,
+			status: "should",
+			href: newURL.href,
+			shouldRedirectStrategy: hrefDetails.isInternal ? "soft" : "hard",
+			latestBuildID,
+		};
+	}
+
+	const clientRedirectHeader = res.headers.get("X-Client-Redirect");
+
+	if (!clientRedirectHeader) {
+		return null;
+	}
+
+	const newURL = new URL(clientRedirectHeader, window.location.href);
+	const hrefDetails = getHrefDetails(newURL.href);
+	if (!hrefDetails.isHTTP) {
+		return null;
+	}
+
+	return {
+		hrefDetails,
+		status: "should",
+		href: hrefDetails.absoluteURL,
+		shouldRedirectStrategy: hrefDetails.isInternal ? "soft" : "hard",
+		latestBuildID,
+	};
+}
+
+export async function effectuateRedirectDataResult(
+	redirectData: RedirectData,
+	redirectCount: number,
+	originalProps?: NavigateProps,
+): Promise<RedirectData | null> {
+	if (redirectData.status !== "should") {
+		return null;
+	}
+
+	// Clean up any active redirect or revalidations when redirecting.
+	// Otherwise loading state will get stuck.
+	const navEntries = navigationStateManager.getNavigations().entries();
+	for (const [key, nav] of navEntries) {
+		if (nav.type === "redirect" || nav.type === "revalidation") {
+			nav.control.abortController?.abort();
+			navigationStateManager.removeNavigation(key);
+		}
+	}
+
+	if (redirectData.shouldRedirectStrategy === "hard") {
+		if (!redirectData.hrefDetails.isHTTP) return null;
+
+		if (redirectData.hrefDetails.isExternal) {
+			window.location.href = redirectData.href;
+		} else {
+			const url = new URL(redirectData.href, window.location.href);
+			url.searchParams.set(
+				VORMA_HARD_RELOAD_QUERY_PARAM,
+				redirectData.latestBuildID,
+			);
+			window.location.href = url.href;
+		}
+
+		return {
+			hrefDetails: redirectData.hrefDetails,
+			status: "did",
+			href: redirectData.href,
+		};
+	}
+
+	if (redirectData.shouldRedirectStrategy === "soft") {
+		await navigationStateManager.navigate({
+			href: redirectData.href,
+			navigationType: "redirect",
+			redirectCount: redirectCount + 1,
+			state: originalProps?.state,
+			replace: originalProps?.replace,
+			scrollToTop: originalProps?.scrollToTop,
+		});
+
+		return {
+			hrefDetails: redirectData.hrefDetails,
+			status: "did",
+			href: redirectData.href,
+		};
+	}
+
+	return null;
+}
+
+export async function handleRedirects(props: {
+	abortController: AbortController;
+	url: URL;
+	requestInit?: RequestInit;
+	isPrefetch?: boolean;
+	redirectCount?: number;
+}): Promise<{ redirectData: RedirectData | null; response?: Response }> {
+	const MAX_REDIRECTS = 10;
+	const redirectCount = props.redirectCount || 0;
+
+	if (redirectCount >= MAX_REDIRECTS) {
+		logError("Too many redirects");
+		return { redirectData: null, response: undefined };
+	}
+
+	// Prepare request
+	const bodyParentObj: RequestInit = {};
+	const isGET = getIsGETRequest(props.requestInit);
+
+	if (props.requestInit && (props.requestInit.body !== undefined || !isGET)) {
+		if (
+			props.requestInit.body instanceof FormData ||
+			typeof props.requestInit.body === "string"
+		) {
+			bodyParentObj.body = props.requestInit.body;
+		} else {
+			bodyParentObj.body = JSON.stringify(props.requestInit.body);
+		}
+	}
+
+	const headers = new Headers(props.requestInit?.headers);
+	// To temporarily test traditional server redirect behavior,
+	// you can set this to "0" instead of "1"
+	headers.set("X-Accepts-Client-Redirect", "1");
+	bodyParentObj.headers = headers;
+
+	const finalRequestInit = {
+		signal: props.abortController.signal,
+		...props.requestInit,
+		...bodyParentObj,
+	};
+
+	// Execute request
+	const res = await fetch(props.url, finalRequestInit);
+	let redirectData = parseFetchResponseForRedirectData(finalRequestInit, res);
+
+	return { redirectData, response: res };
+}

package/internal/framework/_typescript/client/src/rendering.ts

@@ -0,0 +1,135 @@
+import { AssetManager } from "./asset_manager.ts";
+import type { VormaNavigationType } from "./client.ts";
+import { deriveAndSetErrorState } from "./client_loaders.ts";
+import { ComponentLoader } from "./component_loader.ts";
+import { dispatchRouteChangeEvent } from "./events.ts";
+import { updateHeadEls } from "./head_elements/head_elements.ts";
+import { HistoryManager } from "./history/history.ts";
+import type { ScrollState } from "./scroll_state_manager.ts";
+import {
+	__vormaClientGlobal,
+	type GetRouteDataOutput,
+} from "./vorma_ctx/vorma_ctx.ts";
+
+type RerenderAppProps = {
+	json: GetRouteDataOutput;
+	navigationType: VormaNavigationType;
+	runHistoryOptions?: {
+		href: string;
+		scrollStateToRestore?: ScrollState;
+		replace?: boolean;
+		scrollToTop?: boolean;
+		state?: unknown;
+	};
+	onFinish: () => void;
+};
+
+export async function __reRenderApp(props: RerenderAppProps): Promise<void> {
+	const shouldUseViewTransitions =
+		__vormaClientGlobal.get("useViewTransitions") &&
+		!!document.startViewTransition &&
+		props.navigationType !== "prefetch" &&
+		props.navigationType !== "revalidation";
+
+	if (shouldUseViewTransitions) {
+		const transition = document.startViewTransition(async () => {
+			await __reRenderAppInner(props);
+		});
+		await transition.finished;
+	} else {
+		await __reRenderAppInner(props);
+	}
+}
+
+async function __reRenderAppInner(props: RerenderAppProps): Promise<void> {
+	const { json, navigationType, runHistoryOptions } = props;
+
+	// Update global state
+	const stateKeys = [
+		"outermostServerError",
+		"outermostServerErrorIdx",
+		"errorExportKeys",
+		"matchedPatterns",
+		"loadersData",
+		"importURLs",
+		"exportKeys",
+		"hasRootData",
+		"params",
+		"splatValues",
+	] as const;
+
+	for (const key of stateKeys) {
+		__vormaClientGlobal.set(key, json[key]);
+	}
+
+	deriveAndSetErrorState();
+
+	// Load components and error boundary
+	await ComponentLoader.handleComponents(json.importURLs);
+	await ComponentLoader.handleErrorBoundaryComponent(json.importURLs);
+
+	// Handle history and scroll
+	let scrollStateToDispatch: ScrollState | undefined;
+
+	if (runHistoryOptions) {
+		const { href, scrollStateToRestore, replace, scrollToTop } =
+			runHistoryOptions;
+		const hash = href.split("#")[1];
+		const history = HistoryManager.getInstance();
+
+		if (
+			navigationType === "userNavigation" ||
+			navigationType === "redirect"
+		) {
+			const target = new URL(href, window.location.href).href;
+			const current = new URL(window.location.href).href;
+
+			if (target !== current && !replace) {
+				history.push(href, runHistoryOptions.state);
+			} else {
+				history.replace(href, runHistoryOptions.state);
+			}
+
+			scrollStateToDispatch = hash
+				? { hash }
+				: scrollToTop !== false
+					? { x: 0, y: 0 }
+					: undefined;
+		}
+
+		if (navigationType === "browserHistory") {
+			scrollStateToDispatch =
+				scrollStateToRestore ?? (hash ? { hash } : undefined);
+		}
+	}
+
+	if (json.title !== undefined) {
+		// Changing the title instantly makes it feel faster
+		// The temp textarea trick is to decode any HTML entities in the title.
+		// This should come after pushing to history though, so that the title is
+		// correct in the history entry.
+		const tempTxt = document.createElement("textarea");
+		tempTxt.innerHTML = json.title?.dangerousInnerHTML || "";
+		if (document.title !== tempTxt.value) {
+			document.title = tempTxt.value;
+		}
+	}
+
+	// Apply CSS
+	if (json.cssBundles) {
+		AssetManager.applyCSS(json.cssBundles);
+	}
+
+	// Dispatch route change event -- this triggers the actual UI update
+	dispatchRouteChangeEvent({ __scrollState: scrollStateToDispatch });
+
+	// Only update head elements if provided (not undefined)
+	if (json.metaHeadEls !== undefined) {
+		updateHeadEls("meta", json.metaHeadEls ?? []);
+	}
+	if (json.restHeadEls !== undefined) {
+		updateHeadEls("rest", json.restHeadEls ?? []);
+	}
+
+	props.onFinish();
+}

package/internal/framework/_typescript/client/src/resolve_public_href.ts

@@ -0,0 +1,15 @@
+import { __vormaClientGlobal } from "./vorma_ctx/vorma_ctx.ts";
+
+export function resolvePublicHref(relativeHref: string): string {
+	let baseURL = __vormaClientGlobal.get("viteDevURL");
+	if (!baseURL) {
+		baseURL = __vormaClientGlobal.get("publicPathPrefix");
+	}
+	if (baseURL.endsWith("/")) {
+		baseURL = baseURL.slice(0, -1);
+	}
+	let final = relativeHref.startsWith("/")
+		? baseURL + relativeHref
+		: baseURL + "/" + relativeHref;
+	return final;
+}

package/internal/framework/_typescript/client/src/scroll_state_manager.ts

@@ -0,0 +1,100 @@
+import { HistoryManager } from "./history/history.ts";
+
+export type ScrollState = { x: number; y: number } | { hash: string };
+
+class ScrollStateManager {
+	private readonly STORAGE_KEY = "__vorma__scrollStateMap";
+	private readonly PAGE_REFRESH_KEY = "__vorma__pageRefreshScrollState";
+	private readonly MAX_ENTRIES = 50;
+
+	saveState(key: string, state: ScrollState): void {
+		const map = this.getMap();
+		map.set(key, state);
+
+		// Enforce size limit
+		if (map.size > this.MAX_ENTRIES) {
+			const firstKey = map.keys().next().value;
+			if (firstKey) map.delete(firstKey);
+		}
+
+		this.saveMap(map);
+	}
+
+	getState(key: string): ScrollState | undefined {
+		return this.getMap().get(key);
+	}
+
+	savePageRefreshState(): void {
+		const state = {
+			x: window.scrollX,
+			y: window.scrollY,
+			unix: Date.now(),
+			href: window.location.href,
+		};
+		sessionStorage.setItem(this.PAGE_REFRESH_KEY, JSON.stringify(state));
+	}
+
+	restorePageRefreshState(): void {
+		const stored = sessionStorage.getItem(this.PAGE_REFRESH_KEY);
+		if (!stored) return;
+
+		try {
+			const state = JSON.parse(stored);
+			if (
+				state.href === window.location.href &&
+				Date.now() - state.unix < 5000
+			) {
+				sessionStorage.removeItem(this.PAGE_REFRESH_KEY);
+				window.requestAnimationFrame(() => {
+					__applyScrollState({ x: state.x, y: state.y });
+				});
+			}
+		} catch {}
+	}
+
+	private getMap(): Map<string, ScrollState> {
+		const stored = sessionStorage.getItem(this.STORAGE_KEY);
+		if (!stored) return new Map();
+
+		try {
+			return new Map(JSON.parse(stored));
+		} catch {
+			return new Map();
+		}
+	}
+
+	private saveMap(map: Map<string, ScrollState>): void {
+		sessionStorage.setItem(
+			this.STORAGE_KEY,
+			JSON.stringify(Array.from(map.entries())),
+		);
+	}
+}
+
+export const scrollStateManager = new ScrollStateManager();
+
+export function __applyScrollState(state?: ScrollState): void {
+	if (!state) {
+		const id = window.location.hash.slice(1);
+		if (id) {
+			document.getElementById(id)?.scrollIntoView();
+		}
+		return;
+	}
+
+	if ("hash" in state) {
+		if (state.hash) {
+			document.getElementById(state.hash)?.scrollIntoView();
+		}
+	} else {
+		window.scrollTo(state.x, state.y);
+	}
+}
+
+export function saveScrollState(): void {
+	const lastKnownLocation = HistoryManager.getLastKnownLocation();
+	scrollStateManager.saveState(lastKnownLocation.key, {
+		x: window.scrollX,
+		y: window.scrollY,
+	});
+}

package/internal/framework/_typescript/client/src/static_route_defs/route_def_helpers.ts

@@ -0,0 +1,22 @@
+// Used by client route defs file (e.g., vorma.routes.ts)
+
+type ImportPromise = Promise<Record<string, any>>;
+type Key<T extends ImportPromise> = keyof Awaited<T>;
+
+/**
+ * Registers a route with the given route pattern,
+ * module import promise, component export key, and
+ * optional error boundary export key. Only for use
+ * in your centralized build-time route definitions
+ * file.
+ */
+export function route<IP extends ImportPromise>(
+	// oxlint-disable-next-line no-unused-vars
+	pattern: string,
+	// oxlint-disable-next-line no-unused-vars
+	importPromise: IP,
+	// oxlint-disable-next-line no-unused-vars
+	componentKey: Key<IP>,
+	// oxlint-disable-next-line no-unused-vars
+	errorBoundaryKey?: Key<IP>,
+): void {}