@ecopages/react-router 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/router.ts

@@ -1,348 +0,0 @@
-/**
- * SPA router with View Transitions API support for React applications.
- *
- * Intercepts link clicks for client-side navigation using the History API.
- * Supports animated page transitions via CSS view-transition pseudo-elements.
- *
- * @module router
- */
-
-import {
-	useEffect,
-	useState,
-	useCallback,
-	useMemo,
-	useRef,
-	createContext,
-	useContext,
-	startTransition,
-	createElement,
-	type ReactNode,
-	type ComponentType,
-	type FC,
-} from 'react';
-import { type EcoRouterOptions, DEFAULT_OPTIONS } from './types.ts';
-import { RouterContext } from './context.ts';
-import { type PageState, getInterceptDecision, loadPageModule, shouldInterceptClick } from './navigation.ts';
-import { morphHead } from './head-morpher.ts';
-import { applyViewTransitionNames } from './view-transition-utils.ts';
-import { manageScroll } from './manage-scroll.ts';
-import { saveScrollPositions, restoreScrollPositions } from './scroll-persist.ts';
-import type { EcoInjectedMeta } from '@ecopages/core';
-
-type PageContextValue = PageState | null;
-
-const PageContext = createContext<PageContextValue>(null);
-
-const PersistLayoutsContext = createContext<boolean>(false);
-
-function getLayoutFromPage(Page: ComponentType<unknown>): ComponentType | undefined {
-	const config = (Page as ComponentType & { config?: { layout?: ComponentType } }).config;
-	return config?.layout;
-}
-
-/**
- * Props for the {@link EcoRouter} component.
- */
-export interface EcoRouterProps {
-	/** Page component to render */
-	page: ComponentType<unknown>;
-	/** Props passed to the page component */
-	pageProps: Record<string, unknown>;
-	/** Router configuration */
-	options?: EcoRouterOptions;
-	/** Children (should contain {@link PageContent}) */
-	children: ReactNode;
-}
-
-/**
- * Cache for layout components to ensure same reference across navigations.
- * When different pages import the same layout, they get different function
- * references. This cache ensures we reuse the first one seen for each displayName.
- *
- * Stored on window to persist across module reloads during HMR/SPA navigation.
- */
-function getLayoutCache(): Map<string, ComponentType> {
-	if (typeof window === 'undefined') {
-		return new Map();
-	}
-	const win = window as typeof window & { __ecoLayoutCache?: Map<string, ComponentType> };
-	if (!win.__ecoLayoutCache) {
-		win.__ecoLayoutCache = new Map();
-	}
-	return win.__ecoLayoutCache;
-}
-
-function normalizeLayoutKey(value: string): string {
-	const trimmed = value.trim();
-	if (!trimmed) return 'layout';
-
-	try {
-		const asUrl = new URL(trimmed);
-		return asUrl.pathname.replace(/\/$/, '') || 'layout';
-	} catch {
-		return trimmed.split('#')[0]?.split('?')[0]?.replace(/\/$/, '') || 'layout';
-	}
-}
-
-/**
- * Clears the layout cache. Called during HMR to ensure fresh layouts are used.
- */
-export function clearLayoutCache(): void {
-	getLayoutCache().clear();
-}
-
-/**
- * Renders the current page with its layout.
- *
- * Must be a child of {@link EcoRouter}. When `persistLayouts` is enabled,
- * shared layouts remain mounted across navigations.
- *
- * @example
- * ```tsx
- * <EcoRouter page={Page} pageProps={props}>
- *   <PageContent />
- * </EcoRouter>
- * ```
- */
-export const PageContent: FC = () => {
-	const pageContext = useContext(PageContext);
-	const persistLayouts = useContext(PersistLayoutsContext);
-
-	if (!pageContext) {
-		if (import.meta.env.NODE_ENV !== 'production') {
-			console.warn('[EcoRouter] PageContent used outside of EcoRouter');
-		}
-		return null;
-	}
-
-	const { Component: Page, props } = pageContext;
-	const Layout = getLayoutFromPage(Page);
-	const pageElement = createElement(Page, props);
-
-	if (!Layout) {
-		return pageElement;
-	}
-
-	if (persistLayouts) {
-		const layoutCache = getLayoutCache();
-		const layoutConfig = (Layout as ComponentType & { config?: { __eco?: EcoInjectedMeta } }).config;
-		const layoutKeyRaw = layoutConfig?.__eco?.id || Layout.displayName || Layout.name || 'layout';
-		const layoutKey = normalizeLayoutKey(layoutKeyRaw);
-
-		if (!layoutCache.has(layoutKey)) {
-			layoutCache.set(layoutKey, Layout);
-		}
-		const CachedLayout = layoutCache.get(layoutKey)!;
-
-		return createElement(CachedLayout, { key: layoutKey }, pageElement);
-	}
-
-	return createElement(Layout, null, pageElement);
-};
-
-function createDeferred<T>() {
-	let resolve!: (value: T) => void;
-	const promise = new Promise<T>((res) => {
-		resolve = res;
-	});
-	return { promise, resolve };
-}
-
-function useHmrReload(navigate: (url: string) => Promise<void>) {
-	useEffect(() => {
-		if (typeof window === 'undefined') return;
-		if (import.meta.env?.MODE === 'production' || import.meta.env?.PROD) return;
-
-		const windowWithHmr = window as typeof window & {
-			__ecopages_reload_current_page__?: (options?: { clearCache?: boolean }) => Promise<void>;
-		};
-
-		windowWithHmr.__ecopages_reload_current_page__ = async (options?: { clearCache?: boolean }) => {
-			if (options?.clearCache) {
-				clearLayoutCache();
-			}
-			const currentUrl = window.location.pathname + window.location.search;
-			await navigate(currentUrl);
-		};
-
-		return () => {
-			windowWithHmr.__ecopages_reload_current_page__ = undefined;
-		};
-	}, [navigate]);
-}
-
-/**
- * Root router providing SPA navigation with View Transitions.
- *
- * Coordinates navigation flow:
- * 1. Intercepts link clicks and popstate events
- * 2. Loads page module and updates document head
- * 3. Triggers View Transition (if supported)
- * 4. Updates React state inside transition callback
- * 5. Resolves deferred promise after render
- * 6. Browser captures new DOM snapshot
- *
- * @example
- * ```tsx
- * <EcoRouter
- *   page={CurrentPage}
- *   pageProps={pageProps}
- *   options={{ persistLayouts: true }}
- * >
- *   <PageContent />
- * </EcoRouter>
- * ```
- *
- * @example Shared element transitions
- * ```tsx
- * // List page
- * <img data-view-transition={`hero-${id}`} src={src} />
- *
- * // Detail page
- * <img data-view-transition={`hero-${id}`} src={src} />
- * ```
- */
-export const EcoRouter: FC<EcoRouterProps> = ({ page, pageProps, options: userOptions, children }: EcoRouterProps) => {
-	const options = useMemo(() => ({ ...DEFAULT_OPTIONS, ...userOptions }), [userOptions]);
-	const [currentPage, setCurrentPage] = useState<PageState>({ Component: page, props: pageProps });
-	const [isNavigating, setIsNavigating] = useState(false);
-	const [pendingPage, setPendingPage] = useState<PageState | null>(null);
-	const renderDfd = useRef<{ promise: Promise<void>; resolve: () => void } | null>(null);
-	const pendingScrollRestoreRef = useRef<{ url: string; isPopState: boolean } | null>(null);
-	const previousUrlRef = useRef<string>(typeof window !== 'undefined' ? window.location.href : '');
-
-	useEffect(() => {
-		setCurrentPage({ Component: page, props: pageProps });
-	}, [page, pageProps]);
-
-	useEffect(() => {
-		applyViewTransitionNames();
-	}, [currentPage]);
-
-	useEffect(() => {
-		if (pendingPage && currentPage.Component === pendingPage.Component && renderDfd.current) {
-			renderDfd.current.resolve();
-			renderDfd.current = null;
-			setPendingPage(null);
-		}
-	}, [currentPage, pendingPage]);
-
-	useEffect(() => {
-		if (typeof window === 'undefined') return;
-
-		const url = new URL(window.location.href);
-		const previousUrl = new URL(previousUrlRef.current);
-
-		if (url.href !== previousUrl.href) {
-			manageScroll(url, previousUrl, {
-				scrollBehavior: options.scrollBehavior,
-				smoothScroll: options.smoothScroll,
-			});
-			previousUrlRef.current = url.href;
-		}
-
-		if (pendingScrollRestoreRef.current) {
-			const { url: targetUrl, isPopState } = pendingScrollRestoreRef.current;
-			restoreScrollPositions(targetUrl, isPopState);
-			pendingScrollRestoreRef.current = null;
-		}
-	}, [currentPage, options.scrollBehavior, options.smoothScroll]);
-
-	const navigate = useCallback(
-		async (url: string, isPopState = false) => {
-			setIsNavigating(true);
-			const result = await loadPageModule(url);
-
-			if (result) {
-				const { Component, props, doc, finalPath } = result;
-				const nextPage = { Component, props };
-				const cleanupHead = await morphHead(doc);
-				applyViewTransitionNames();
-
-				if (finalPath !== url) {
-					window.history.replaceState(null, '', finalPath);
-				}
-
-				saveScrollPositions();
-				pendingScrollRestoreRef.current = { url, isPopState };
-
-				if (options.viewTransitions && document.startViewTransition) {
-					renderDfd.current = createDeferred<void>();
-					setPendingPage(nextPage);
-
-					document.startViewTransition(async () => {
-						startTransition(() => {
-							setCurrentPage(nextPage);
-						});
-						await renderDfd.current?.promise;
-						cleanupHead();
-						applyViewTransitionNames();
-					});
-				} else {
-					setCurrentPage(nextPage);
-					cleanupHead();
-					applyViewTransitionNames();
-				}
-			} else {
-				if (options.debug) {
-					console.error('[EcoRouter] Falling back to full page navigation:', url);
-				}
-				window.location.href = url;
-			}
-			setIsNavigating(false);
-		},
-		[options.viewTransitions, options.debug],
-	);
-
-	useEffect(() => {
-		const handleClick = (event: MouseEvent) => {
-			const link = (event.target as Element).closest(options.linkSelector) as HTMLAnchorElement | null;
-			if (!link) return;
-			if (!shouldInterceptClick(event, link, options)) {
-				if (options.debug) {
-					const decision = getInterceptDecision(event, link, options);
-					if (!decision.shouldIntercept) {
-						console.debug('[EcoRouter] Not intercepting link click:', decision.reason, link.href);
-					}
-				}
-				return;
-			}
-
-			event.preventDefault();
-			const href = link.getAttribute('href')!;
-			const url = new URL(href, window.location.origin);
-
-			if (options.debug) {
-				console.debug('[EcoRouter] Intercepting navigation:', url.pathname + url.search);
-			}
-
-			window.history.pushState(null, '', url.href);
-			navigate(url.pathname + url.search);
-		};
-
-		const handlePopState = () => {
-			navigate(window.location.pathname + window.location.search, true);
-		};
-
-		document.addEventListener('click', handleClick);
-		window.addEventListener('popstate', handlePopState);
-
-		return () => {
-			document.removeEventListener('click', handleClick);
-			window.removeEventListener('popstate', handlePopState);
-		};
-	}, [navigate, options]);
-
-	useHmrReload(navigate);
-
-	return createElement(
-		RouterContext.Provider,
-		{ value: { navigate, isNavigating } },
-		createElement(
-			PersistLayoutsContext.Provider,
-			{ value: options.persistLayouts },
-			createElement(PageContext.Provider, { value: currentPage }, children),
-		),
-	);
-};

