@ecopages/react-router 0.2.0-alpha.5 → 0.2.0-alpha.51

package/src/context.ts

@@ -1,25 +0,0 @@
-/**
- * Router context and hook for accessing navigation state.
- * @module
- */
-
-import { createContext, useContext } from 'react';
-
-export type RouterContextValue = {
-	navigate: (url: string) => void;
-	isNavigating: boolean;
-};
-
-export const RouterContext = createContext<RouterContextValue | null>(null);
-
-/**
- * Hook to access the router's navigate function and navigation state.
- * Must be used within an EcoRouter.
- *
- * @throws Error if used outside of EcoRouter
- */
-export const useRouter = (): RouterContextValue => {
-	const context = useContext(RouterContext);
-	if (!context) throw new Error('useRouter must be used within EcoRouter');
-	return context;
-};

package/src/head-morpher.ts

@@ -1,170 +0,0 @@
-/**
- * Head morphing utilities for client-side navigation.
- * Intelligently syncs head elements between pages using key-based diffing.
- * @module
- */
-
-const PRESERVE_SELECTORS = ['script[type="importmap"]', 'meta[charset]', '[data-eco-persist]'];
-
-/**
- * Computes a unique key for a head element to enable diffing.
- * Elements with the same key are considered the same across navigations.
- */
-function getHeadElementKey(el: Element): string | null {
-	const tag = el.tagName.toLowerCase();
-
-	switch (tag) {
-		case 'title':
-			return 'title';
-
-		case 'meta': {
-			const name = el.getAttribute('name') || el.getAttribute('property') || el.getAttribute('http-equiv');
-			return name ? `meta:${name}` : null;
-		}
-
-		case 'link': {
-			const rel = el.getAttribute('rel');
-			const href = el.getAttribute('href');
-			if (rel === 'stylesheet' && href) return `stylesheet:${href}`;
-			if (rel === 'icon' || rel === 'shortcut icon') return 'favicon';
-			if (rel === 'canonical') return 'canonical';
-			return href ? `link:${href}` : null;
-		}
-
-		case 'script': {
-			if (el.getAttribute('type') === 'importmap') return 'importmap';
-			const src = (el as HTMLScriptElement).src;
-			return src ? `script:${src}` : null;
-		}
-
-		case 'style': {
-			const dataId = el.getAttribute('data-eco-style');
-			return dataId ? `style:${dataId}` : null;
-		}
-
-		default:
-			return null;
-	}
-}
-
-/**
- * Morphs the current document head to match the new document's head.
- * Now splits the process into adding new elements and returning a cleanup function
- * to remove old ones. This is crucial for View Transitions to ensure styles
- * don't disappear before the "old" snapshot is taken.
- *
- * @param newDocument - The parsed document from the navigation target
- * @returns Promise that resolves to a cleanup function when new stylesheets have loaded
- */
-export async function morphHead(newDocument: Document): Promise<() => void> {
-	const currentHead = document.head;
-	const newHead = newDocument.head;
-
-	const currentElements = new Map<string, Element>();
-	const newElements = new Map<string, Element>();
-	const stylesheetPromises: Promise<void>[] = [];
-	const elementsToRemove: Element[] = [];
-
-	/**
-	 * First, map existing head elements by their keys
-	 * to enable efficient diffing.
-	 */
-	for (const el of Array.from(currentHead.children)) {
-		const key = getHeadElementKey(el);
-		if (key) currentElements.set(key, el);
-	}
-
-	/**
-	 * Next, map new head elements by their keys.
-	 * This allows us to see which elements are new, updated, or removed.
-	 */
-	for (const el of Array.from(newHead.children)) {
-		const key = getHeadElementKey(el);
-		if (key) newElements.set(key, el);
-	}
-
-	/**
-	 * Now, iterate over new elements to add or update them in the current head.
-	 */
-	for (const [key, newEl] of newElements) {
-		const currentEl = currentElements.get(key);
-
-		if (!currentEl) {
-			const src = newEl.getAttribute('src');
-			/**
-			 * Skip hydration scripts during SPA navigation to prevent re-mounting
-			 *
-			 * In an SPA transition, the EcoRouter is already running and handling the page update.
-			 * The new page's HTML includes a hydration script (for initial load support), but
-			 * if we let it execute now, it would re-bootstrap the React app from scratch,
-			 * causing a full re-mount, state loss, and a visual flash.
-			 *
-			 * By blocking this script, we ensure the router maintains control and state.
-			 */
-			if (newEl.tagName === 'SCRIPT' && src && src.includes('hydration.js') && src.includes('ecopages-react')) {
-				continue;
-			}
-
-			const cloned = newEl.cloneNode(true) as Element;
-
-			/**
-			 * If the new element is a stylesheet, we need to wait for it to load
-			 * before considering the head morph complete. This prevents FOUC.
-			 */
-			if (cloned.tagName === 'LINK' && (cloned as HTMLLinkElement).rel === 'stylesheet') {
-				const loadPromise = new Promise<void>((resolve) => {
-					(cloned as HTMLLinkElement).onload = () => resolve();
-					(cloned as HTMLLinkElement).onerror = () => resolve();
-				});
-				stylesheetPromises.push(loadPromise);
-			}
-
-			currentHead.appendChild(cloned);
-		} else if (key === 'title' && currentEl.textContent !== newEl.textContent) {
-			currentEl.textContent = newEl.textContent;
-		} else if (key.startsWith('style:') && currentEl.textContent !== newEl.textContent) {
-			currentEl.textContent = newEl.textContent;
-		}
-	}
-
-	/**
-	 * Finally, handle any new elements without keys (e.g., inline scripts/styles)
-	 */
-	for (const newEl of Array.from(newHead.children)) {
-		const key = getHeadElementKey(newEl);
-		if (!key) {
-			currentHead.appendChild(newEl.cloneNode(true));
-		}
-	}
-
-	/**
-	 * Wait for all new stylesheets to load before proceeding.
-	 */
-	if (stylesheetPromises.length > 0) {
-		await Promise.all(stylesheetPromises);
-	}
-
-	/**
-	 * Identify and prepare to remove any old elements
-	 * that are no longer present in the new head.
-	 */
-	for (const [key, el] of currentElements) {
-		if (!newElements.has(key)) {
-			const shouldPreserve = PRESERVE_SELECTORS.some((sel) => el.matches(sel));
-			if (!shouldPreserve) {
-				elementsToRemove.push(el);
-			}
-		}
-	}
-
-	/**
-	 * Return a cleanup function to remove old elements.
-	 * This allows the caller to control when the removal happens,
-	 * which is important for View Transitions.
-	 */
-	return () => {
-		for (const el of elementsToRemove) {
-			el.remove();
-		}
-	};
-}

