@ecopages/react 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/utils/client-only.ts

@@ -1,27 +0,0 @@
-import type { ReactNode } from 'react';
-import { useEffect, useState } from 'react';
-
-type ClientOnlyProps = {
-	children: ReactNode;
-	fallback?: ReactNode;
-};
-
-export const useIsClient = (): boolean => {
-	const [isClient, setIsClient] = useState(false);
-
-	useEffect(() => {
-		setIsClient(true);
-	}, []);
-
-	return isClient;
-};
-
-export const ClientOnly = ({ children, fallback = null }: ClientOnlyProps): ReactNode => {
-	const isClient = useIsClient();
-
-	if (!isClient) {
-		return fallback;
-	}
-
-	return children;
-};

package/src/utils/declared-modules.ts

@@ -1,99 +0,0 @@
-/**
- * Shared utilities for collecting declared module sources from component configs.
- * Used by both the production ReactRenderer and the HMR strategy to ensure
- * the client-graph-boundary plugin receives a consistent set of allowed modules.
- *
- * @module
- */
-
-import type { EcoComponentConfig } from '@ecopages/core';
-
-type PageConfigModule = {
-	default?: { config?: EcoComponentConfig };
-	config?: EcoComponentConfig;
-};
-
-/**
- * Extracts the module source (package name) from a declared module string,
- * stripping any `{namedImport,...}` grammar.
- *
- * @example
- * parseDeclaredModuleSource('@ecopages/image-processor/component/react{EcoImage}')
- * // → '@ecopages/image-processor/component/react'
- */
-export function parseDeclaredModuleSource(value: string): string | undefined {
-	const source = value.trim();
-	if (source.length === 0) return undefined;
-	const openBraceIndex = source.indexOf('{');
-	if (openBraceIndex < 0) return source;
-	const from = source.slice(0, openBraceIndex).trim();
-	return from.length > 0 ? from : undefined;
-}
-
-/**
- * Normalizes an array of declared module strings into unique source paths.
- */
-export function normalizeDeclaredModuleSources(modules?: string[]): string[] {
-	const seen = new Set<string>();
-	for (const declaration of modules ?? []) {
-		const from = parseDeclaredModuleSource(declaration);
-		if (from) {
-			seen.add(from);
-		}
-	}
-	return Array.from(seen);
-}
-
-/**
- * Recursively walks a component config tree (including layouts and nested
- * `dependencies.components`) to collect all declared module sources.
- */
-export function collectDeclaredModulesInConfig(
-	config: EcoComponentConfig | undefined,
-	visited = new Set<EcoComponentConfig>(),
-): string[] {
-	if (!config || visited.has(config)) {
-		return [];
-	}
-
-	visited.add(config);
-
-	const declarations = normalizeDeclaredModuleSources(config.dependencies?.modules);
-
-	if (config.layout?.config) {
-		declarations.push(...collectDeclaredModulesInConfig(config.layout.config, visited));
-	}
-
-	for (const component of config.dependencies?.components ?? []) {
-		if (component.config) {
-			declarations.push(...collectDeclaredModulesInConfig(component.config, visited));
-		}
-	}
-
-	return declarations;
-}
-
-/**
- * Collects declared module sources from an already imported page module.
- */
-export function collectPageDeclaredModulesFromModule(pageModule: PageConfigModule): string[] {
-	const declarations = [
-		...collectDeclaredModulesInConfig(pageModule.default?.config),
-		...collectDeclaredModulesInConfig(pageModule.config),
-	];
-
-	return Array.from(new Set(declarations));
-}
-
-/**
- * Imports a page entrypoint and collects all transitively declared module sources
- * from its config, layout config, and nested component configs.
- */
-export async function collectPageDeclaredModules(pagePath: string): Promise<string[]> {
-	try {
-		const pageModule = (await import(pagePath)) as PageConfigModule;
-		return collectPageDeclaredModulesFromModule(pageModule);
-	} catch {
-		return [];
-	}
-}

package/src/utils/dynamic.ts