package/src/scroll-persist.ts

@@ -1,96 +0,0 @@
-/**
- * Scroll position persistence for elements marked with `data-eco-persist="scroll"`.
- *
- * Handles two navigation scenarios:
- * - **Forward navigation**: Preserves current scroll positions for shared layout elements
- * - **Back navigation**: Restores positions from when the page was last visited
- *
- * @module scroll-persist
- */
-
-const PERSIST_SELECTOR = '[data-eco-persist="scroll"]';
-
-type ScrollPosition = { top: number; left: number };
-type ScrollMap = Map<string, ScrollPosition>;
-type UrlScrollStore = Map<string, ScrollMap>;
-
-const urlScrollStore: UrlScrollStore = new Map();
-let currentScrollSnapshot: ScrollMap | null = null;
-
-function getElementKey(el: Element): string | null {
-	return el.id || el.getAttribute('data-testid') || null;
-}
-
-function captureScrollPositions(): ScrollMap {
-	const positions = new Map<string, ScrollPosition>();
-	document.querySelectorAll(PERSIST_SELECTOR).forEach((el) => {
-		const key = getElementKey(el);
-		if (key) {
-			positions.set(key, { top: el.scrollTop, left: el.scrollLeft });
-		}
-	});
-	return positions;
-}
-
-/**
- * Captures and stores scroll positions before navigation.
- *
- * Saves positions to both:
- * - URL-keyed store (for back navigation restoration)
- * - Current snapshot (for forward navigation preservation)
- */
-export function saveScrollPositions(): void {
-	const url = `${window.location.pathname}${window.location.search}`;
-	const positions = captureScrollPositions();
-
-	if (positions.size > 0) {
-		urlScrollStore.set(url, positions);
-	}
-	currentScrollSnapshot = positions;
-}
-
-/**
- * Restores scroll positions after React render completes.
- *
- * Uses double `requestAnimationFrame` to ensure DOM is fully painted.
- *
- * @param targetUrl - The URL being navigated to
- * @param isPopState - True for back/forward navigation, false for link clicks
- */
-export function restoreScrollPositions(targetUrl: string, isPopState: boolean): void {
-	const positions = isPopState ? urlScrollStore.get(targetUrl) : currentScrollSnapshot;
-
-	if (!positions || positions.size === 0) {
-		currentScrollSnapshot = null;
-		return;
-	}
-
-	requestAnimationFrame(() => {
-		requestAnimationFrame(() => {
-			document.querySelectorAll(PERSIST_SELECTOR).forEach((el) => {
-				const key = getElementKey(el);
-				if (key && positions.has(key)) {
-					const pos = positions.get(key)!;
-					el.scrollTop = pos.top;
-					el.scrollLeft = pos.left;
-				}
-			});
-			currentScrollSnapshot = null;
-		});
-	});
-}
-
-/**
- * Returns stored scroll positions for a URL without applying them.
- */
-export function getScrollPositions(url: string): ScrollMap | undefined {
-	return urlScrollStore.get(url);
-}
-
-/**
- * Clears all stored scroll positions.
- */
-export function clearScrollPositions(): void {
-	urlScrollStore.clear();
-	currentScrollSnapshot = null;
-}

