vorma 0.0.0-pre.0 → 0.83.0

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

@@ -0,0 +1,193 @@
+import { panic } from "../utils/errors.ts";
+import type { HeadEl } from "../vorma_ctx/vorma_ctx.ts";
+
+export function getStartAndEndComments(type: "meta" | "rest"): {
+	startComment: Comment | null;
+	endComment: Comment | null;
+} {
+	const startMarker = `data-vorma="${type}-start"`;
+	const endMarker = `data-vorma="${type}-end"`;
+	const start = findComment(startMarker);
+	const end = findComment(endMarker);
+	return { startComment: start, endComment: end };
+}
+
+function findComment(matchingText: string): Comment | null {
+	const walker = document.createTreeWalker(
+		document.head,
+		NodeFilter.SHOW_COMMENT,
+		{
+			acceptNode(node: Comment) {
+				return node.nodeValue?.trim() === matchingText.trim()
+					? NodeFilter.FILTER_ACCEPT
+					: NodeFilter.FILTER_REJECT;
+			},
+		},
+	);
+	return walker.nextNode() as Comment | null;
+}
+
+export function updateHeadEls(type: "meta" | "rest", blocks: Array<HeadEl>) {
+	const { startComment, endComment } = getStartAndEndComments(type);
+	if (!startComment || !endComment || !endComment.parentNode) {
+		return;
+	}
+	const parent = endComment.parentNode;
+
+	// Collect all current nodes between start and end comments
+	const currentNodes: Array<Node> = [];
+	let nodePtr = startComment.nextSibling;
+	while (nodePtr != null && nodePtr !== endComment) {
+		currentNodes.push(nodePtr);
+		nodePtr = nodePtr.nextSibling;
+	}
+	const currentElements = currentNodes.filter(
+		(node): node is Element => node.nodeType === Node.ELEMENT_NODE,
+	);
+
+	// Create new elements from blocks
+	const newElements: Array<Element> = [];
+	const newElementFingerprints = new Map<string, Element>();
+	for (const block of blocks) {
+		if (!block.tag) {
+			continue;
+		}
+		const newEl = document.createElement(block.tag);
+		if (block.attributesKnownSafe) {
+			for (const key of Object.keys(block.attributesKnownSafe)) {
+				const value = block.attributesKnownSafe[key];
+				if (value === null || value === undefined) {
+					panic(
+						`Attribute value for '${key}' in tag '${block.tag}' cannot be null or undefined.`,
+					);
+				}
+				newEl.setAttribute(key, value);
+			}
+		}
+		if (block.booleanAttributes) {
+			for (const key of block.booleanAttributes) {
+				newEl.setAttribute(key, "");
+			}
+		}
+		if (block.dangerousInnerHTML) {
+			newEl.innerHTML = block.dangerousInnerHTML;
+		}
+
+		const fingerprint = createElementFingerprint(newEl);
+		if (newElementFingerprints.has(fingerprint)) {
+			const elementToRemove = newElementFingerprints.get(fingerprint);
+			if (elementToRemove) {
+				const indexToRemove = newElements.indexOf(elementToRemove);
+				if (indexToRemove > -1) {
+					newElements.splice(indexToRemove, 1);
+				}
+			}
+		}
+		newElements.push(newEl);
+		newElementFingerprints.set(fingerprint, newEl);
+	}
+
+	// Build a map of current elements by fingerprint
+	const currentElementsMap = new Map<string, Array<Element>>();
+	for (const el of currentElements) {
+		const fingerprint = createElementFingerprint(el);
+		if (!currentElementsMap.has(fingerprint)) {
+			currentElementsMap.set(fingerprint, []);
+		}
+		currentElementsMap.get(fingerprint)?.push(el);
+	}
+
+	// Match new elements with existing ones when possible
+	const finalElements: Array<Element> = [];
+	const usedCurrentElements = new Set<Element>();
+
+	for (const newEl of newElements) {
+		const fingerprint = createElementFingerprint(newEl);
+		const matchingCurrentElementsList =
+			currentElementsMap.get(fingerprint) || [];
+
+		// Find the first matching element that hasn't been used yet
+		const matchingElement = matchingCurrentElementsList.find(
+			(el) => !usedCurrentElements.has(el),
+		);
+
+		if (matchingElement) {
+			usedCurrentElements.add(matchingElement);
+			finalElements.push(matchingElement);
+		} else {
+			finalElements.push(newEl);
+		}
+	}
+
+	// Create a map to track which elements are in the correct position
+	// and which need to be moved or added
+	const desiredPositions = new Map<Element, number>();
+	finalElements.forEach((el, index) => {
+		desiredPositions.set(el, index);
+	});
+
+	// Track elements still in the DOM
+	const remainingCurrentElements = new Set(currentElements);
+
+	// First pass: remove elements that are no longer needed
+	for (const currentElement of currentElements) {
+		if (!usedCurrentElements.has(currentElement)) {
+			parent.removeChild(currentElement);
+			remainingCurrentElements.delete(currentElement);
+		}
+	}
+
+	// Second pass: position elements in the correct order with minimal DOM operations
+	let lastProcessedElement: Element | null = null;
+
+	for (let i = 0; i < finalElements.length; i++) {
+		const element = finalElements[i];
+		if (!element) {
+			continue;
+		}
+		const isExistingElement = usedCurrentElements.has(element);
+
+		if (isExistingElement) {
+			// Check if this element is already in the correct position
+			const nextElementInDOM = (
+				lastProcessedElement
+					? lastProcessedElement.nextElementSibling
+					: startComment.nextElementSibling
+			) as Element | null;
+
+			if (nextElementInDOM !== element) {
+				// Element exists but is in the wrong position, move it
+				parent.insertBefore(element, nextElementInDOM || endComment);
+			}
+
+			// Mark as processed
+			remainingCurrentElements.delete(element);
+			lastProcessedElement = element;
+		} else {
+			// This is a new element, insert it
+			const insertBefore = lastProcessedElement
+				? lastProcessedElement.nextSibling
+				: startComment.nextSibling;
+
+			parent.insertBefore(element, insertBefore || endComment);
+			lastProcessedElement = element;
+		}
+	}
+}
+
+function createElementFingerprint(element: Element): string {
+	const attributes: Array<string> = [];
+	for (let i = 0; i < element.attributes.length; i++) {
+		const attr = element.attributes[i];
+		if (!attr) {
+			continue;
+		}
+		const value =
+			element.hasAttribute(attr.name) && attr.value === ""
+				? ""
+				: attr.value;
+		attributes.push(`${attr.name}="${value}"`);
+	}
+	attributes.sort();
+	return `${element.tagName.toUpperCase()}|${attributes.join(",")}|${(element.innerHTML || "").trim()}`;
+}

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

