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

package/src/eco/eco.ts

@@ -1,262 +0,0 @@
-/**
- * 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

@@ -1,293 +0,0 @@
-/**
- * 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>;
-}