package/src/types.ts

@@ -1,64 +0,0 @@
-/**
- * Configuration options for the EcoRouter
- */
-export interface EcoRouterOptions {
-	/**
-	 * CSS selector for links to intercept
-	 * @default 'a[href]'
-	 */
-	linkSelector?: string;
-
-	/**
-	 * Attribute that forces a full page reload when present on a link
-	 * @default 'data-eco-reload'
-	 */
-	reloadAttribute?: string;
-
-	/**
-	 * Whether to use the View Transitions API for page animations.
-	 * When enabled and supported, page transitions animate using CSS view-transition pseudo-elements.
-	 * Falls back to instant swap if not supported by the browser.
-	 * @default true
-	 */
-	viewTransitions?: boolean;
-
-	/**
-	 * Enable debug logging to console
-	 * @default false
-	 */
-	debug?: boolean;
-
-	/**
-	 * Scroll behavior after navigation:
-	 * - 'top': Always scroll to top (default)
-	 * - 'preserve': Keep current scroll position
-	 * - 'auto': Scroll to top only when pathname changes
-	 */
-	scrollBehavior?: 'top' | 'preserve' | 'auto';
-
-	/**
-	 * Whether to use smooth scrolling during navigation.
-	 * If true, uses 'smooth' behavior. If false, uses 'instant' behavior.
-	 * @default false
-	 */
-	smoothScroll?: boolean;
-
-	/**
-	 * Keep layouts mounted between navigations.
-	 * When enabled, if consecutive pages share the same layout component,
-	 * the layout stays mounted and only the page content re-renders.
-	 * This preserves layout state including scroll positions.
-	 * @default true
-	 */
-	persistLayouts?: boolean;
-}
-
-export const DEFAULT_OPTIONS: Required<EcoRouterOptions> = {
-	linkSelector: 'a[href]',
-	reloadAttribute: 'data-eco-reload',
-	viewTransitions: true,
-	debug: false,
-	scrollBehavior: 'top',
-	smoothScroll: false,
-	persistLayouts: true,
-};

