@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

package/src/eco/eco.ts

@@ -1,242 +0,0 @@
-/**
- * The eco namespace - unified component and page factory API
- * @module
- */
-
-import type {
-	EcoComponent,
-	EcoHtmlComponent,
-	EcoLayoutComponent,
-	EcoPagesElement,
-	EcoPageComponent,
-	GetMetadata,
-	GetStaticPaths,
-	GetStaticProps,
-	Middleware,
-	RequestLocals,
-	RequestPageContext,
-} from '../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 { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from './component-render-context.ts';
-import { createComponentMarker, parseComponentMarkers } from '../route-renderer/component-graph/component-marker.ts';
-import { getComponentReference } from '../route-renderer/component-graph/component-reference.ts';
-import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from './eco.utils.ts';
-
-/**
- * Creates a component factory with lazy-trigger support and deferred-boundary
- * marker emission.
- *
- * Behavior:
- * - In normal render flow, returns `options.render(props)` with optional lazy
- *   trigger/script wrapping.
- * - When rendering under component graph context and the active boundary policy
- *   decides the target boundary should defer, emits an `eco-marker` token
- *   instead of rendering the component immediately.
- *
- * @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 renderContext = getComponentRenderContext();
-		const shouldEmitMarker =
-			renderContext !== undefined &&
-			renderContext.boundaryContext.decideBoundaryRender({
-				currentIntegration: renderContext.currentIntegration,
-				targetIntegration: integrationName,
-				component: comp,
-			}) === 'defer';
-
-		if (shouldEmitMarker && renderContext) {
-			const nodeId = createNodeId(renderContext);
-			const propsRef = createPropsRef(renderContext);
-			const componentRef = getComponentReference(comp);
-
-			const componentProps = (props ?? {}) as Record<string, unknown>;
-			renderContext.propsByRef[propsRef] = componentProps;
-
-			let slotRef: string | undefined;
-			const children = componentProps.children;
-			if (typeof children === 'string' && children.includes('<eco-marker')) {
-				const childMarkers = parseComponentMarkers(children);
-				if (childMarkers.length > 0) {
-					slotRef = createSlotRef(renderContext);
-					renderContext.slotChildrenByRef[slotRef] = childMarkers.map((marker) => marker.nodeId);
-				}
-			}
-
-			return createComponentMarker({
-				nodeId,
-				integration: integrationName as string,
-				componentRef,
-				propsRef,
-				slotRef,
-			}) as E;
-		}
-
-		const content = options.render(props);
-
-		const lazyTriggers = comp.config?._resolvedLazyTriggers;
-		if (lazyTriggers && lazyTriggers.length > 0) {
-			const triggerId = lazyTriggers[0].triggerId;
-			if (isThenable(content)) {
-				return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
-			}
-			return addTriggerAttribute(content, triggerId);
-		}
-
-		const lazyGroups = comp.config?._resolvedLazyScripts;
-
-		if (lazyGroups && lazyGroups.length > 0) {
-			if (isThenable(content)) {
-				return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
-			}
-			return wrapWithScriptsInjector(content, lazyGroups);
-		}
-
-		return content;
-	}) 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);
-}
-
-/**
- * Creates a document shell component.
- *
- * Phase 1 keeps this as a semantic alias over eco.component() so existing
- * renderer behavior remains unchanged.
- */
-function html<E = EcoPagesElement>(options: HtmlOptions<E>): EcoHtmlComponent<E> {
-	return createComponentFactory(options) as EcoHtmlComponent<E>;
-}
-
-/**
- * Creates a route layout component.
- *
- * Phase 1 keeps this as a semantic alias over eco.component() so existing
- * renderer behavior remains unchanged.
- */
-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?: Middleware[] },
-): 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,
-	html,
-	layout,
-	page,
-	metadata,
-	staticPaths,
-	staticProps,
-};

package/src/eco/eco.types.ts