@@ -0,0 +1,118 @@
+import { createBrowserHistory, type Update as NPMHistoryUpdate } from "history";
+import { navigationStateManager } from "../client.ts";
+import { dispatchLocationEvent } from "../events.ts";
+import {
+	__applyScrollState,
+	saveScrollState,
+	scrollStateManager,
+} from "../scroll_state_manager.ts";
+import { logError } from "../utils/logging.ts";
+import type { historyInstance, historyListener } from "./npm_history_types.ts";
+
+export class HistoryManager {
+	private static instance: historyInstance;
+	private static lastKnownLocation: typeof HistoryManager.instance.location;
+
+	static getInstance(): historyInstance {
+		if (!this.instance) {
+			this.instance =
+				createBrowserHistory() as unknown as historyInstance;
+			this.lastKnownLocation = this.instance.location;
+		}
+		return this.instance;
+	}
+
+	static getLastKnownLocation() {
+		return this.lastKnownLocation;
+	}
+
+	static updateLastKnownLocation(
+		location: typeof HistoryManager.instance.location,
+	) {
+		this.lastKnownLocation = location;
+	}
+
+	static init(): void {
+		const instance = this.getInstance();
+		instance.listen(customHistoryListener as unknown as historyListener);
+		this.setManualScrollRestoration();
+	}
+
+	private static setManualScrollRestoration(): void {
+		if (
+			history.scrollRestoration &&
+			history.scrollRestoration !== "manual"
+		) {
+			history.scrollRestoration = "manual";
+		}
+	}
+}
+
+export function initCustomHistory(): void {
+	HistoryManager.init();
+}
+
+export async function customHistoryListener({
+	action,
+	location,
+}: NPMHistoryUpdate): Promise<void> {
+	const lastKnownLocation = HistoryManager.getLastKnownLocation();
+
+	if (location.key !== lastKnownLocation.key) {
+		dispatchLocationEvent();
+	}
+
+	const popWithinSameDoc =
+		action === "POP" &&
+		location.pathname === lastKnownLocation.pathname &&
+		location.search === lastKnownLocation.search;
+
+	const removingHash =
+		popWithinSameDoc && lastKnownLocation.hash && !location.hash;
+	const addingHash =
+		popWithinSameDoc && !lastKnownLocation.hash && location.hash;
+	const updatingHash = popWithinSameDoc && location.hash;
+
+	if (!popWithinSameDoc) {
+		saveScrollState();
+	}
+
+	let navigationSucceeded = true;
+
+	if (action === "POP") {
+		const newHash = location.hash.slice(1);
+
+		if (addingHash || updatingHash) {
+			__applyScrollState({ hash: newHash });
+		}
+
+		if (removingHash) {
+			const stored = scrollStateManager.getState(location.key);
+			__applyScrollState(stored ?? { x: 0, y: 0 });
+		}
+
+		if (!popWithinSameDoc) {
+			const result = await navigationStateManager.navigate({
+				href: window.location.href,
+				navigationType: "browserHistory",
+				scrollStateToRestore: scrollStateManager.getState(location.key),
+			});
+
+			if (!result.didNavigate) {
+				navigationSucceeded = false;
+				logError(
+					"Browser POP navigation failed, attempting hard reload of the destination.",
+				);
+
+				// This just reloads the current (failed) URL.
+				// It preserves the history stack and ensures no UI/URL mismatch,
+				// which could otherwise happen if a browser forward/back navigation fails
+				window.location.reload();
+			}
+		}
+	}
+
+	if (navigationSucceeded) {
+		HistoryManager.updateLastKnownLocation(location);
+	}
+}