package/src/index.ts

@@ -1,21 +0,0 @@
-/**
- * EcoPages React Router - SPA navigation for React with SSR support.
- * @module
- */
-
-export { EcoRouter, PageContent } from './router.ts';
-export type { EcoRouterProps } from './router.ts';
-
-export { EcoPropsScript } from './props-script.ts';
-export type { EcoPropsScriptProps } from './props-script.ts';
-
-export { useRouter } from './context.ts';
-export type { RouterContextValue } from './context.ts';
-
-export type { EcoRouterOptions } from './types.ts';
-
-export { morphHead } from './head-morpher.ts';
-
-export type { PageState } from './navigation.ts';
-
-export { ecoRouter } from './adapter.ts';

package/src/manage-scroll.ts

@@ -1,47 +0,0 @@
-/**
- * Manages scroll position during navigations
- * @module
- */
-
-import type { EcoRouterOptions } from './types.ts';
-
-/**
- * Service for handling scroll position during page transitions.
- * Handles window scroll behavior and hash navigation.
- */
-/**
- * Handle window scroll position based on scrollBehavior option.
- * Hash links always scroll to target regardless of option.
- */
-export function manageScroll(
-	newUrl: URL,
-	previousUrl: URL,
-	options: {
-		scrollBehavior: Required<EcoRouterOptions>['scrollBehavior'];
-		smoothScroll: boolean;
-	},
-): void {
-	const { scrollBehavior, smoothScroll } = options;
-
-	if (newUrl.hash) {
-		const target = document.getElementById(newUrl.hash.slice(1));
-		target?.scrollIntoView({ behavior: smoothScroll ? 'smooth' : 'instant' });
-		return;
-	}
-
-	const behavior = smoothScroll ? 'smooth' : 'instant';
-
-	switch (scrollBehavior) {
-		case 'preserve':
-			break;
-		case 'auto':
-			if (newUrl.pathname !== previousUrl.pathname) {
-				window.scrollTo({ top: 0, left: 0, behavior });
-			}
-			break;
-		case 'top':
-		default:
-			window.scrollTo({ top: 0, left: 0, behavior });
-			break;
-	}
-}

package/src/navigation.ts