@@ -1,27 +0,0 @@
-import { type ComponentType, type LazyExoticComponent, lazy } from 'react';
-
-/**
- * Dynamically loads a React component with optional SSR support.
- *
- * @param importFn - Function returning a promise that resolves to a React component.
- * @param options - Options for SSR behavior.
- * @returns Lazy loaded component or a null fallback for non-client environments.
- */
-type DynamicLoaderOptions = {
-	ssr?: boolean;
-};
-
-const NullComponent: ComponentType = () => null;
-
-export function dynamic(
-	importFn: () => Promise<{ default: ComponentType<any> }>,
-	options: DynamicLoaderOptions = {},
-): LazyExoticComponent<ComponentType<any>> | ComponentType {
-	const { ssr = false } = options;
-
-	if (ssr || typeof window !== 'undefined') {
-		return lazy(importFn);
-	}
-
-	return NullComponent;
-}

package/src/utils/hmr-scripts.ts

@@ -1,47 +0,0 @@
-/**
- * HMR script utilities for React components.
- * @module
- */
-
-/** Marker comment to identify already-processed HMR code */
-const HMR_MARKER = '/* [ecopages] react-hmr */';
-
-/**
- * Checks if code has already been processed with HMR marker.
- * @param code - The bundled code to check
- * @returns True if the code already contains the HMR marker
- */
-export function hasHmrMarker(code: string): boolean {
-	return code.includes(HMR_MARKER);
-}
-
-/**
- * Injects HMR acceptance handler into bundled code.
- * When a module with React exports changes, it triggers a full invalidation
- * to ensure the parent module re-imports and re-renders with the updated component.
- * @param code - The bundled code to wrap
- * @returns Code with HMR handler injected
- */
-export function injectHmrHandler(code: string): string {
-	return `${HMR_MARKER}
-${code}
-if (import.meta.hot) {
-  import.meta.hot.accept((newModule) => {
-    if (newModule) {
-      const exports = Object.keys(newModule);
-      const hasReactExport = exports.some(key => {
-        const value = newModule[key];
-        return value && (
-          typeof value === 'function' ||
-          (typeof value === 'object' && value.$$typeof)
-        );
-      });
-      
-      if (hasReactExport) {
-        import.meta.hot.invalidate();
-      }
-    }
-  });
-}
-`;
-}

package/src/utils/html-boundary.ts

