@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

package/src/route-renderer/orchestration/template-serialization.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'vitest';
+import {
+	type DeferredTemplateSerializer,
+	serializeTemplateShape,
+	type SerializableTemplateShape,
+} from './template-serialization.ts';
+
+type TestTemplateShape = SerializableTemplateShape & {
+	__testTemplateType: 'deferred-template';
+};
+
+function createTestTemplate(strings: readonly string[], values: readonly unknown[]): TestTemplateShape {
+	return {
+		__testTemplateType: 'deferred-template',
+		strings,
+		values,
+	};
+}
+
+const testDeferredTemplateSerializer: DeferredTemplateSerializer<TestTemplateShape> = {
+	matches(value: unknown): value is TestTemplateShape {
+		return (
+			typeof value === 'object' &&
+			value !== null &&
+			(value as { __testTemplateType?: unknown }).__testTemplateType === 'deferred-template' &&
+			Array.isArray((value as { strings?: unknown }).strings) &&
+			((value as { values?: unknown }).values === undefined ||
+				Array.isArray((value as { values?: unknown }).values))
+		);
+	},
+	serialize(template: TestTemplateShape, serializeValue: (value: unknown) => string | undefined) {
+		return serializeTemplateShape(template, serializeValue);
+	},
+};
+
+function serializeTestDeferredTemplateValue(
+	value: unknown,
+	serializeValue: (value: unknown) => string | undefined,
+): string | undefined {
+	if (!testDeferredTemplateSerializer.matches(value)) {
+		return undefined;
+	}
+
+	return testDeferredTemplateSerializer.serialize(value, serializeValue);
+}
+
+describe('serializeTemplateLike', () => {
+	test('preserves quoted attribute values for multi-token class attributes', () => {
+		const html = serializeTemplateShape(
+			createTestTemplate(['<div class=', '>', '</div>'], ['grid gap-4 lg:grid-cols-2 xl:grid-cols-4', 'Content']),
+			(value) => (value == null ? '' : String(value)),
+		);
+
+		expect(html).toBe('<div class="grid gap-4 lg:grid-cols-2 xl:grid-cols-4">Content</div>');
+	});
+
+	test('omits falsey boolean attributes and preserves truthy boolean attributes', () => {
+		const truthyHtml = serializeTemplateShape(
+			createTestTemplate(['<button ?disabled=', '>x</button>'], ['yes']),
+			(value) => (value == null ? '' : String(value)),
+		);
+		const falseyHtml = serializeTemplateShape(
+			createTestTemplate(['<button ?disabled=', '>x</button>'], ['']),
+			(value) => (value == null ? '' : String(value)),
+		);
+
+		expect(truthyHtml).toBe('<button disabled>x</button>');
+		expect(falseyHtml).toBe('<button>x</button>');
+	});
+
+	test('skips event and prop bindings in SSR output', () => {
+		const html = serializeTemplateShape(
+			createTestTemplate(['<button @click=', ' .value=', '>x</button>'], ['handler', '1']),
+			(value) => (value == null ? '' : String(value)),
+		);
+
+		expect(html).toBe('<button>x</button>');
+	});
+
+	test('escapes attribute values while preserving child interpolation', () => {
+		const html = serializeTemplateShape(
+			createTestTemplate(['<div title=', '>', '</div>'], ['a "quote" & <tag>', '<span>child</span>']),
+			(value) => (value == null ? '' : String(value)),
+		);
+
+		expect(html).toBe('<div title="a &quot;quote&quot; &amp; &lt;tag&gt;"><span>child</span></div>');
+	});
+
+	test('does not serialize unmatched template-like values', () => {
+		expect(
+			serializeTestDeferredTemplateValue(
+				{
+					strings: ['<div>', '</div>'],
+					values: ['content'],
+					_$litType$: 1,
+				},
+				(value) => (value == null ? '' : String(value)),
+			),
+		).toBeUndefined();
+	});
+
+	test('serializes locally provided template serializers without ambient registration', () => {
+		expect(
+			serializeTestDeferredTemplateValue(
+				createTestTemplate(['<div class=', '>', '</div>'], ['shared gap-4', 'content']),
+				(value) => (value == null ? '' : String(value)),
+			),
+		).toBe('<div class="shared gap-4">content</div>');
+	});
+});