package/internal/framework/_typescript/client/src/history/npm_history_types.ts

@@ -0,0 +1,83 @@
+/******************************************************************************
+
+This file is a condensed, comment-stripped, and prefixed-type version of
+npm:history's index.d.ts file as of v5.3.0. npm:history is licensed under the
+MIT license. It is used under the hood by vorma/client.
+
+The npm:history repository is located at: https://github.com/remix-run/history
+
+It's only purpose is to re-export a minimal version of the types needed by
+vorma/client's "getHistoryInstance" function, which simply returns an
+instance of npm:history's BrowserHistory.
+
+Original license:
+
+MIT License
+
+Copyright (c) React Training 2016-2020
+Copyright (c) Remix Software 2020-2021
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+******************************************************************************/
+
+declare enum historyAction {
+	Pop = "POP",
+	Push = "PUSH",
+	Replace = "REPLACE",
+}
+declare type historyPathname = string;
+declare type historySearch = string;
+declare type historyHash = string;
+declare type historyKey = string;
+interface historyPath {
+	pathname: historyPathname;
+	search: historySearch;
+	hash: historyHash;
+}
+export interface historyLocation extends historyPath {
+	state: unknown;
+	key: historyKey;
+}
+interface historyUpdate {
+	action: historyAction;
+	location: historyLocation;
+}
+export interface historyListener {
+	(update: historyUpdate): void;
+}
+interface historyTransition extends historyUpdate {
+	retry(): void;
+}
+interface historyBlocker {
+	(tx: historyTransition): void;
+}
+declare type historyTo = string | Partial<historyPath>;
+export interface historyInstance {
+	readonly action: historyAction;
+	readonly location: historyLocation;
+	createHref(to: historyTo): string;
+	push(to: historyTo, state?: any): void;
+	replace(to: historyTo, state?: any): void;
+	go(delta: number): void;
+	back(): void;
+	forward(): void;
+	listen(listener: historyListener): () => void;
+	block(blocker: historyBlocker): () => void;
+}

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