@@ -1,247 +0,0 @@
-/**
- * Navigation utilities for fetching and parsing page content.
- * @module
- */
-
-/// <reference types="@ecopages/core/declarations" />
-
-import { type ComponentType } from 'react';
-import type { EcoRouterOptions } from './types.ts';
-
-export type PageState = {
-	Component: ComponentType<any>;
-	props: Record<string, any>;
-};
-
-export type InterceptDecision =
-	| { shouldIntercept: true }
-	| {
-			shouldIntercept: false;
-			reason:
-				| 'modified-click'
-				| 'non-left-click'
-				| 'external-target'
-				| 'explicit-reload'
-				| 'download'
-				| 'invalid-href'
-				| 'cross-origin';
-	  };
-
-/**
- * Determines whether a link click should be intercepted for client-side navigation.
- *
- * Standard SPA navigation rules:
- * - Modified clicks (Cmd/Ctrl/Shift/Alt) open in new tab
- * - Non-left clicks use default browser behavior
- * - External targets, downloads, and cross-origin links navigate normally
- *
- * @returns Object indicating whether to intercept and the reason if not
- */
-export function getInterceptDecision(
-	event: MouseEvent,
-	link: HTMLAnchorElement,
-	options: Required<EcoRouterOptions>,
-): InterceptDecision {
-	if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-		return { shouldIntercept: false, reason: 'modified-click' };
-	}
-	if (event.button !== 0) return { shouldIntercept: false, reason: 'non-left-click' };
-
-	const target = link.getAttribute('target');
-	if (target && target !== '_self') return { shouldIntercept: false, reason: 'external-target' };
-
-	if (link.hasAttribute(options.reloadAttribute)) return { shouldIntercept: false, reason: 'explicit-reload' };
-	if (link.hasAttribute('download')) return { shouldIntercept: false, reason: 'download' };
-
-	const href = link.getAttribute('href');
-	if (!href || href.startsWith('#') || href.startsWith('javascript:')) {
-		return { shouldIntercept: false, reason: 'invalid-href' };
-	}
-
-	const url = new URL(href, window.location.origin);
-	if (url.origin !== window.location.origin) return { shouldIntercept: false, reason: 'cross-origin' };
-
-	return { shouldIntercept: true };
-}
-
-/**
- * Extracts component module URL from window.__ECO_PAGE__.
- * For current document, returns the module path set by hydration script.
- * For fetched documents, parses the hydration script to extract the module path.
- */
-function extractComponentUrlFromMarker(doc: Document): string | null {
-	if (doc === document && window.__ECO_PAGE__?.module) {
-		return window.__ECO_PAGE__.module;
-	}
-	return null;
-}
-
-/**
- * Matches default import: `import Content from './Content'`
- * Used to extract module path from hydration script for fetched documents.
- */
-const DEFAULT_IMPORT_REGEX = /import\s+(\w+)\s+from\s*['"]([^'"]+)['"]/;
-
-/**
- * Matches namespace import: `import * as Content from './Content'`
- * Used for MDX components. Also handles minified: `import*as Content from'./Content'`
- */
-const NAMESPACE_IMPORT_REGEX = /import\s*\*\s*as\s*(\w+)\s*from\s*['"]([^'"]+)['"]/;
-
-/**
- * Extracts import path from hydration script code using regex.
- * Used for fetched documents. Less reliable due to minification.
- */
-function extractModulePathFromCode(code: string): string | null {
-	const defaultMatch = code.match(DEFAULT_IMPORT_REGEX);
-	const namespaceMatch = code.match(NAMESPACE_IMPORT_REGEX);
-	return (defaultMatch || namespaceMatch)?.[2] ?? null;
-}
-
-/**
- * Extracts serialized page props from window.__ECO_PAGE__ or fetched document.
- * For current document, returns props set by hydration script.
- * For fetched documents, parses the JSON script tag directly.
- */
-export function extractProps(doc: Document): Record<string, any> {
-	if (doc === document && window.__ECO_PAGE__?.props) {
-		return window.__ECO_PAGE__.props;
-	}
-
-	const propsScript = doc.getElementById('__ECO_PAGE_DATA__');
-	if (propsScript?.textContent) {
-		try {
-			return JSON.parse(propsScript.textContent);
-		} catch (e) {
-			console.error('[EcoRouter] Failed to parse props:', e);
-			return {};
-		}
-	}
-
-	return {};
-}
-
-/**
- * Adds cache-busting timestamp for HMR in development.
- *
- * Prevents loading stale cached modules when navigating to previously visited pages.
- * Disabled in production where filenames have content hashes.
- */
-function addCacheBuster(url: string): string {
-	if (import.meta.env?.MODE === 'production' || import.meta.env?.PROD) {
-		return url;
-	}
-	const separator = url.includes('?') ? '&' : '?';
-	return `${url}${separator}t=${Date.now()}`;
-}
-
-/**
- * Extracts component module URL using multi-tier strategy.
- *
- * 1. Read from window.__ECO_PAGE__.module (for current document)
- * 2. Parse inline hydration script with regex (for fetched documents)
- * 3. Fetch and parse external hydration script (final fallback)
- *
- * Regex parsing is less reliable due to minification.
- */
-export async function extractComponentUrl(doc: Document): Promise<string | null> {
-	const markerUrl = extractComponentUrlFromMarker(doc);
-	if (markerUrl) return markerUrl;
-
-	const scripts = Array.from(doc.querySelectorAll('script'));
-
-	const inlineHydrationScript = scripts.find(
-		(s) =>
-			!s.src &&
-			!!s.textContent &&
-			s.textContent.includes('__ECO_PAGE__') &&
-			s.textContent.includes('hydrateRoot') &&
-			s.textContent.includes('import'),
-	);
-
-	if (inlineHydrationScript?.textContent) {
-		return extractModulePathFromCode(inlineHydrationScript.textContent);
-	}
-
-	const hydrationScript = scripts.find((s) => s.src?.includes('hydration.js') && s.src?.includes('ecopages-react'));
-	if (!hydrationScript?.src) return null;
-
-	try {
-		const scriptUrl = addCacheBuster(hydrationScript.src);
-		const res = await fetch(scriptUrl);
-		const code = await res.text();
-		return extractModulePathFromCode(code);
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Fetches and parses a page, returning its component, props, and document.
- *
- * Flow: Fetch HTML → Parse → Extract props → Extract component URL → Import module
- *
- * Handles multiple export patterns (Content, default.Content, default) for different
- * integration setups. Does NOT update DOM - caller applies changes.
- *
- * @param url - The URL to load
- * @returns Object with Component, props, doc, and finalPath, or null on error
- */
-export async function loadPageModule(
-	url: string,
-): Promise<{ Component: ComponentType<any>; props: Record<string, any>; doc: Document; finalPath: string } | null> {
-	try {
-		const res = await fetch(url);
-		const html = await res.text();
-
-		const finalUrl = new URL(res.url || url, window.location.origin);
-		const finalPath = finalUrl.pathname + finalUrl.search;
-
-		const doc = new DOMParser().parseFromString(html, 'text/html');
-
-		const props = extractProps(doc);
-		const componentUrl = await extractComponentUrl(doc);
-
-		if (!componentUrl) {
-			console.error('[EcoRouter] Could not find component URL');
-			return null;
-		}
-
-		const moduleUrl = addCacheBuster(componentUrl);
-		const module = await import(/* @vite-ignore */ moduleUrl);
-		const rawComponent = module.Content || module.default?.Content || module.default;
-
-		const config = module.config || rawComponent?.config;
-
-		if (!rawComponent) {
-			console.error('[EcoRouter] No component found in module');
-			return null;
-		}
-
-		if (config && !rawComponent.config) {
-			rawComponent.config = config;
-		}
-
-		window.__ECO_PAGE__ = {
-			module: componentUrl,
-			props,
-		};
-
-		return { Component: rawComponent, props, doc, finalPath };
-	} catch (e) {
-		console.error('[EcoRouter] Navigation failed:', e);
-		return null;
-	}
-}
-
-/**
- * Convenience wrapper around getInterceptDecision that returns a boolean.
- * Use getInterceptDecision directly when you need the reason for debugging.
- */
-export function shouldInterceptClick(
-	event: MouseEvent,
-	link: HTMLAnchorElement,
-	options: Required<EcoRouterOptions>,
-): boolean {
-	return getInterceptDecision(event, link, options).shouldIntercept;
-}

package/src/props-script.ts

@@ -1,19 +0,0 @@
-import { createElement, type FC } from 'react';
-
-export interface EcoPropsScriptProps {
-	/** The page props to serialize for client-side hydration */
-	data: Record<string, any>;
-}
-
-/**
- * Serializes page props as JSON for SPA navigation.
- * The hydration script reads this and sets window.__ECO_PAGE__.
- * Using application/json allows direct parsing without regex.
- */
-export const EcoPropsScript: FC<EcoPropsScriptProps> = ({ data }) => {
-	return createElement('script', {
-		id: '__ECO_PAGE_DATA__',
-		type: 'application/json',
-		dangerouslySetInnerHTML: { __html: JSON.stringify(data || {}) },
-	});
-};