@ecopages/browser-router 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/client/eco-router.ts

@@ -1,290 +0,0 @@
-/**
- * Client-side router for Ecopages with morphdom-based DOM diffing.
- * @module eco-router
- */
-
-import type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types.ts';
-import { DEFAULT_OPTIONS } from './types.ts';
-import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } from './services/index.ts';
-
-/**
- * Intercepts same-origin link clicks and performs client-side navigation
- * using morphdom for efficient DOM diffing. Supports View Transitions API.
- */
-export class EcoRouter {
-	private options: Required<EcoRouterOptions>;
-	private abortController: AbortController | null = null;
-
-	private domSwapper: DomSwapper;
-	private scrollManager: ScrollManager;
-	private viewTransitionManager: ViewTransitionManager;
-	private prefetchManager: PrefetchManager | null = null;
-
-	constructor(options: EcoRouterOptions = {}) {
-		this.options = { ...DEFAULT_OPTIONS, ...options };
-
-		this.domSwapper = new DomSwapper(this.options.persistAttribute);
-		this.scrollManager = new ScrollManager(this.options.scrollBehavior, this.options.smoothScroll);
-		this.viewTransitionManager = new ViewTransitionManager(this.options.viewTransitions);
-
-		if (this.options.prefetch !== false) {
-			this.prefetchManager = new PrefetchManager({
-				...this.options.prefetch,
-				linkSelector: this.options.linkSelector,
-			});
-		}
-
-		this.handleClick = this.handleClick.bind(this);
-		this.handlePopState = this.handlePopState.bind(this);
-	}
-
-	/**
-	 * Starts the router and begins intercepting navigation.
-	 *
-	 * Attaches click handlers for links and popstate handlers for browser
-	 * back/forward buttons. Also starts the prefetch manager if configured.
-	 */
-	public start(): void {
-		document.addEventListener('click', this.handleClick);
-		window.addEventListener('popstate', this.handlePopState);
-		this.prefetchManager?.start();
-
-		// Cache the initial page for instant back-navigation
-		const initialHtml = document.documentElement.outerHTML;
-		this.prefetchManager?.cacheVisitedPage(window.location.href, initialHtml);
-	}
-
-	/**
-	 * Stops the router and cleans up all event listeners.
-	 * After calling this, navigation will fall back to full page reloads.
-	 */
-	public stop(): void {
-		document.removeEventListener('click', this.handleClick);
-		window.removeEventListener('popstate', this.handlePopState);
-		this.prefetchManager?.stop();
-	}
-
-	/**
-	 * Programmatic navigation.
-	 * Falls back to full page reload for cross-origin URLs.
-	 * @param href - The URL to navigate to
-	 * @param options - Navigation options
-	 * @param options.replace - If true, replaces the current history entry instead of pushing
-	 */
-	public async navigate(href: string, options: { replace?: boolean } = {}): Promise<void> {
-		const url = new URL(href, window.location.origin);
-
-		if (!this.isSameOrigin(url)) {
-			window.location.href = href;
-			return;
-		}
-
-		await this.performNavigation(url, options.replace ? 'replace' : 'forward');
-	}
-
-	/**
-	 * Manually prefetch a URL.
-	 * @param href - The URL to prefetch
-	 */
-	public async prefetch(href: string): Promise<void> {
-		if (!this.prefetchManager) {
-			console.warn('[ecopages] Prefetching is disabled. Enable it in router options.');
-			return;
-		}
-		return this.prefetchManager.prefetch(href);
-	}
-
-	/**
-	 * Intercepts link clicks for client-side navigation.
-	 *
-	 * Filters out clicks with modifier keys (opens new tab), non-left clicks,
-	 * external links, download links, and links with the reload attribute.
-	 *
-	 * Uses `event.composedPath()` to correctly detect clicks on anchors inside
-	 * Shadow DOM boundaries (Web Components).
-	 */
-	private handleClick(event: MouseEvent): void {
-		const link = event
-			.composedPath()
-			.find(
-				(el) => el instanceof HTMLAnchorElement && el.matches(this.options.linkSelector),
-			) as HTMLAnchorElement | null;
-
-		if (!link) return;
-
-		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-		if (event.button !== 0) return;
-
-		const target = link.getAttribute('target');
-		if (target && target !== '_self') return;
-
-		if (link.hasAttribute(this.options.reloadAttribute)) return;
-		if (link.hasAttribute('download')) return;
-
-		const href = link.getAttribute('href');
-		if (!href) return;
-
-		if (href.startsWith('#')) return;
-		if (href.startsWith('javascript:')) return;
-
-		const url = new URL(href, window.location.origin);
-
-		if (!this.isSameOrigin(url)) return;
-
-		event.preventDefault();
-		this.performNavigation(url, 'forward');
-	}
-
-	/**
-	 * Handles browser back/forward navigation.
-	 * Triggered by the History API's popstate event.
-	 */
-	private handlePopState(_event: PopStateEvent): void {
-		const url = new URL(window.location.href);
-		this.performNavigation(url, 'back');
-	}
-
-	/**
-	 * Checks if a URL shares the same origin as the current page.
-	 * Cross-origin navigation always falls back to full page reload.
-	 */
-	private isSameOrigin(url: URL): boolean {
-		return url.origin === window.location.origin;
-	}
-
-	/**
-	 * Executes the core navigation flow.
-	 *
-	 * Orchestrates fetching, DOM swapping, and lifecycle events:
-	 *
-	 * 1. **Fetch** - Retrieves HTML (from cache or network)
-	 * 2. **eco:before-swap** - Allows listeners to force a full reload
-	 * 3. **History update** - Updates URL before DOM swap so Web Components
-	 *    see the correct URL in their `connectedCallback`
-	 * 4. **Stylesheet preload** - Prevents FOUC by loading styles first
-	 * 5. **DOM swap** - Morphs head/body, optionally with View Transition
-	 * 6. **Lifecycle events** - Dispatches `eco:after-swap` and `eco:page-load`
-	 *
-	 * Falls back to full page reload on network errors.
-	 *
-	 * @param url - The target URL to navigate to
-	 * @param direction - Navigation direction ('forward', 'back', or 'replace')
-	 */
-	private async performNavigation(url: URL, direction: EcoNavigationEvent['direction']): Promise<void> {
-		const previousUrl = new URL(window.location.href);
-
-		this.abortController?.abort();
-		this.abortController = new AbortController();
-
-		try {
-			const html = await this.fetchPage(url, this.abortController.signal);
-			const newDocument = this.domSwapper.parseHTML(html, url);
-
-			let shouldReload = false;
-			const beforeSwapEvent: EcoBeforeSwapEvent = {
-				url,
-				direction,
-				newDocument,
-				reload: () => {
-					shouldReload = true;
-				},
-			};
-
-			document.dispatchEvent(new CustomEvent('eco:before-swap', { detail: beforeSwapEvent }));
-
-			if (shouldReload) {
-				window.location.href = url.href;
-				return;
-			}
-
-			if (this.options.updateHistory && direction === 'forward') {
-				window.history.pushState({}, '', url.href);
-			} else if (direction === 'replace') {
-				window.history.replaceState({}, '', url.href);
-			}
-
-			const useViewTransitions = this.options.viewTransitions;
-			await this.domSwapper.preloadStylesheets(newDocument);
-
-			if (useViewTransitions) {
-				await this.viewTransitionManager.transition(() => {
-					this.domSwapper.morphHead(newDocument);
-					this.domSwapper.morphBody(newDocument);
-					this.scrollManager.handleScroll(url, previousUrl);
-				});
-			} else {
-				this.domSwapper.morphHead(newDocument);
-				this.domSwapper.replaceBody(newDocument);
-				this.scrollManager.handleScroll(url, previousUrl);
-			}
-
-			const afterSwapEvent: EcoAfterSwapEvent = {
-				url,
-				direction,
-			};
-
-			document.dispatchEvent(new CustomEvent('eco:after-swap', { detail: afterSwapEvent }));
-
-			this.prefetchManager?.observeNewLinks();
-
-			// Cache the visited page for instant revisits (stale-while-revalidate)
-			this.prefetchManager?.cacheVisitedPage(url.href, html);
-
-			requestAnimationFrame(() => {
-				document.dispatchEvent(
-					new CustomEvent('eco:page-load', {
-						detail: { url, direction } as EcoNavigationEvent,
-					}),
-				);
-			});
-		} catch (error) {
-			if (error instanceof Error && error.name === 'AbortError') {
-				return;
-			}
-
-			console.error('[ecopages] Navigation failed:', error);
-			window.location.href = url.href;
-		}
-	}
-
-	/**
-	 * Fetches the HTML content of a page.
-	 * @param url - The URL to fetch
-	 * @param signal - AbortSignal for cancelling the request
-	 * @throws Error if the response is not ok
-	 */
-	private async fetchPage(url: URL, signal: AbortSignal): Promise<string> {
-		if (this.prefetchManager) {
-			const cachedHtml = this.prefetchManager.getCachedHtml(url.href);
-			if (cachedHtml) {
-				return cachedHtml;
-			}
-		}
-
-		const response = await fetch(url.href, {
-			signal,
-			headers: {
-				Accept: 'text/html',
-			},
-		});
-
-		if (!response.ok) {
-			throw new Error(`Failed to fetch page: ${response.status}`);
-		}
-
-		return response.text();
-	}
-}
-
-/**
- * Creates and starts a router instance.
- * @param options - Configuration options for the router
- * @returns A started EcoRouter instance
- */
-export function createRouter(options?: EcoRouterOptions): EcoRouter {
-	const router = new EcoRouter(options);
-	router.start();
-	return router;
-}
-
-export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types';

