@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

package/src/eco/eco.ts

@@ -0,0 +1,262 @@
+/**
+ * The eco namespace - unified component and page factory API
+ * @module
+ */
+
+import type {
+	EcoComponent,
+	EcoHtmlComponent,
+	EcoLayoutComponent,
+	EcoPagesElement,
+	EcoPageComponent,
+	FileRouteMiddleware,
+	GetMetadata,
+	GetStaticPaths,
+	GetStaticProps,
+	RequestLocals,
+	RequestPageContext,
+} from '../types/public-types.ts';
+import type { CacheStrategy } from '../services/cache/cache.types.ts';
+import type {
+	ComponentOptions,
+	Eco,
+	HtmlOptions,
+	LayoutOptions,
+	PageOptions,
+	PageOptionsBase,
+	PagePropsFor,
+	PagePropsForWithLocals,
+	PageRequires,
+} from './eco.types.ts';
+import {
+	finalizeComponentRender,
+	getComponentRenderContext,
+	interceptForeignChild,
+} from '../route-renderer/orchestration/component-render-context.ts';
+import { isThenable } from '../route-renderer/orchestration/render-output.utils.ts';
+
+/**
+ * Creates a component factory with lazy-trigger support and foreign-child-runtime
+ * interception.
+ *
+ * Behavior:
+ * - In normal render flow, returns `options.render(props)` with optional lazy
+ *   trigger/script wrapping.
+ * - When rendering under an active foreign-child runtime and the current
+ *   renderer-owned foreign-child runtime resolves the foreign child immediately, returns
+ *   that resolved output instead of rendering the component inline.
+ *
+ * @param options Component options for rendering and dependency declaration.
+ * @returns Configured eco component.
+ */
+function createComponentFactory<P, E>(options: ComponentOptions<P, E>): EcoComponent<P, E> {
+	const integrationName = options.integration ?? options.__eco?.integration;
+	const comp: EcoComponent<P, E> = ((props: P) => {
+		const componentProps = (props ?? {}) as Record<string, unknown>;
+		const renderInline = (nextProps: P = props) => finalizeComponentRender(comp, options.render(nextProps)) as E;
+		const activeRenderContext = getComponentRenderContext();
+		const foreignChildRender = interceptForeignChild({
+			component: comp,
+			props: componentProps,
+			targetIntegration: integrationName,
+		});
+
+		if (isThenable<unknown | undefined>(foreignChildRender)) {
+			return foreignChildRender.then((resolvedForeignChildRender) => {
+				if (resolvedForeignChildRender?.kind === 'resolved') {
+					return resolvedForeignChildRender.value as E;
+				}
+
+				return renderInline((resolvedForeignChildRender?.props ?? props) as P);
+			}) as E;
+		}
+
+		if (foreignChildRender?.kind === 'resolved') {
+			return foreignChildRender.value as E;
+		}
+
+		if (foreignChildRender?.kind === 'inline') {
+			return renderInline((foreignChildRender.props ?? props) as P);
+		}
+
+		if (
+			activeRenderContext &&
+			activeRenderContext.foreignChildRuntime &&
+			integrationName &&
+			integrationName !== activeRenderContext.currentIntegration
+		) {
+			throw new Error(
+				`[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.__eco?.file ?? 'unknown component'}.`,
+			);
+		}
+
+		return renderInline();
+	}) as EcoComponent<P, E>;
+
+	comp.config = {
+		__eco: options.__eco,
+		integration: options.integration,
+		dependencies: options.dependencies,
+	};
+
+	return comp;
+}
+
+/**
+ * Creates a reusable component with optional dependencies.
+ *
+ * @param options Component definition options.
+ * @returns Eco component function.
+ */
+function component<P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>): EcoComponent<P, E> {
+	return createComponentFactory(options);
+}
+
+type CallableEcoComponent<P = Record<string, unknown>, R = unknown> = (props: P, ...args: any[]) => R;
+
+function isMissingForeignChildInterceptionError(error: unknown): error is Error {
+	return error instanceof Error && error.message.startsWith('[ecopages] Missing foreign-child interception from ');
+}
+
+function embed<P, R>(component: CallableEcoComponent<P, R>, props: P): R;
+function embed<P extends Record<string, unknown>, R>(
+	component: CallableEcoComponent<P, R>,
+	props: P,
+	children: unknown,
+): R;
+
+/**
+ * Renders a component explicitly and optionally injects `children` into the
+ * props bag before invocation.
+ */
+function embed<P extends Record<string, unknown>, R>(
+	component: CallableEcoComponent<P, R>,
+	props: P,
+	children?: unknown,
+): R {
+	const activeRenderContext = getComponentRenderContext();
+	const ecoComponent = component as unknown as EcoComponent<P, R>;
+	const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
+	const componentFile = ecoComponent.config?.__eco?.file ?? 'unknown component';
+	const nextProps = (children === undefined ? props : { ...props, children }) as P;
+
+	try {
+		return component(nextProps);
+	} catch (error) {
+		if (!isMissingForeignChildInterceptionError(error)) {
+			throw error;
+		}
+
+		throw new Error(
+			`[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? 'unknown integration'} to ${targetIntegration ?? 'unknown integration'} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`,
+		);
+	}
+}
+
+/**
+ * Creates a document shell component.
+ */
+function html<E = EcoPagesElement>(options: HtmlOptions<E>): EcoHtmlComponent<E> {
+	return createComponentFactory(options) as EcoHtmlComponent<E>;
+}
+
+/**
+ * Creates a route layout component.
+ */
+function layout<E = EcoPagesElement>(options: LayoutOptions<E>): EcoLayoutComponent<E> {
+	return createComponentFactory(options) as EcoLayoutComponent<E>;
+}
+
+/**
+ * Creates a page component with typed props and optional static helpers.
+ */
+function page<T = {}, E = EcoPagesElement>(options: PageOptions<T, E> & { requires?: undefined }): EcoPageComponent<T>;
+function page<T = {}, E = EcoPagesElement, const K extends keyof RequestLocals = keyof RequestLocals>(
+	options: Omit<PageOptions<T, E>, 'render' | 'requires'> & {
+		requires: PageRequires<K>;
+		render: (props: PagePropsForWithLocals<T, K>) => E | Promise<E>;
+	},
+): EcoPageComponent<T>;
+
+/**
+ * Creates a page component and attaches optional static APIs.
+ *
+ * @param options Page options.
+ * @returns Eco page component.
+ */
+function page<T, E>(
+	options: PageOptionsBase<T, E> & { cache?: CacheStrategy; middleware?: FileRouteMiddleware[] },
+): EcoPageComponent<T> {
+	const { layout, dependencies, render, staticPaths, staticProps, metadata, cache, requires, middleware } = options;
+
+	const componentOptions: ComponentOptions<PagePropsFor<T> & Partial<RequestPageContext>, E> = {
+		__eco: options.__eco,
+		integration: options.integration,
+		dependencies: layout
+			? {
+					...dependencies,
+					components: [...(dependencies?.components || []), layout],
+				}
+			: dependencies,
+		render,
+	};
+
+	const pageComponent = createComponentFactory(componentOptions) as EcoPageComponent<T>;
+
+	if (layout && pageComponent.config) {
+		pageComponent.config.layout = layout;
+	}
+
+	if (staticPaths) pageComponent.staticPaths = staticPaths;
+	if (staticProps) pageComponent.staticProps = staticProps;
+	if (metadata) pageComponent.metadata = metadata;
+	if (cache) pageComponent.cache = cache;
+	if (requires) pageComponent.requires = requires;
+	if (middleware) pageComponent.middleware = middleware;
+
+	return pageComponent;
+}
+
+/**
+ * Type-safe wrapper for metadata functions.
+ *
+ * @param fn Metadata factory function.
+ * @returns The same function.
+ */
+function metadata<P = {}>(fn: GetMetadata<P>): GetMetadata<P> {
+	return fn;
+}
+
+/**
+ * Type-safe wrapper for static paths functions.
+ *
+ * @param fn Static paths function.
+ * @returns The same function.
+ */
+function staticPaths(fn: GetStaticPaths): GetStaticPaths {
+	return fn;
+}
+
+/**
+ * Type-safe wrapper for static props functions.
+ *
+ * @param fn Static props function.
+ * @returns The same function.
+ */
+function staticProps<P>(fn: GetStaticProps<P>): GetStaticProps<P> {
+	return fn;
+}
+
+/**
+ * The eco namespace - provides factories for components and pages
+ */
+export const eco: Eco = {
+	component,
+	embed,
+	html,
+	layout,
+	page,
+	metadata,
+	staticPaths,
+	staticProps,
+};