@@ -1,221 +0,0 @@
-/**
- * Type definitions for the eco namespace API
- * @module
- */
-
-import type {
-	DependencyLazyTrigger,
-	EcoComponent,
-	EcoComponentDependencies,
-	EcoHtmlComponent,
-	EcoInjectedMeta,
-	EcoLayoutComponent,
-	EcoPageLayoutComponent,
-	EcoPagesElement,
-	GetMetadata,
-	GetStaticPaths,
-	GetStaticProps,
-	HtmlTemplateProps,
-	LayoutProps,
-	Middleware,
-	RequestLocals,
-	RequestPageContext,
-} from '../public-types.ts';
-import type { CacheStrategy } from '../services/cache/cache.types.ts';
-
-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: Middleware[];
-}
-
-/**
- * Options for creating a page with eco.page()
- *
- * Supports two patterns:
- * 1. **Consolidated API** (recommended): Define staticPaths, staticProps, and metadata inline
- * 2. **Separate exports** (legacy): Export getStaticPaths, getStaticProps, getMetadata separately
- *
- * 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?: Middleware[];
-};
-
-/**
- * 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>;
-
-	/**
-	 * 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>;
-}

package/src/eco/eco.utils.ts

@@ -1,89 +0,0 @@
-import type { EcoComponent } from '../public-types.ts';
-import { buildInjectorMapScript } from './lazy-injector-map.ts';
-
-/**
- * Returns `true` when `value` is a thenable (Promise-like) object.
- *
- * Used to transparently handle both synchronous and asynchronous component
- * render results without requiring every caller to branch on `instanceof Promise`.
- *
- * @typeParam T Expected resolved type of the thenable.
- */
-export function isThenable<T>(value: unknown): value is PromiseLike<T> {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		'then' in value &&
-		typeof (value as { then?: unknown }).then === 'function'
-	);
-}
-
-/**
- * Injects `data-eco-trigger` into the first real HTML element opening tag of
- * a component's rendered output string.
- *
- * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
- * sections, and doctype declarations so that the attribute is always placed on
- * the first actual element — not spurious markup that can precede it.
- *
- * The insertion point is the end of the element's tag name, before any existing
- * attributes or the closing `>`, which produces output like:
- *
- * ```html
- * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
- * ```
- *
- * When no eligible opening tag is found the original string is returned
- * unchanged so callers never receive a broken fragment.
- *
- * @param content Rendered HTML string (or any value coercible to string).
- * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
- */
-export function addTriggerAttribute(content: unknown, triggerId: string): string {
-	const str = String(content);
-	let i = 0;
-
-	while (i < str.length) {
-		if (str[i] !== '<') {
-			i++;
-			continue;
-		}
-
-		const next = str[i + 1];
-
-		if (next === '!' || next === '?') {
-			const end = str.indexOf('>', i);
-			if (end === -1) break;
-			i = end + 1;
-			continue;
-		}
-
-		if (next && /[a-zA-Z]/.test(next)) {
-			const tagSlice = str.slice(i + 1);
-			const nameEnd = tagSlice.search(/[\s/>]/);
-			if (nameEnd === -1) break;
-			const insertAt = i + 1 + nameEnd;
-			return `${str.slice(0, insertAt)} data-eco-trigger="${triggerId}"${str.slice(insertAt)}`;
-		}
-
-		break;
-	}
-
-	return str;
-}
-
-/**
- * Wraps rendered component output in a `<scripts-injector>` element that
- * carries an inline injector map for the legacy (non-global-injector) path.
- *
- * @param content Rendered component HTML.
- * @param lazyGroups Resolved lazy script groups attached to the component config.
- */
-export function wrapWithScriptsInjector(
-	content: unknown,
-	lazyGroups: NonNullable<EcoComponent['config']>['_resolvedLazyScripts'],
-): string {
-	const wrappedContent = String(content);
-	const injectorMapScript = buildInjectorMapScript(lazyGroups ?? []);
-	return `<scripts-injector><script type="ecopages/injector-map">${injectorMapScript}</script>${wrappedContent}</scripts-injector>`;
-}

package/src/eco/global-injector-map.ts

@@ -1,112 +0,0 @@
-import type { ResolvedLazyTrigger } from '../public-types.ts';
-
-type GlobalInjectorEntry = {
-	'on:idle'?: { scripts: string[] };
-	'on:interaction'?: { value: string; scripts: string[] };
-	'on:visible'?: { value?: string; scripts: string[] };
-};
-
-type GlobalInjectorMap = Record<string, GlobalInjectorEntry>;
-
-/**
- * Converts a flat list of resolved triggers into the map structure consumed
- * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
- * `triggerId` are merged so their script lists are deduplicated.
- */
-function buildGlobalInjectorMap(triggers: ResolvedLazyTrigger[]): GlobalInjectorMap {
-	const map: GlobalInjectorMap = {};
-
-	for (const { triggerId, rules } of triggers) {
-		const entry: GlobalInjectorEntry = map[triggerId] ?? {};
-
-		for (const rule of rules) {
-			if ('on:idle' in rule) {
-				const { scripts } = rule['on:idle'];
-				entry['on:idle'] = {
-					scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-
-			if ('on:interaction' in rule) {
-				const { value, scripts } = rule['on:interaction'];
-				entry['on:interaction'] = {
-					value,
-					scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-
-			if ('on:visible' in rule) {
-				const { value, scripts } = rule['on:visible'];
-				entry['on:visible'] = {
-					...(value ? { value } : {}),
-					scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
-				};
-				continue;
-			}
-		}
-
-		if (Object.keys(entry).length > 0) {
-			map[triggerId] = entry;
-		}
-	}
-
-	return map;
-}
-
-/**
- * Serializes resolved lazy triggers into a JSON string safe for embedding
- * inside an inline `<script type="ecopages/global-injector-map">` tag.
- *
- * The `</script` sequence is escaped because an unescaped occurrence in inline
- * script content causes the HTML parser to close the script tag prematurely,
- * breaking page rendering. `JSON.stringify` does not perform this escape by
- * default, so a targeted replacement is applied after serialization.
- */
-export function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string {
-	const map = buildGlobalInjectorMap(triggers);
-	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
-}
-
-/**
- * Builds the inline module script that boots the global lazy injector on the client.
- * Emitted once per page alongside the `ecopages/global-injector-map` script block.
- */
-export function buildGlobalInjectorBootstrapContent(globalInjectorModuleUrl: string): string {
-	return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleUrl)};
-
-function pruneStaleTriggerMaps() {
-	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
-	if (mapScripts.length <= 1) {
-		return;
-	}
-
-	const latestMapScript = mapScripts[mapScripts.length - 1];
-	for (const mapScript of mapScripts) {
-		if (mapScript !== latestMapScript) {
-			mapScript.remove();
-		}
-	}
-}
-
-const globalScope = window;
-if (typeof globalScope.__ecoGlobalInjectorCleanup === 'function') {
-	globalScope.__ecoGlobalInjectorCleanup();
-}
-
-const injector = initGlobalInjector();
-
-const handleAfterSwap = () => {
-	pruneStaleTriggerMaps();
-	injector.refresh();
-};
-
-document.addEventListener('eco:after-swap', handleAfterSwap);
-pruneStaleTriggerMaps();
-
-globalScope.__ecoGlobalInjectorCleanup = () => {
-	document.removeEventListener('eco:after-swap', handleAfterSwap);
-	injector.cleanup();
-};`;
-}