@@ -0,0 +1,71 @@
+import { debounce } from "vorma/kit/debounce";
+import { revalidate } from "../client.ts";
+import { setupClientLoaders } from "../client_loaders.ts";
+import { dispatchRouteChangeEvent } from "../events.ts";
+import { logInfo } from "../utils/logging.ts";
+import { __vormaClientGlobal } from "../vorma_ctx/vorma_ctx.ts";
+
+let devTimeSetupClientLoadersDebounced: () => Promise<void> = () =>
+	Promise.resolve();
+
+let hmrRevalidateSet: Set<string>;
+
+export let __runClientLoadersAfterHMRUpdate: (
+	importMeta: ImportMeta,
+	pattern: string,
+) => void = () => {};
+
+export function initHMR() {
+	if (import.meta.env.DEV) {
+		(window as any).__waveRevalidate = revalidate;
+
+		devTimeSetupClientLoadersDebounced = debounce(async () => {
+			await setupClientLoaders();
+			dispatchRouteChangeEvent({});
+		}, 10);
+
+		__runClientLoadersAfterHMRUpdate = (importMeta, pattern) => {
+			if (hmrRevalidateSet === undefined) {
+				hmrRevalidateSet = new Set();
+			}
+
+			if (import.meta.env.DEV && import.meta.hot) {
+				const thisURL = new URL(importMeta.url, location.href);
+				thisURL.search = "";
+				const thisPathname = thisURL.pathname;
+
+				const alreadyRegistered = hmrRevalidateSet.has(thisPathname);
+				if (alreadyRegistered) {
+					return;
+				}
+
+				hmrRevalidateSet.add(thisPathname);
+
+				import.meta.hot.on("vite:afterUpdate", (props) => {
+					for (const update of props.updates) {
+						if (update.type === "js-update") {
+							const updateURL = new URL(
+								update.path,
+								location.href,
+							);
+							updateURL.search = "";
+							if (updateURL.pathname === thisURL.pathname) {
+								if (
+									__vormaClientGlobal
+										.get("matchedPatterns")
+										.includes(pattern)
+								) {
+									logInfo(
+										"Refreshing client loaders due to change in pattern:",
+										pattern,
+									);
+									devTimeSetupClientLoadersDebounced();
+								}
+							}
+						}
+					}
+				});
+			}
+		};
+	}
+}

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