package/src/route-renderer/orchestration/template-serialization.ts

@@ -0,0 +1,117 @@
+import { escapeHtmlAttribute } from '../../utils/html-escaping.ts';
+
+/**
+ * Minimal template-result shape that core can serialize generically.
+ *
+ * @remarks
+ * Core intentionally models only the transport shape used during deferred
+ * cross-integration child passing: alternating static string segments plus
+ * interpolated runtime values. Concrete runtime markers that identify a given
+ * framework's template payload must stay outside core and be registered by the
+ * owning integration package.
+ */
+export type SerializableTemplateShape = {
+	strings: readonly string[];
+	values?: readonly unknown[];
+};
+
+/**
+ * Parsed attribute metadata for one template string segment.
+ *
+ * `serializeTemplateShape()` uses this to decide whether the next interpolated
+ * value should be emitted as raw HTML content, a quoted attribute value, a
+ * boolean attribute, or omitted entirely for client-only bindings.
+ */
+type SerializableTemplateAttribute = {
+	leading: string;
+	name: string;
+	prefix: string;
+	whitespace: string;
+};
+
+/**
+ * Integration-owned adapter that teaches core how to serialize one deferred
+ * template payload shape.
+ *
+ * @remarks
+ * The separation here is intentional: core owns the HTML serialization logic,
+ * but integrations own runtime-shape detection. That keeps package-specific
+ * markers such as framework template sentinels out of core while still letting
+ * deferred children round-trip through mixed renderer boundaries.
+ */
+export type DeferredTemplateSerializer<TTemplate extends SerializableTemplateShape = SerializableTemplateShape> = {
+	matches(value: unknown): value is TTemplate;
+	serialize(template: TTemplate, serializeValue: (value: unknown) => string | undefined): string;
+};
+
+const ATTRIBUTE_TAIL_PATTERN = /(\s+)([@.?!]?)([^\s"'<>/=`@.?!]+)=$/;
+
+/**
+ * Detects whether the current string segment ends in an HTML attribute binding.
+ *
+ * The parser is intentionally small: it only recognizes the transport shape
+ * Ecopages needs during deferred mixed-integration rendering, not a full HTML
+ * grammar.
+ */
+function getSerializableTemplateAttribute(stringPart: string): SerializableTemplateAttribute | undefined {
+	const match = ATTRIBUTE_TAIL_PATTERN.exec(stringPart);
+	if (!match) return undefined;
+
+	return {
+		leading: stringPart.slice(0, match.index),
+		whitespace: match[1],
+		prefix: match[2],
+		name: match[3],
+	};
+}
+
+/**
+ * Serializes a generic template shape into HTML.
+ *
+ * @remarks
+ * This handles only HTML reconstruction semantics: quoted attribute values,
+ * boolean attributes, and omission of client-only event or property bindings.
+ * It does not decide whether an arbitrary value belongs to a framework-specific
+ * template runtime; integrations must make that decision before delegating here.
+ */
+export function serializeTemplateShape(
+	template: SerializableTemplateShape,
+	serializeValue: (value: unknown) => string | undefined,
+): string {
+	const values = template.values ?? [];
+	let html = '';
+
+	for (let index = 0; index < values.length; index += 1) {
+		const stringPart = template.strings[index] ?? '';
+		const serializedValue = serializeValue(values[index]);
+		const attribute = getSerializableTemplateAttribute(stringPart);
+
+		if (!attribute) {
+			html += stringPart;
+			html += serializedValue ?? '';
+			continue;
+		}
+
+		html += attribute.leading;
+
+		if (attribute.prefix === '@' || attribute.prefix === '!' || attribute.prefix === '.') {
+			continue;
+		}
+
+		if (attribute.prefix === '?') {
+			if (serializedValue) {
+				html += `${attribute.whitespace}${attribute.name}`;
+			}
+			continue;
+		}
+
+		if (serializedValue === undefined) {
+			continue;
+		}
+
+		html += `${attribute.whitespace}${attribute.name}="${escapeHtmlAttribute(serializedValue)}"`;
+	}
+
+	html += template.strings[values.length] ?? '';
+	return html;
+}

package/src/route-renderer/page-loading/component-dependency-collection.ts

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import type { DependencyLazyTrigger, EcoComponent } from '../../types/public-types.ts';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import { extractEcopagesVirtualImports } from './ecopages-virtual-imports.ts';
+import { collectDeclaredAssetEntries } from './declared-asset-collection.ts';
+import { getLazyTriggerKey } from './lazy-trigger-planning.ts';
+import { collectLazyScriptEntries, type LazyGroup } from './lazy-entry-collection.ts';
+import {
+	createModuleScriptName,
+	createNamedImportModuleSource,
+	createNamespaceImportModuleSource,
+} from './module-declaration-scripts.ts';
+import { collectModuleDeclarations } from './module-declaration-aggregation.ts';
+
+const MODULE_SCRIPT_ATTRIBUTES = {
+	type: 'module',
+	defer: '',
+} as const;
+
+function createModuleScriptAttributes(attributes?: Record<string, string>): Record<string, string> {
+	return {
+		...MODULE_SCRIPT_ATTRIBUTES,
+		...attributes,
+	};
+}
+
+function pushUniqueDependency(
+	keys: Set<string>,
+	key: string,
+	dependencies: AssetDefinition[],
+	dependency: AssetDefinition,
+): boolean {
+	if (keys.has(key)) {
+		return false;
+	}
+
+	keys.add(key);
+	dependencies.push(dependency);
+	return true;
+}
+
+function resolveDependencyPath(componentDir: string, pathUrl: string): string {
+	return path.join(componentDir, pathUrl);
+}
+
+/**
+ * Aggregated dependency output for one dependency-collection pass.
+ */
+export type CollectedComponentDependencies = {
+	/**
+	 * Flat asset declarations ready for downstream processing.
+	 */
+	dependencies: AssetDefinition[];
+	/**
+	 * Lazy script groups keyed by component config and trigger key.
+	 */
+	lazyScriptsByConfig: Map<NonNullable<EcoComponent['config']>, Map<string, LazyGroup>>;
+};
+
+type CollectComponentDependenciesOptions = {
+	components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>;
+	integrationName: string;
+	resolveLazyScripts: (componentDir: string, scripts: string[]) => string;
+	createEcopagesJsxLazyEntryName: (integrationName: string, key: string) => string;
+	isEcopagesJsxIntegration: (integrationName: string) => boolean;
+	errors: {
+		invalidStylesheetEntry: string;
+		invalidScriptEntry: string;
+		lazyScriptMissingSrc: string;
+	};
+};
+
+/**
+ * Walks component dependency trees and collects declared assets, module declarations,
+ * and lazy-script group metadata in one pass.
+ *
+ * The returned structures intentionally preserve both the flat asset list used by
+ * asset processing and the grouped lazy-trigger data used later during render output.
+ */
+export function collectComponentDependencies(
+	options: CollectComponentDependenciesOptions,
+): CollectedComponentDependencies {
+	const { components, integrationName, resolveLazyScripts, createEcopagesJsxLazyEntryName, isEcopagesJsxIntegration, errors } =
+		options;
+	const dependencies: AssetDefinition[] = [];
+	const lazyScriptsByConfig = new Map<NonNullable<EcoComponent['config']>, Map<string, LazyGroup>>();
+	const lazyDependencyKeys = new Set<string>();
+
+	for (const component of components) {
+		if (!component) continue;
+
+		const componentFile = component.config?.__eco?.file;
+		if (!componentFile) continue;
+
+		const stylesheetDependencyKeys = new Set<string>();
+		const scriptDependencyKeys = new Set<string>();
+		const modulesMap = new Map<string, Set<string> | null>();
+
+		/**
+		 * Recursively visits one component config and its declared child dependencies.
+		 */
+		const collect = (config: EcoComponent['config']) => {
+			if (!config) return;
+
+			const file = config.__eco?.file;
+			if (!file) return;
+			const dir = path.dirname(file);
+			const dependenciesConfig = config.dependencies;
+
+			const registerLazyScript = ({
+				lazy,
+				lazyKey,
+				fallbackUrl,
+			}: {
+				lazy: DependencyLazyTrigger;
+				lazyKey: string;
+				fallbackUrl?: string;
+			}) => {
+				let grouped = lazyScriptsByConfig.get(config);
+				if (!grouped) {
+					grouped = new Map<string, LazyGroup>();
+					lazyScriptsByConfig.set(config, grouped);
+				}
+
+				const triggerKey = getLazyTriggerKey(lazy);
+				const existing = grouped.get(triggerKey) ?? { lazy, scripts: [] };
+				existing.scripts.push({ lazyKey, fallbackUrl });
+				grouped.set(triggerKey, existing);
+			};
+
+			collectDeclaredAssetEntries({
+				stylesheetEntries: dependenciesConfig?.stylesheets ?? [],
+				scriptEntries: dependenciesConfig?.scripts ?? [],
+				componentDir: dir,
+				dependencies,
+				stylesheetDependencyKeys,
+				scriptDependencyKeys,
+				resolveDependencyPath,
+				createModuleScriptAttributes,
+				pushUniqueDependency,
+				getInvalidStylesheetEntryMessage: () => errors.invalidStylesheetEntry,
+				getInvalidScriptEntryMessage: () => errors.invalidScriptEntry,
+			});
+
+			collectModuleDeclarations(modulesMap, dependenciesConfig?.modules, extractEcopagesVirtualImports(file));
+
+			collectLazyScriptEntries({
+				scriptEntries: dependenciesConfig?.scripts ?? [],
+				componentFile: file,
+				componentDir: dir,
+				integrationName,
+				dependencies,
+				lazyDependencyKeys,
+				registerLazyScript,
+				resolveDependencyPath,
+				resolveLazyScripts,
+				createModuleScriptAttributes,
+				createEcopagesJsxLazyEntryName,
+				pushUniqueDependency,
+				getLazyScriptMissingSrcMessage: () => errors.lazyScriptMissingSrc,
+				isEcopagesJsxIntegration,
+			});
+
+			if (dependenciesConfig?.components) {
+				for (const nestedComponent of dependenciesConfig.components) {
+					if (nestedComponent?.config) {
+						collect(nestedComponent.config);
+					}
+				}
+			}
+		};
+
+		collect(component.config);
+
+		dependencies.push(
+			...Array.from(modulesMap.entries()).map(([from, importsSet]) => {
+				const imports = importsSet ? Array.from(importsSet) : undefined;
+				return AssetFactory.createContentScript({
+					position: 'head',
+					name: createModuleScriptName(from, imports),
+					content:
+						imports && imports.length > 0
+							? createNamedImportModuleSource(from, imports)
+							: createNamespaceImportModuleSource(from),
+					attributes: createModuleScriptAttributes(),
+				});
+			}),
+		);
+	}
+
+	return {
+		dependencies,
+		lazyScriptsByConfig,
+	};
+}

package/src/route-renderer/page-loading/declared-asset-collection.ts

@@ -0,0 +1,156 @@
+import type {
+	EcoComponentScriptEntry,
+	EcoComponentStylesheetEntry,
+} from '../../types/public-types.ts';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+
+type CollectDeclaredAssetEntriesOptions = {
+	stylesheetEntries: Array<string | EcoComponentStylesheetEntry>;
+	scriptEntries: Array<string | EcoComponentScriptEntry>;
+	componentDir: string;
+	dependencies: AssetDefinition[];
+	stylesheetDependencyKeys: Set<string>;
+	scriptDependencyKeys: Set<string>;
+	resolveDependencyPath: (componentDir: string, pathUrl: string) => string;
+	createModuleScriptAttributes: (attributes?: Record<string, string>) => Record<string, string>;
+	pushUniqueDependency: (
+		keys: Set<string>,
+		key: string,
+		dependencies: AssetDefinition[],
+		dependency: AssetDefinition,
+	) => boolean;
+	getInvalidStylesheetEntryMessage: () => string;
+	getInvalidScriptEntryMessage: () => string;
+};
+
+function isDependencyEntryObject(
+	entry: string | EcoComponentScriptEntry | EcoComponentStylesheetEntry,
+): entry is EcoComponentScriptEntry | EcoComponentStylesheetEntry {
+	return typeof entry === 'object' && entry !== null;
+}
+
+function getDependencyEntrySrc(
+	entry: string | EcoComponentScriptEntry | EcoComponentStylesheetEntry,
+): string | undefined {
+	return isDependencyEntryObject(entry) ? entry.src : entry;
+}
+
+function getDependencyEntryContent(
+	entry: string | EcoComponentScriptEntry | EcoComponentStylesheetEntry,
+): string | undefined {
+	return isDependencyEntryObject(entry) ? entry.content : undefined;
+}
+
+function getDependencyEntryAttributes(
+	entry: string | EcoComponentScriptEntry | EcoComponentStylesheetEntry,
+): Record<string, string> | undefined {
+	return isDependencyEntryObject(entry) ? entry.attributes : undefined;
+}
+
+/**
+ * Normalizes non-lazy stylesheet and script declarations into asset definitions.
+ *
+ * Duplicate declarations are filtered through the provided key sets so callers can
+ * compose this helper into larger recursive collection passes without re-emitting
+ * the same asset multiple times.
+ */
+export function collectDeclaredAssetEntries(options: CollectDeclaredAssetEntriesOptions): void {
+	const {
+		stylesheetEntries,
+		scriptEntries,
+		componentDir,
+		dependencies,
+		stylesheetDependencyKeys,
+		scriptDependencyKeys,
+		resolveDependencyPath,
+		createModuleScriptAttributes,
+		pushUniqueDependency,
+		getInvalidStylesheetEntryMessage,
+		getInvalidScriptEntryMessage,
+	} = options;
+
+	for (const style of stylesheetEntries) {
+		const content = getDependencyEntryContent(style);
+		const src = getDependencyEntrySrc(style);
+		const attributes = getDependencyEntryAttributes(style);
+
+		if (content) {
+			const depKey = `style:content:${content}:${JSON.stringify(attributes ?? {})}`;
+			pushUniqueDependency(
+				stylesheetDependencyKeys,
+				depKey,
+				dependencies,
+				AssetFactory.createContentStylesheet({
+					content,
+					position: 'head',
+					attributes,
+				}),
+			);
+			continue;
+		}
+
+		if (!src) {
+			throw new Error(getInvalidStylesheetEntryMessage());
+		}
+
+		const resolvedPath = resolveDependencyPath(componentDir, src);
+		const depKey = `style:file:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+		pushUniqueDependency(
+			stylesheetDependencyKeys,
+			depKey,
+			dependencies,
+			AssetFactory.createFileStylesheet({
+				filepath: resolvedPath,
+				position: 'head',
+				attributes: {
+					rel: 'stylesheet',
+					...attributes,
+				},
+			}),
+		);
+	}
+
+	for (const script of scriptEntries) {
+		if (isDependencyEntryObject(script) && 'lazy' in script && script.lazy) {
+			continue;
+		}
+
+		const content = getDependencyEntryContent(script);
+		const src = getDependencyEntrySrc(script);
+		const attributes = getDependencyEntryAttributes(script);
+
+		if (content) {
+			const depKey = `script:content:${content}:${JSON.stringify(attributes ?? {})}`;
+			pushUniqueDependency(
+				scriptDependencyKeys,
+				depKey,
+				dependencies,
+				AssetFactory.createInlineContentScript({
+					position: 'head',
+					content,
+					bundle: false,
+					attributes,
+				}),
+			);
+			continue;
+		}
+
+		if (!src) {
+			throw new Error(getInvalidScriptEntryMessage());
+		}
+
+		const resolvedPath = resolveDependencyPath(componentDir, src);
+		const depKey = `script:file:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+		pushUniqueDependency(
+			scriptDependencyKeys,
+			depKey,
+			dependencies,
+			AssetFactory.createFileScript({
+				filepath: resolvedPath,
+				position: 'head',
+				attributes: createModuleScriptAttributes(attributes),
+			}),
+		);
+	}
+}