@@ -1,66 +0,0 @@
-const VOID_TAGS = new Set([
-	'area',
-	'base',
-	'br',
-	'col',
-	'embed',
-	'hr',
-	'img',
-	'input',
-	'link',
-	'meta',
-	'param',
-	'source',
-	'track',
-	'wbr',
-]);
-
-/**
- * Returns true when HTML contains exactly one root element node.
- *
- * Used by component-level React rendering to decide whether root attributes can
- * be attached safely without introducing synthetic wrapper nodes.
- */
-export function hasSingleRootElement(html: string): boolean {
-	const firstTagMatch = html.match(/^\s*<([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/);
-	if (!firstTagMatch) {
-		return false;
-	}
-
-	const firstTag = firstTagMatch[1].toLowerCase();
-	const firstTagText = firstTagMatch[0];
-	const firstTagStart = firstTagMatch.index ?? 0;
-	const firstTagEnd = firstTagStart + firstTagText.length;
-	const isSelfClosing = /\/\s*>$/.test(firstTagText);
-
-	if (isSelfClosing || VOID_TAGS.has(firstTag)) {
-		return html.slice(firstTagEnd).trim().length === 0;
-	}
-
-	const tokenRegex = /<\/?([a-zA-Z][a-zA-Z0-9:-]*)\b[^>]*>/g;
-	tokenRegex.lastIndex = firstTagEnd;
-	let depth = 1;
-
-	for (let token = tokenRegex.exec(html); token; token = tokenRegex.exec(html)) {
-		const tagText = token[0];
-		const tagName = token[1].toLowerCase();
-		const isClosing = tagText.startsWith('</');
-		const tokenSelfClosing = /\/\s*>$/.test(tagText);
-
-		if (VOID_TAGS.has(tagName) || tokenSelfClosing) {
-			continue;
-		}
-
-		if (isClosing) {
-			depth--;
-			if (depth === 0) {
-				const afterRoot = html.slice(token.index + token[0].length).trim();
-				return afterRoot.length === 0;
-			}
-		} else {
-			depth++;
-		}
-	}
-
-	return false;
-}

package/src/utils/hydration-scripts.ts

@@ -1,338 +0,0 @@
-/**
- * Hydration script generators for React pages.
- * These functions create the client-side scripts that hydrate React components.
- * @module
- */
-
-import type { ReactRouterAdapter } from '../router-adapter.ts';
-
-/**
- * Options for generating a hydration script.
- */
-export type HydrationScriptOptions = {
-	/** The import path for the bundled page component */
-	importPath: string;
-	/** Direct import path for React runtime module */
-	reactImportPath: string;
-	/** Direct import path for react-dom/client runtime module */
-	reactDomClientImportPath: string;
-	/** Direct import path for router runtime module */
-	routerImportPath?: string;
-	/** Whether running in development mode with HMR support */
-	isDevelopment: boolean;
-	/** Whether the source file is an MDX file */
-	isMdx: boolean;
-	/** Optional router adapter for SPA navigation */
-	router?: ReactRouterAdapter;
-};
-
-export type IslandHydrationScriptOptions = {
-	/** Bundled browser module path for the island component. */
-	importPath: string;
-	/** Browser import path for React runtime. */
-	reactImportPath: string;
-	/** Browser import path for react-dom/client runtime. */
-	reactDomClientImportPath: string;
-	/** Selector that resolves to the SSR root element for this island instance. */
-	targetSelector: string;
-	/** Serialized component props emitted at render time. */
-	props: Record<string, unknown>;
-	/** Optional stable component id used to resolve named exports reliably. */
-	componentRef?: string;
-	/** Optional source file hint used as fallback for component resolution. */
-	componentFile?: string;
-	/** Enables development-oriented non-minified output. */
-	isDevelopment: boolean;
-};
-
-/**
- * Generates the import statement for the page component.
- * MDX files use namespace imports to access the config export.
- */
-function getImportStatement(importPath: string, isMdx: boolean): string {
-	return isMdx
-		? `import * as MDXModule from "${importPath}";\nconst Page = MDXModule.default;\nif (MDXModule.config) Page.config = MDXModule.config;`
-		: `import Page from "${importPath}";`;
-}
-
-/**
- * Generates the HMR import statement for hot-reloading.
- * MDX files need to extract config from the new module.
- */
-function getHmrImportStatement(isMdx: boolean): string {
-	return isMdx
-		? 'const NewPage = newModule.default; if (newModule.config) NewPage.config = newModule.config;'
-		: 'const NewPage = newModule.default;';
-}
-
-/**
- * Returns the component type label for logging.
- */
-function getComponentType(isMdx: boolean): string {
-	return isMdx ? 'MDX' : 'React';
-}
-
-/**
- * Creates development hydration script with router support.
- * Includes HMR handlers for hot module replacement.
- * Layout is NOT applied here since PageContent handles it.
- */
-function createDevScriptWithRouter(options: HydrationScriptOptions): string {
-	const { importPath, isMdx, router, reactImportPath, reactDomClientImportPath, routerImportPath } = options;
-	const { components, getRouterProps } = router!;
-	if (!routerImportPath) {
-		throw new Error('routerImportPath is required when router adapter is configured');
-	}
-
-	return `
-import { hydrateRoot } from "${reactDomClientImportPath}";
-import { createElement } from "${reactImportPath}";
-import { ${components.router}, ${components.pageContent} } from "${routerImportPath}";
-${getImportStatement(importPath, isMdx)}
-
-window.__ecopages_hmr_handlers__ = window.__ecopages_hmr_handlers__ || {};
-window.__ecopages_router_active__ = false;
-window.__ecopages_reload_current_page__ = null;
-let root = null;
-
-const getPageData = () => {
-  const el = document.getElementById("__ECO_PAGE_DATA__");
-  if (el?.textContent) {
-    try { return JSON.parse(el.textContent); } catch {}
-  }
-  return {};
-};
-
-const props = getPageData();
-
-window.__ECO_PAGE__ = {
-  module: "${importPath}",
-  props
-};
-
-const createTree = (Component, props) => {
-  const pageContent = createElement(${components.pageContent});
-  return createElement(${components.router}, ${getRouterProps('Component', 'props')}, pageContent);
-};
-
-const mount = () => {
-  root = hydrateRoot(document, createTree(Page, props), {
-    onRecoverableError: (err) => console.warn("[ecopages] Hydration error:", err)
-  });
-  window.__ecopages_router_active__ = true;
-  window.__ecopages_hmr_handlers__["${importPath}"] = async (newUrl) => {
-    if (window.__ecopages_router_active__ && window.__ecopages_reload_current_page__) {
-      await window.__ecopages_reload_current_page__();
-      console.log("[ecopages] ${getComponentType(isMdx)} component updated via router");
-      return;
-    }
-    try {
-      const newModule = await import(newUrl);
-      ${getHmrImportStatement(isMdx)}
-      root.render(createTree(NewPage, props));
-      console.log("[ecopages] ${getComponentType(isMdx)} component updated");
-    } catch (e) {
-      console.error("[ecopages] Failed to hot-reload ${getComponentType(isMdx)} component:", e);
-    }
-  };
-};
-
-if (document.readyState === "loading") {
-  document.addEventListener("DOMContentLoaded", mount);
-} else {
-  mount();
-}
-`.trim();
-}
-
-/**
- * Creates development hydration script without router.
- * Includes HMR handlers for hot module replacement.
- */
-function createDevScriptWithoutRouter(options: HydrationScriptOptions): string {
-	const { importPath, isMdx, reactImportPath, reactDomClientImportPath } = options;
-
-	return `
-import { hydrateRoot } from "${reactDomClientImportPath}";
-import { createElement } from "${reactImportPath}";
-${getImportStatement(importPath, isMdx)}
-
-window.__ecopages_hmr_handlers__ = window.__ecopages_hmr_handlers__ || {};
-let root = null;
-
-const getPageData = () => {
-  const el = document.getElementById("__ECO_PAGE_DATA__");
-  if (el?.textContent) {
-    try { return JSON.parse(el.textContent); } catch {}
-  }
-  return {};
-};
-
-const props = getPageData();
-
-window.__ECO_PAGE__ = {
-  module: "${importPath}",
-  props
-};
-
-const createTree = (Component, props) => {
-  const Layout = Component.config?.layout;
-  const pageElement = createElement(Component, props);
-  return Layout ? createElement(Layout, null, pageElement) : pageElement;
-};
-
-const mount = () => {
-  root = hydrateRoot(document, createTree(Page, props), {
-    onRecoverableError: (err) => console.warn("[ecopages] Hydration error:", err)
-  });
-  window.__ecopages_hmr_handlers__["${importPath}"] = async (newUrl) => {
-    try {
-      const newModule = await import(newUrl);
-      ${getHmrImportStatement(isMdx)}
-      root.render(createTree(NewPage, props));
-      console.log("[ecopages] ${getComponentType(isMdx)} component updated");
-    } catch (e) {
-      console.error("[ecopages] Failed to hot-reload ${getComponentType(isMdx)} component:", e);
-    }
-  };
-};
-
-if (document.readyState === "loading") {
-  document.addEventListener("DOMContentLoaded", mount);
-} else {
-  mount();
-}
-`.trim();
-}
-
-/**
- * Creates minified production hydration script with router support.
- * Layout is NOT applied here since PageContent handles it.
- */
-function createProdScriptWithRouter(options: HydrationScriptOptions): string {
-	const { importPath, isMdx, router, reactImportPath, reactDomClientImportPath, routerImportPath } = options;
-	const { components, getRouterProps } = router!;
-	if (!routerImportPath) {
-		throw new Error('routerImportPath is required when router adapter is configured');
-	}
-
-	if (isMdx) {
-		return `import{hydrateRoot as hr}from"${reactDomClientImportPath}";import{createElement as ce}from"${reactImportPath}";import{${components.router} as R,${components.pageContent} as PC}from"${routerImportPath}";import*as M from"${importPath}";const P=M.default;if(M.config)P.config=M.config;const gd=()=>{const e=document.getElementById("__ECO_PAGE_DATA__");if(e?.textContent){try{return JSON.parse(e.textContent)}catch{}}return{}};const pr=gd();window.__ECO_PAGE__={module:"${importPath}",props:pr};const ct=(C,p)=>ce(R,${getRouterProps('C', 'p')},ce(PC));const m=()=>hr(document,ct(P,pr),{onRecoverableError:(e)=>console.warn("[ecopages] Hydration error:",e)});document.readyState==="loading"?document.addEventListener("DOMContentLoaded",m):m()`;
-	}
-
-	return `import{hydrateRoot as hr}from"${reactDomClientImportPath}";import{createElement as ce}from"${reactImportPath}";import{${components.router} as R,${components.pageContent} as PC}from"${routerImportPath}";import P from"${importPath}";const gd=()=>{const e=document.getElementById("__ECO_PAGE_DATA__");if(e?.textContent){try{return JSON.parse(e.textContent)}catch{}}return{}};const pr=gd();window.__ECO_PAGE__={module:"${importPath}",props:pr};const ct=(C,p)=>ce(R,${getRouterProps('C', 'p')},ce(PC));const m=()=>hr(document,ct(P,pr),{onRecoverableError:(e)=>console.warn("[ecopages] Hydration error:",e)});document.readyState==="loading"?document.addEventListener("DOMContentLoaded",m):m()`;
-}
-
-/**
- * Creates minified production hydration script without router.
- */
-function createProdScriptWithoutRouter(options: HydrationScriptOptions): string {
-	const { importPath, isMdx, reactImportPath, reactDomClientImportPath } = options;
-
-	if (isMdx) {
-		return `import{hydrateRoot as hr}from"${reactDomClientImportPath}";import{createElement as ce}from"${reactImportPath}";import*as M from"${importPath}";const P=M.default;if(M.config)P.config=M.config;const gd=()=>{const e=document.getElementById("__ECO_PAGE_DATA__");if(e?.textContent){try{return JSON.parse(e.textContent)}catch{}}return{}};const pr=gd();window.__ECO_PAGE__={module:"${importPath}",props:pr};const ct=(C,p)=>{const L=C.config?.layout;const pe=ce(C,p);return L?ce(L,null,pe):pe};const m=()=>hr(document,ct(P,pr),{onRecoverableError:(e)=>console.warn("[ecopages] Hydration error:",e)});document.readyState==="loading"?document.addEventListener("DOMContentLoaded",m):m()`;
-	}
-
-	return `import{hydrateRoot as hr}from"${reactDomClientImportPath}";import{createElement as ce}from"${reactImportPath}";import P from"${importPath}";const gd=()=>{const e=document.getElementById("__ECO_PAGE_DATA__");if(e?.textContent){try{return JSON.parse(e.textContent)}catch{}}return{}};const pr=gd();window.__ECO_PAGE__={module:"${importPath}",props:pr};const ct=(C,p)=>{const L=C.config?.layout;const pe=ce(C,p);return L?ce(L,null,pe):pe};const m=()=>hr(document,ct(P,pr),{onRecoverableError:(e)=>console.warn("[ecopages] Hydration error:",e)});document.readyState==="loading"?document.addEventListener("DOMContentLoaded",m):m()`;
-}
-
-/**
- * Creates a hydration script for client-side React hydration.
- * Generates appropriate script based on environment and router configuration.
- * @param options - Configuration options for script generation
- * @returns The generated hydration script as a string
- */
-export function createHydrationScript(options: HydrationScriptOptions): string {
-	const { isDevelopment, router } = options;
-
-	if (isDevelopment) {
-		return router ? createDevScriptWithRouter(options) : createDevScriptWithoutRouter(options);
-	}
-
-	return router ? createProdScriptWithRouter(options) : createProdScriptWithoutRouter(options);
-}
-
-/**
- * Creates the client bootstrap for component-level React islands.
- *
- * The island runtime intentionally uses `createRoot()` (not `hydrateRoot()`) and
- * mounts into the SSR element identified by `targetSelector`.
- *
- * Rationale:
- * - No synthetic wrapper element is introduced in SSR output.
- * - DOM structure remains identical to authored component markup.
- * - Runtime ownership is isolated per island instance.
- *
- * Generated script behavior:
- * - resolves the component export by metadata (`componentRef`, `componentFile`)
- *   before falling back to default/first function export
- * - selects island root using `targetSelector`
- * - creates a fresh React root and renders with serialized `props`
- *
- * @param options Island script generation options.
- * @returns Browser-executable JavaScript module source.
- */
-export function createIslandHydrationScript(options: IslandHydrationScriptOptions): string {
-	const targetSelector = JSON.stringify(options.targetSelector);
-	const serializedProps = JSON.stringify(options.props ?? {});
-	const componentRef = JSON.stringify(options.componentRef ?? '');
-	const componentFile = JSON.stringify(options.componentFile ?? '');
-	const mountedAttribute = 'data-eco-react-mounted';
-
-	if (options.isDevelopment) {
-		return `
-import { createRoot } from "${options.reactDomClientImportPath}";
-import { createElement } from "${options.reactImportPath}";
-import * as ComponentModule from "${options.importPath}";
-
-const resolveComponent = () => {
-  const id = ${componentRef};
-  const file = ${componentFile};
-  const moduleValues = Object.values(ComponentModule);
-
-  const matchByMetadata = moduleValues.find((entry) => {
-    if (typeof entry !== "function") return false;
-    const config = entry.config;
-    const eco = config?.__eco;
-    if (!eco) return false;
-    if (id && eco.id === id) return true;
-    if (file && eco.file === file) return true;
-    return false;
-  });
-
-  if (matchByMetadata && typeof matchByMetadata === "function") {
-    return matchByMetadata;
-  }
-
-  const defaultExport = ComponentModule.default;
-  if (typeof defaultExport === "function") {
-    return defaultExport;
-  }
-
-  const firstFunction = moduleValues.find((entry) => typeof entry === "function");
-  return typeof firstFunction === "function" ? firstFunction : null;
-};
-
-const mount = () => {
-  const target = document.querySelector(${targetSelector});
-  const Component = resolveComponent();
-  if (!target || !Component || target.hasAttribute("${mountedAttribute}")) {
-    return;
-  }
-  const props = ${serializedProps};
-  target.setAttribute("${mountedAttribute}", "true");
-  const root = createRoot(target);
-  root.render(createElement(Component, props));
-};
-
-document.addEventListener("eco:after-swap", mount);
-if (document.readyState === "loading") {
-  document.addEventListener("DOMContentLoaded", mount, { once: true });
-} else {
-  mount();
-}
-`.trim();
-	}
-
-	return `import{createRoot as cr}from"${options.reactDomClientImportPath}";import{createElement as ce}from"${options.reactImportPath}";import*as M from"${options.importPath}";const r=${componentRef};const f=${componentFile};const mv=Object.values(M);const c=mv.find((e)=>{if(typeof e!=="function")return false;const ec=e.config?.__eco;if(!ec)return false;if(r&&ec.id===r)return true;if(f&&ec.file===f)return true;return false;})??(typeof M.default==="function"?M.default:mv.find((e)=>typeof e==="function")??null);const m=()=>{const t=document.querySelector(${targetSelector});if(!t||!c||t.hasAttribute("${mountedAttribute}"))return;const p=${serializedProps};t.setAttribute("${mountedAttribute}","true");cr(t).render(ce(c,p))};document.addEventListener("eco:after-swap",m);document.readyState==="loading"?document.addEventListener("DOMContentLoaded",m,{once:true}):m()`;
-}