@ecopages/react-router 0.2.0-alpha.1

package/src/navigation.ts

@@ -0,0 +1,247 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,11 @@
+import { 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 declare const EcoPropsScript: FC<EcoPropsScriptProps>;

package/src/props-script.js

@@ -0,0 +1,11 @@
+import { createElement } from "react";
+const EcoPropsScript = ({ data }) => {
+  return createElement("script", {
+    id: "__ECO_PAGE_DATA__",
+    type: "application/json",
+    dangerouslySetInnerHTML: { __html: JSON.stringify(data || {}) }
+  });
+};
+export {
+  EcoPropsScript
+};

package/src/props-script.ts

@@ -0,0 +1,19 @@
+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 || {}) },
+	});
+};

package/src/router.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 { type ReactNode, type ComponentType, type FC } from 'react';
+import { type EcoRouterOptions } from './types.js';
+/**
+ * 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;
+}
+/**
+ * Clears the layout cache. Called during HMR to ensure fresh layouts are used.
+ */
+export declare function clearLayoutCache(): void;
+/**
+ * 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 declare const PageContent: FC;
+/**
+ * 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 declare const EcoRouter: FC<EcoRouterProps>;

package/src/router.js

@@ -0,0 +1,225 @@
+import {
+  useEffect,
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+  createContext,
+  useContext,
+  startTransition,
+  createElement
+} from "react";
+import { DEFAULT_OPTIONS } from "./types.js";
+import { RouterContext } from "./context.js";
+import { getInterceptDecision, loadPageModule, shouldInterceptClick } from "./navigation.js";
+import { morphHead } from "./head-morpher.js";
+import { applyViewTransitionNames } from "./view-transition-utils.js";
+import { manageScroll } from "./manage-scroll.js";
+import { saveScrollPositions, restoreScrollPositions } from "./scroll-persist.js";
+const PageContext = createContext(null);
+const PersistLayoutsContext = createContext(false);
+function getLayoutFromPage(Page) {
+  const config = Page.config;
+  return config?.layout;
+}
+function getLayoutCache() {
+  if (typeof window === "undefined") {
+    return /* @__PURE__ */ new Map();
+  }
+  const win = window;
+  if (!win.__ecoLayoutCache) {
+    win.__ecoLayoutCache = /* @__PURE__ */ new Map();
+  }
+  return win.__ecoLayoutCache;
+}
+function normalizeLayoutKey(value) {
+  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";
+  }
+}
+function clearLayoutCache() {
+  getLayoutCache().clear();
+}
+const PageContent = () => {
+  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.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() {
+  let resolve;
+  const promise = new Promise((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+function useHmrReload(navigate) {
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    if (import.meta.env?.MODE === "production" || import.meta.env?.PROD) return;
+    const windowWithHmr = window;
+    windowWithHmr.__ecopages_reload_current_page__ = async (options) => {
+      if (options?.clearCache) {
+        clearLayoutCache();
+      }
+      const currentUrl = window.location.pathname + window.location.search;
+      await navigate(currentUrl);
+    };
+    return () => {
+      windowWithHmr.__ecopages_reload_current_page__ = void 0;
+    };
+  }, [navigate]);
+}
+const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
+  const options = useMemo(() => ({ ...DEFAULT_OPTIONS, ...userOptions }), [userOptions]);
+  const [currentPage, setCurrentPage] = useState({ Component: page, props: pageProps });
+  const [isNavigating, setIsNavigating] = useState(false);
+  const [pendingPage, setPendingPage] = useState(null);
+  const renderDfd = useRef(null);
+  const pendingScrollRestoreRef = useRef(null);
+  const previousUrlRef = useRef(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, 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();
+          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) => {
+      const link = event.target.closest(options.linkSelector);
+      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)
+    )
+  );
+};
+export {
+  EcoRouter,
+  PageContent,
+  clearLayoutCache
+};