package/src/view-transition-manager.ts

@@ -1,30 +0,0 @@
-/**
- * Manages View Transition API integration
- * @module
- */
-
-type ViewTransitionDocument = Document & {
-	startViewTransition: (callback: () => void | Promise<void>) => {
-		finished: Promise<void>;
-		ready: Promise<void>;
-		updateCallbackDone: Promise<void>;
-		skipTransition(): void;
-	};
-};
-
-function isViewTransitionSupported(): boolean {
-	return 'startViewTransition' in document;
-}
-
-export async function withViewTransition(callback: () => void): Promise<void> {
-	if (!isViewTransitionSupported()) {
-		callback();
-		return;
-	}
-
-	const transition = (document as ViewTransitionDocument).startViewTransition(() => {
-		callback();
-	});
-
-	await transition.finished;
-}

package/src/view-transition-utils.ts

@@ -1,95 +0,0 @@
-/**
- * View transition utilities for applying transition names from data attributes.
- * @module
- */
-
-const VIEW_TRANSITION_ATTR = 'data-view-transition';
-const VIEW_TRANSITION_ANIMATE_ATTR = 'data-view-transition-animate';
-const VIEW_TRANSITION_DURATION_ATTR = 'data-view-transition-duration';
-
-/**
- * Applies view-transition-name CSS property to elements with data-view-transition attribute.
- * Also handles data-view-transition-animate="morph" (default) logic and custom duration.
- */
-export function applyViewTransitionNames(): void {
-	const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
-	const morphNames: string[] = [];
-	const customDurations: { name: string; duration: string }[] = [];
-
-	elements.forEach((el) => {
-		const name = el.getAttribute(VIEW_TRANSITION_ATTR);
-		if (name) {
-			(el as HTMLElement).style.viewTransitionName = name;
-			/**
-			 * By default, we apply a clean geometric morph (no cross-fade/ghosting).
-			 * The 'fade' value is reserved for opting out of this behavior.
-			 */
-			const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
-			if (animate !== 'fade') {
-				morphNames.push(name);
-			}
-
-			const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
-			if (duration) {
-				customDurations.push({ name, duration });
-			}
-		}
-	});
-
-	if (morphNames.length > 0 || customDurations.length > 0) {
-		injectDynamicStyles(morphNames, customDurations);
-	}
-}
-
-/**
- * Injects dynamic CSS to hide old snapshots and apply custom durations.
- */
-function injectDynamicStyles(morphNames: string[], customDurations: { name: string; duration: string }[]) {
-	let styleEl = document.getElementById('eco-vt-dynamic-styles');
-	if (!styleEl) {
-		styleEl = document.createElement('style');
-		styleEl.id = 'eco-vt-dynamic-styles';
-		/**
-		 * Persistence is required to prevent the head-morpher from removing this style tag during navigation.
-		 */
-		styleEl.setAttribute('data-eco-persist', '');
-		document.head.appendChild(styleEl);
-	}
-
-	const morphCss = morphNames
-		.map(
-			(name) => `
-		::view-transition-old(${name}) { display: none !important; }
-		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
-	`,
-		)
-		.join('\n');
-
-	const durationCss = customDurations
-		.map(
-			({ name, duration }) => `
-		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
-	`,
-		)
-		.join('\n');
-
-	styleEl.textContent = morphCss + '\n' + durationCss;
-}
-
-/**
- * Clears view-transition-name CSS property from all elements.
- */
-export function clearViewTransitionNames(): void {
-	const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
-	elements.forEach((el) => {
-		(el as HTMLElement).style.viewTransitionName = '';
-	});
-
-	/**
-	 * Cleanup dynamic styles to ensure a clean slate for the next transition.
-	 */
-	const styleEl = document.getElementById('eco-vt-dynamic-styles');
-	if (styleEl) {
-		styleEl.textContent = '';
-	}
-}