@@ -0,0 +1,134 @@
+import {
+	createPatternRegistry,
+	registerPattern,
+} from "vorma/kit/matcher/register";
+import { setupClientLoaders } from "./client_loaders.ts";
+import { ComponentLoader } from "./component_loader.ts";
+import { defaultErrorBoundary } from "./error_boundary.ts";
+import { VORMA_HARD_RELOAD_QUERY_PARAM } from "./hard_reload.ts";
+import { HistoryManager } from "./history/history.ts";
+import { initHMR } from "./hmr/hmr.ts";
+import { scrollStateManager } from "./scroll_state_manager.ts";
+import type { VormaAppConfig } from "./vorma_app_helpers/vorma_app_helpers.ts";
+import {
+	__vormaClientGlobal,
+	type RouteErrorComponent,
+	type VormaClientGlobal,
+} from "./vorma_ctx/vorma_ctx.ts";
+
+export async function initClient(options: {
+	vormaAppConfig: VormaAppConfig;
+	renderFn: () => void;
+	defaultErrorBoundary?: RouteErrorComponent;
+	useViewTransitions?: boolean;
+}): Promise<void> {
+	initHMR();
+
+	// Setup beforeunload handler for scroll restoration
+	window.addEventListener("beforeunload", () => {
+		scrollStateManager.savePageRefreshState();
+	});
+
+	__vormaClientGlobal.set("vormaAppConfig", options.vormaAppConfig);
+	const clientModuleMap: VormaClientGlobal["clientModuleMap"] = {};
+
+	// Populate client module map with initial page's modules
+	const initialMatchedPatterns =
+		__vormaClientGlobal.get("matchedPatterns") || [];
+	const initialImportURLs = __vormaClientGlobal.get("importURLs") || [];
+	const initialExportKeys = __vormaClientGlobal.get("exportKeys") || [];
+	const initialErrorExportKeys =
+		__vormaClientGlobal.get("errorExportKeys") || [];
+
+	for (let i = 0; i < initialMatchedPatterns.length; i++) {
+		const pattern = initialMatchedPatterns[i];
+		const importURL = initialImportURLs[i];
+		const exportKey = initialExportKeys[i];
+		const errorExportKey = initialErrorExportKeys[i];
+
+		if (pattern && importURL) {
+			clientModuleMap[pattern] = {
+				importURL,
+				exportKey: exportKey || "default",
+				errorExportKey: errorExportKey || "",
+			};
+		}
+	}
+	__vormaClientGlobal.set("clientModuleMap", clientModuleMap);
+
+	const patternRegistry = createPatternRegistry({
+		dynamicParamPrefixRune: options.vormaAppConfig.loadersDynamicRune,
+		splatSegmentRune: options.vormaAppConfig.loadersSplatRune,
+		explicitIndexSegment:
+			options.vormaAppConfig.loadersExplicitIndexSegment,
+	});
+	__vormaClientGlobal.set("patternRegistry", patternRegistry);
+
+	const manifestURL = __vormaClientGlobal.get("routeManifestURL");
+	if (manifestURL) {
+		fetch(manifestURL)
+			.then((response) => response.json())
+			.then((manifest) => {
+				__vormaClientGlobal.set("routeManifest", manifest);
+
+				// Register all patterns from manifest into the existing registry
+				for (const pattern of Object.keys(manifest)) {
+					registerPattern(patternRegistry, pattern);
+				}
+			})
+			.catch((error) => {
+				// This is no biggie -- it's a progressive enhancement
+				console.warn("Failed to load route manifest:", error);
+			});
+	}
+
+	// Set options
+	if (options.defaultErrorBoundary) {
+		__vormaClientGlobal.set(
+			"defaultErrorBoundary",
+			options.defaultErrorBoundary,
+		);
+	} else {
+		__vormaClientGlobal.set("defaultErrorBoundary", defaultErrorBoundary);
+	}
+
+	if (options.useViewTransitions) {
+		__vormaClientGlobal.set("useViewTransitions", true);
+	}
+
+	// Initialize history
+	HistoryManager.init();
+
+	// Clean URL
+	const url = new URL(window.location.href);
+	if (url.searchParams.has(VORMA_HARD_RELOAD_QUERY_PARAM)) {
+		url.searchParams.delete(VORMA_HARD_RELOAD_QUERY_PARAM);
+		HistoryManager.getInstance().replace(url.href);
+	}
+
+	const importURLs = __vormaClientGlobal.get("importURLs");
+
+	// Load initial components
+	await ComponentLoader.handleComponents(importURLs);
+
+	// Setup client loaders
+	await setupClientLoaders();
+
+	// Handle error boundary component (must come after setupClientLoaders)
+	await ComponentLoader.handleErrorBoundaryComponent(importURLs);
+
+	// Render
+	options.renderFn();
+
+	// Restore scroll
+	scrollStateManager.restorePageRefreshState();
+
+	// Touch detection
+	window.addEventListener(
+		"touchstart",
+		() => {
+			__vormaClientGlobal.set("isTouchDevice", true);
+		},
+		{ once: true },
+	);
+}