package/src/eco/eco.types.ts

@@ -0,0 +1,293 @@
+/**
+ * Type definitions for the eco namespace API
+ * @module
+ */
+
+import type {
+	DependencyLazyTrigger,
+	EcoComponent,
+	EcoComponentDependencies,
+	EcoHtmlComponent,
+	EcoInjectedMeta,
+	EcoLayoutComponent,
+	EcoPageLayoutComponent,
+	EcoPagesElement,
+	FileRouteMiddleware,
+	GetMetadata,
+	GetStaticPaths,
+	GetStaticProps,
+	HtmlTemplateProps,
+	LayoutProps,
+	RequestLocals,
+	RequestPageContext,
+} from '../types/public-types.ts';
+import type { CacheStrategy } from '../services/cache/cache.types.ts';
+
+/**
+ * Extracts the props type from one eco component.
+ */
+export type PropsOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<infer P, any> ? P : never;
+
+/**
+ * Extracts the render result type from one eco component.
+ */
+export type ResultOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<any, infer R> ? R : never;
+
+/**
+ * Narrows an eco component to its callable function signature.
+ *
+ * This is useful for helper modules such as `EcoEmbed` that invoke a component
+ * directly and need to exclude the non-callable metadata shape from the public
+ * type surface.
+ */
+export type CallableComponentOf<TComponent extends EcoComponent> = Extract<
+	TComponent,
+	(props: any, ...args: any[]) => any
+>;
+
+/**
+ * Extracts the declared `children` type from one eco component when present.
+ */
+export type ChildrenOf<TComponent extends EcoComponent> =
+	PropsOf<TComponent> extends { children?: infer T }
+		? T
+		: PropsOf<TComponent> extends { children: infer T }
+			? T
+			: never;
+
+/**
+ * Extracts the props accepted by `eco.embed()` before optional `children`
+ * injection.
+ *
+ * When the target component already declares `children`, callers pass the rest
+ * of the props bag here and provide `children` as the third `eco.embed()`
+ * argument or the `EcoEmbed` wrapper children slot.
+ */
+export type EmbedPropsOf<TComponent extends EcoComponent> = 'children' extends keyof PropsOf<TComponent>
+	? Omit<PropsOf<TComponent>, 'children'>
+	: PropsOf<TComponent>;
+
+/**
+ * Props accepted by integration-owned `EcoEmbed` adapters.
+ *
+ * The `component` field is narrowed to the callable portion of the target eco
+ * component so JSX wrappers can invoke `eco.embed()` without repeating local
+ * callable-component extraction logic.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = {
+	component: CallableComponentOf<TComponent>;
+	props: EmbedPropsOf<TComponent>;
+	children?: unknown;
+};
+
+type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
+	[P in K]-?: Exclude<RequestLocals[P], null | undefined>;
+};
+
+type RequiresKeys = keyof RequestLocals;
+
+export type PageRequires<K extends RequiresKeys = RequiresKeys> = K | readonly K[];
+
+/**
+ * Lazy trigger options map directly to scripts-injector attributes.
+ * Only one trigger type can be active at a time.
+ */
+export type LazyTrigger = DependencyLazyTrigger;
+
+/**
+ * Options for creating a component with eco.component()
+ * @template P - The props type for the component
+ * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
+ */
+export interface ComponentOptions<P, E = EcoPagesElement> {
+	/** @internal Injected by eco-component-meta-plugin */
+	__eco?: EcoInjectedMeta;
+	integration?: string;
+	dependencies?: EcoComponentDependencies;
+	render: (props: P) => E | Promise<E>;
+}
+
+export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
+
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+
+/**
+ * Base options shared by all page variants
+ */
+export interface PageOptionsBase<T, E = EcoPagesElement> {
+	/** @internal Injected by eco-component-meta-plugin */
+	__eco?: EcoInjectedMeta;
+	integration?: string;
+	dependencies?: EcoComponentDependencies;
+	layout?: EcoPageLayoutComponent<E>;
+
+	/**
+	 * Define static paths for dynamic routes (e.g., [slug].tsx).
+	 * Returns all possible paths that should be pre-rendered at build time.
+	 */
+	staticPaths?: GetStaticPaths;
+
+	/**
+	 * Fetch data for the page at build time.
+	 * Props returned here are passed to both render() and metadata().
+	 */
+	staticProps?: GetStaticProps<T>;
+
+	/**
+	 * Generate page metadata (title, description, etc.).
+	 * Receives props from staticProps if defined.
+	 */
+	metadata?: GetMetadata<T>;
+
+	/**
+	 * Declares which `locals` keys must be present for this page.
+	 *
+	 * This is a typing and documentation feature; runtime enforcement must be done via handler/page middleware.
+	 */
+	requires?: PageRequires;
+
+	render: (props: PagePropsFor<T> & Partial<RequestPageContext>) => E | Promise<E>;
+}
+
+/**
+ * Page options without middleware - allows any cache strategy
+ */
+interface PageOptionsWithoutMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
+	/**
+	 * Cache configuration for ISR (Incremental Static Regeneration).
+	 * - `'static'`: Cache indefinitely (default)
+	 * - `'dynamic'`: No caching, render on every request
+	 * - `{ revalidate: number, tags?: string[] }`: Cache with time-based revalidation
+	 */
+	cache?: CacheStrategy;
+	middleware?: undefined;
+}
+
+/**
+ * Page options with middleware - requires cache: 'dynamic'
+ */
+interface PageOptionsWithMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
+	/**
+	 * Cache must be 'dynamic' when using middleware.
+	 * Middleware runs on every request, so caching would bypass middleware effects.
+	 */
+	cache: 'dynamic';
+	/**
+	 * Request-time middleware for file-based routes.
+	 * Runs before rendering and can short-circuit by returning a Response.
+	 */
+	middleware: FileRouteMiddleware[];
+}
+
+/**
+ * Options for creating a page with eco.page()
+ *
+ * Define staticPaths, staticProps, and metadata inline. When using
+ * `middleware`, `cache` must be set to `'dynamic'` because middleware
+ * runs on every request and caching would bypass middleware effects.
+ *
+ * @template T - The props type for the page
+ * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
+ */
+export type PageOptions<T, E = EcoPagesElement> = PageOptionsWithoutMiddleware<T, E> | PageOptionsWithMiddleware<T, E>;
+
+export type PagePropsForWithLocals<T, K extends RequiresKeys | never = never> = PagePropsFor<T> &
+	(K extends never
+		? Partial<RequestPageContext>
+		: Omit<Partial<RequestPageContext>, 'locals'> & {
+				locals: WithRequiredLocals<Extract<K, keyof RequestLocals>>;
+			});
+
+/**
+ * Extracts props type from getStaticProps return type, or uses T directly if it's a props object.
+ * Always includes params and query for page context.
+ */
+export type PagePropsFor<T> =
+	T extends GetStaticProps<infer P>
+		? P & { params?: Record<string, string>; query?: Record<string, string> }
+		: T & { params?: Record<string, string>; query?: Record<string, string> };
+
+/**
+ * A page component with optional attached static functions.
+ * Used by the consolidated eco.page() API where staticPaths, staticProps,
+ * and metadata are defined inline and attached to the component.
+ */
+export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<RequestPageContext>> & {
+	staticPaths?: GetStaticPaths;
+	staticProps?: GetStaticProps<T>;
+	metadata?: GetMetadata<T>;
+	cache?: CacheStrategy;
+	requires?: PageRequires;
+	middleware?: FileRouteMiddleware[];
+};
+
+/**
+ * The eco namespace interface
+ */
+export interface Eco {
+	/**
+	 * Create a reusable component with dependencies and optional lazy-loading.
+	 * @template P - Props type
+	 * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
+	 */
+	component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+
+	/**
+	 * Render a component explicitly, with an optional `children` argument.
+	 *
+	 * This is useful when authoring crosses integration boundaries and inline JSX
+	 * would otherwise force one file to model multiple JSX namespaces.
+	 */
+	embed: {
+		<TComponent extends EcoComponent>(
+			component: CallableComponentOf<TComponent>,
+			props: PropsOf<TComponent>,
+		): ResultOf<TComponent>;
+		<TComponent extends EcoComponent>(
+			component: CallableComponentOf<TComponent>,
+			props: EmbedPropsOf<TComponent>,
+			children: ChildrenOf<TComponent> | unknown,
+		): ResultOf<TComponent>;
+	};
+
+	/**
+	 * Create a document shell component for the HTML wrapper.
+	 */
+	html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
+
+	/**
+	 * Create a route layout component.
+	 */
+	layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
+
+	/**
+	 * Create a page component with type-safe props from getStaticProps.
+	 * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.
+	 *
+	 * If `requires` is provided, the `render` callback receives `locals` as required and non-null for the required keys.
+	 */
+	page: {
+		<T = {}, E = EcoPagesElement>(options: PageOptions<T, E> & { requires?: undefined }): EcoPageComponent<T>;
+		<T = {}, E = EcoPagesElement, const K extends RequiresKeys = RequiresKeys>(
+			options: Omit<PageOptions<T, E>, 'render' | 'requires'> & {
+				requires: PageRequires<K>;
+				render: (props: PagePropsForWithLocals<T, K>) => E | Promise<E>;
+			},
+		): EcoPageComponent<T>;
+	};
+
+	/**
+	 * Type-safe wrapper for page metadata (identity function)
+	 */
+	metadata: <P = {}>(fn: GetMetadata<P>) => GetMetadata<P>;
+
+	/**
+	 * Type-safe wrapper for static paths (identity function)
+	 */
+	staticPaths: (fn: GetStaticPaths) => GetStaticPaths;
+
+	/**
+	 * Type-safe wrapper for static props (identity function)
+	 */
+	staticProps: <P>(fn: GetStaticProps<P>) => GetStaticProps<P>;
+}