package/src/client/services/dom-swapper.ts

@@ -1,325 +0,0 @@
-/**
- * DOM morphing service for client-side navigation.
- * Uses Idiomorph for body morphing and Turbo-style surgical updates for head.
- * @module dom-swapper
- */
-
-import morphdom from 'morphdom';
-
-const DEFAULT_PERSIST_ATTR = 'data-eco-persist';
-
-/**
- * Checks if element has a persist attribute (custom or default).
- */
-function isPersisted(element: Element, persistAttribute: string): boolean {
-	return element.hasAttribute(persistAttribute) || element.hasAttribute(DEFAULT_PERSIST_ATTR);
-}
-
-/**
- * Detects hydrated custom elements (with shadow DOM) that should skip morphing.
- */
-function isHydratedCustomElement(element: Element): boolean {
-	return element.localName.includes('-') && element.shadowRoot !== null;
-}
-
-/**
- * Handles DOM manipulation during client-side page transitions.
- *
- * Uses a hybrid approach inspired by Turbo:
- * - Surgical head updates (no morphing) to prevent FOUC
- * - Idiomorph for efficient body diffing
- */
-export class DomSwapper {
-	private persistAttribute: string;
-
-	constructor(persistAttribute: string) {
-		this.persistAttribute = persistAttribute;
-	}
-
-	/**
-	 * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
-	 */
-	parseHTML(html: string, url?: URL): Document {
-		const parser = new DOMParser();
-		const htmlToParse = url ? `<base href="${url.href}" data-eco-injected>${html}` : html;
-		return parser.parseFromString(htmlToParse, 'text/html');
-	}
-
-	/**
-	 * Preloads new stylesheets from target document to prevent FOUC.
-	 *
-	 * Discovers stylesheet links in the target document that aren't present in the
-	 * current document, creates corresponding link elements, and waits for all to
-	 * load before resolving. This follows Turbo's approach of waiting for stylesheets
-	 * before any DOM updates.
-	 */
-	async preloadStylesheets(newDocument: Document): Promise<void> {
-		const existingHrefs = new Set(
-			Array.from(document.head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')).map((l) => l.href),
-		);
-
-		const newStylesheetLinks = Array.from(
-			newDocument.head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'),
-		).filter((link) => !existingHrefs.has(link.href));
-
-		if (newStylesheetLinks.length === 0) {
-			return;
-		}
-
-		const TIMEOUT = 5000;
-		const loadPromises = newStylesheetLinks.map((link) => {
-			return new Promise<void>((resolve) => {
-				const newLink = document.createElement('link');
-				newLink.rel = 'stylesheet';
-				newLink.media = link.media || 'all';
-
-				const timeoutId = setTimeout(() => {
-					cleanup();
-					resolve();
-				}, TIMEOUT);
-
-				const cleanup = () => {
-					clearTimeout(timeoutId);
-					newLink.onload = null;
-					newLink.onerror = null;
-				};
-
-				newLink.onload = () => {
-					cleanup();
-					resolve();
-				};
-
-				newLink.onerror = () => {
-					cleanup();
-					resolve();
-				};
-
-				newLink.href = link.href;
-				document.head.appendChild(newLink);
-			});
-		});
-
-		await Promise.all(loadPromises);
-	}
-
-	/**
-	 * Updates document head using Turbo-style surgical updates.
-	 *
-	 * This approach avoids morphing the head element entirely, which prevents
-	 * browser repaints that cause FOUC. Instead, it:
-	 * - Updates the document title
-	 * - Merges meta tags (adds new, updates changed)
-	 * - Leaves stylesheets untouched (they're preloaded separately)
-	 * - Handles script re-execution for marked scripts
-	 * - Injects new scripts from the incoming page that are absent from the current head
-	 */
-	morphHead(newDocument: Document): void {
-		/** Update the document title if it has changed. */
-		const newTitle = newDocument.head.querySelector('title');
-		if (newTitle && document.title !== newTitle.textContent) {
-			document.title = newTitle.textContent || '';
-		}
-
-		/** Merge meta tags: update existing ones whose content changed, append new ones. */
-		const newMetas = newDocument.head.querySelectorAll('meta[name], meta[property]');
-		for (const newMeta of newMetas) {
-			const name = newMeta.getAttribute('name');
-			const property = newMeta.getAttribute('property');
-			const content = newMeta.getAttribute('content');
-
-			const selector = name ? `meta[name="${name}"]` : `meta[property="${property}"]`;
-			const existingMeta = document.head.querySelector(selector);
-
-			if (existingMeta) {
-				if (existingMeta.getAttribute('content') !== content) {
-					existingMeta.setAttribute('content', content || '');
-				}
-			} else {
-				document.head.appendChild(newMeta.cloneNode(true));
-			}
-		}
-
-		/**
-		 * Re-execute scripts that are explicitly marked with `data-eco-rerun`.
-		 * Deduplication is performed via `data-eco-script-id` to prevent double execution.
-		 */
-		const existingScriptIds = new Set(
-			Array.from(document.head.querySelectorAll('script[data-eco-script-id]')).map((s) =>
-				s.getAttribute('data-eco-script-id'),
-			),
-		);
-
-		const rerunScripts = newDocument.head.querySelectorAll('script[data-eco-rerun]');
-		for (const script of rerunScripts) {
-			const scriptId = script.getAttribute('data-eco-script-id');
-			if (scriptId && !existingScriptIds.has(scriptId)) {
-				const newScript = document.createElement('script');
-				for (const attr of script.attributes) {
-					if (attr.name !== 'data-eco-rerun') {
-						newScript.setAttribute(attr.name, attr.value);
-					}
-				}
-				newScript.textContent = script.textContent;
-				document.head.appendChild(newScript);
-			}
-		}
-
-		/**
-		 * Inject new scripts from the incoming page that are not already loaded.
-		 *
-		 * When the client-side router swaps pages, the new page may require scripts
-		 * (e.g. custom-element definitions) that were not present on the previous page.
-		 * Because the browser only executes a <script> element when it is first parsed
-		 * or dynamically appended to the DOM, a fresh element must be created for each
-		 * new script — cloneNode() alone is not sufficient to trigger execution.
-		 *
-		 * - External scripts are matched by their `src` attribute.
-		 * - Inline scripts are matched by trimmed text content to avoid re-running duplicates.
-		 */
-		const existingScriptSrcs = new Set(
-			Array.from(document.head.querySelectorAll('script[src]')).map((s) => s.getAttribute('src')),
-		);
-		const existingInlineContents = new Set(
-			Array.from(document.head.querySelectorAll('script:not([src])')).map((s) => (s.textContent ?? '').trim()),
-		);
-
-		const allNewHeadScripts = newDocument.head.querySelectorAll('script');
-		for (const script of allNewHeadScripts) {
-			/** Skip scripts already handled by the `data-eco-rerun` mechanism above. */
-			if (script.hasAttribute('data-eco-rerun')) continue;
-
-			const src = script.getAttribute('src');
-
-			if (src) {
-				if (existingScriptSrcs.has(src)) continue;
-				/** New external script — append a freshly created element so the browser fetches and executes it. */
-				const newScript = document.createElement('script');
-				for (const attr of script.attributes) {
-					newScript.setAttribute(attr.name, attr.value);
-				}
-				document.head.appendChild(newScript);
-				existingScriptSrcs.add(src);
-			} else {
-				/** Inline script — skip if identical content is already present to avoid re-running on every navigation. */
-				const content = (script.textContent ?? '').trim();
-				if (!content || existingInlineContents.has(content)) continue;
-				const newScript = document.createElement('script');
-				for (const attr of script.attributes) {
-					newScript.setAttribute(attr.name, attr.value);
-				}
-				newScript.textContent = script.textContent;
-				document.head.appendChild(newScript);
-				existingInlineContents.add(content);
-			}
-		}
-	}
-
-	/**
-	 * Detects custom elements without shadow DOM (light-DOM custom elements).
-	 * These need full replacement rather than morphing, because morphdom would
-	 * strip JS-generated content from their light DOM children.
-	 */
-	private isLightDomCustomElement(element: Element): boolean {
-		return element.localName.includes('-') && element.shadowRoot === null;
-	}
-
-	/**
-	 * Morphs document body using morphdom.
-	 * Preserves persisted elements and hydrated custom elements.
-	 * Light-DOM custom elements are fully replaced to trigger proper
-	 * disconnectedCallback → connectedCallback lifecycle.
-	 */
-	morphBody(newDocument: Document): void {
-		const persistAttr = this.persistAttribute;
-
-		morphdom(document.body, newDocument.body, {
-			onBeforeElUpdated: (fromEl, toEl) => {
-				if (isPersisted(fromEl, persistAttr)) {
-					return false;
-				}
-				if (isHydratedCustomElement(fromEl)) {
-					return false;
-				}
-
-				/**
-				 * Light-DOM custom elements (e.g. <radiant-code-tabs>) often
-				 * generate DOM in connectedCallback that doesn't exist in the
-				 * server-rendered HTML. Morphdom would diff those children away.
-				 * Instead, replace the element entirely so the browser fires
-				 * disconnectedCallback on the old instance and connectedCallback
-				 * on the fresh one.
-				 */
-				if (this.isLightDomCustomElement(fromEl)) {
-					const newEl = document.createElement(toEl.tagName);
-					for (const attr of toEl.attributes) {
-						newEl.setAttribute(attr.name, attr.value);
-					}
-					newEl.innerHTML = toEl.innerHTML;
-					fromEl.replaceWith(newEl);
-					return false;
-				}
-
-				if (fromEl.isEqualNode(toEl)) {
-					return false;
-				}
-
-				return true;
-			},
-		});
-
-		this.processDeclarativeShadowDOM(document.body);
-	}
-
-	/**
-	 * Replaces body content in a single operation.
-	 * Preserves persisted elements by moving them to the new body.
-	 * Use when View Transitions are disabled.
-	 */
-	replaceBody(newDocument: Document): void {
-		const persistAttr = this.persistAttribute;
-
-		const persistedElements = document.body.querySelectorAll(`[${persistAttr}], [${DEFAULT_PERSIST_ATTR}]`);
-		const persistedMap = new Map<string, Element>();
-
-		for (const el of persistedElements) {
-			const key = el.getAttribute(persistAttr) || el.getAttribute(DEFAULT_PERSIST_ATTR);
-			if (key) {
-				persistedMap.set(key, el);
-			}
-		}
-
-		for (const [key, oldEl] of persistedMap) {
-			const placeholder = newDocument.body.querySelector(
-				`[${persistAttr}="${key}"], [${DEFAULT_PERSIST_ATTR}="${key}"]`,
-			);
-			if (placeholder) {
-				placeholder.replaceWith(oldEl);
-			}
-		}
-
-		document.body.replaceChildren(...newDocument.body.childNodes);
-		this.processDeclarativeShadowDOM(document.body);
-	}
-
-	/**
-	 * Manually attaches declarative shadow DOM templates.
-	 * Browsers only process `<template shadowrootmode>` during initial parse.
-	 */
-	private processDeclarativeShadowDOM(root: Element | Document | ShadowRoot): void {
-		const templates = root.querySelectorAll<HTMLTemplateElement>('template[shadowrootmode], template[shadowroot]');
-
-		for (const template of templates) {
-			const mode = (template.getAttribute('shadowrootmode') ||
-				template.getAttribute('shadowroot')) as ShadowRootMode;
-			const parent = template.parentElement;
-
-			if (parent && !parent.shadowRoot) {
-				const shadowRoot = parent.attachShadow({ mode });
-				shadowRoot.appendChild(template.content);
-				template.remove();
-
-				this.processDeclarativeShadowDOM(shadowRoot);
-			}
-		}
-	}
-}

package/src/client/services/index.ts

@@ -1,9 +0,0 @@
-/**
- * Services for the EcoPages transitions package
- * @module
- */
-
-export { DomSwapper } from './dom-swapper.ts';
-export { ScrollManager } from './scroll-manager.ts';
-export { ViewTransitionManager } from './view-transition-manager.ts';
-export { PrefetchManager } from './prefetch-manager.ts';