@useavalon/avalon 0.1.12 → 0.1.13

package/src/core/layout/layout-discovery.ts

@@ -0,0 +1,243 @@
+import { join, resolve, relative } from 'node:path';
+import { statSync } from 'node:fs';
+
+import type {
+	ComponentType,
+	LayoutRoute,
+	LayoutHandler,
+	LayoutDiscoveryOptions,
+	LayoutContext,
+	LayoutData,
+	LayoutProps,
+	LayoutErrorInfo,
+} from './layout-types.ts';
+
+export type { LayoutDiscoveryOptions } from './layout-types.ts';
+
+interface LayoutFileExport {
+	default: ComponentType<LayoutProps>;
+	layoutLoader?: (ctx: LayoutContext) => Promise<LayoutData>;
+}
+
+/**
+ * Converts an absolute file path to a valid ESM import specifier.
+ * Windows absolute paths (C:\...) are converted to file:// URLs.
+ */
+function toImportSpecifier(filePath: string): string {
+	if (/^[A-Za-z]:[\\/]/.test(filePath)) {
+		return `file:///${filePath.replaceAll('\\', '/')}`;
+	}
+	return filePath;
+}
+
+/**
+ * Checks whether a file exists at the given path using statSync.
+ */
+function fileExists(filePath: string): boolean {
+	try {
+		statSync(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Builds the path hierarchy for a route.
+ * For "/admin/users" returns ['', '/admin', '/admin/users'].
+ */
+function buildPathHierarchy(routePath: string): string[] {
+	const segments = routePath.split('/').filter(Boolean);
+	const paths: string[] = [''];
+	for (let i = 0; i < segments.length; i++) {
+		paths.push('/' + segments.slice(0, i + 1).join('/'));
+	}
+	return paths;
+}
+
+/**
+ * Simplified Layout Discovery System
+ *
+ * Looks for _layout.tsx files in the path hierarchy from root to the current route.
+ *
+ * For route /admin/users/123:
+ * - Check src/layouts/_layout.tsx (root layout)
+ * - Check src/layouts/admin/_layout.tsx
+ * - Check src/layouts/admin/users/_layout.tsx
+ */
+export class LayoutDiscovery {
+	private readonly layoutCache = new Map<string, LayoutHandler>();
+	private readonly routeCache = new Map<string, LayoutRoute[]>();
+	private readonly baseDirectory: string;
+	private readonly filePattern: string;
+	private readonly developmentMode: boolean;
+
+	constructor(options: LayoutDiscoveryOptions) {
+		this.baseDirectory = resolve(options.baseDirectory);
+		this.filePattern = options.filePattern || '_layout.tsx';
+		this.developmentMode = options.developmentMode || false;
+
+		if (this.developmentMode) {
+			console.log(`[LayoutDiscovery] baseDirectory=${this.baseDirectory}, filePattern=${this.filePattern}`);
+		}
+	}
+
+	/**
+	 * Discovers all layout files for a given route path by walking up the path hierarchy
+	 */
+	discoverLayouts(routePath: string): Promise<LayoutRoute[]> {
+		const cacheKey = `layouts-${routePath}`;
+
+		if (this.routeCache.has(cacheKey)) {
+			return Promise.resolve(this.routeCache.get(cacheKey)!);
+		}
+
+		const routes: LayoutRoute[] = [];
+		const pathsToCheck = buildPathHierarchy(routePath);
+
+		for (const pathToCheck of pathsToCheck) {
+			const fsPath = pathToCheck === '' ? this.baseDirectory : join(this.baseDirectory, pathToCheck);
+			const layoutFilePath = join(fsPath, this.filePattern);
+
+			if (fileExists(layoutFilePath)) {
+				const depth = pathToCheck === '' ? 0 : pathToCheck.split('/').filter(Boolean).length;
+				routes.push({
+					pattern: new URLPattern({ pathname: depth === 0 ? '*' : `${pathToCheck}/*` }),
+					layoutPath: layoutFilePath,
+					priority: depth * 10,
+					type: depth === 0 ? 'root' : 'nested',
+					depth,
+				});
+			}
+		}
+
+		routes.sort((a, b) => a.priority - b.priority);
+		this.routeCache.set(cacheKey, routes);
+		return Promise.resolve(routes);
+	}
+
+	/**
+	 * Builds a complete layout chain for a URL
+	 */
+	async buildLayoutChain(url: URL): Promise<LayoutHandler[]> {
+		const routes = await this.discoverLayouts(url.pathname);
+		const layoutChain: LayoutHandler[] = [];
+
+		for (const route of routes) {
+			try {
+				const handler = await this.loadLayout(route.layoutPath);
+				if (handler) {
+					layoutChain.push(handler);
+				}
+			} catch (error) {
+				if (this.developmentMode) {
+					console.warn(
+						`[Layout] Failed to load ${route.layoutPath}: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+		}
+
+		return layoutChain;
+	}
+
+	/**
+	 * Builds layout chain with data loading
+	 */
+	async buildLayoutChainWithData(
+		url: URL,
+		context: LayoutContext,
+	): Promise<{ handlers: LayoutHandler[]; data: LayoutData[]; errors: LayoutErrorInfo[] }> {
+		const handlers = await this.buildLayoutChain(url);
+		const data: LayoutData[] = [];
+		const errors: LayoutErrorInfo[] = [];
+
+		for (const handler of handlers) {
+			if (handler.loader) {
+				try {
+					const layoutData = await handler.loader(context);
+					data.push(layoutData);
+				} catch (error) {
+					if (this.developmentMode) {
+						console.warn(`[Layout] Data loader error for ${handler.path}:`, error);
+					}
+					errors.push({ layoutPath: handler.path, errorType: 'loader', timestamp: Date.now() });
+					data.push({});
+				}
+			} else {
+				data.push({});
+			}
+		}
+
+		return { handlers, data, errors };
+	}
+
+	/**
+	 * Loads layout handler from file
+	 */
+	private async loadLayout(filePath: string): Promise<LayoutHandler | null> {
+		if (this.layoutCache.has(filePath)) {
+			return this.layoutCache.get(filePath)!;
+		}
+
+		try {
+			const importPath = toImportSpecifier(filePath);
+			const layoutModule = (await import(/* @vite-ignore */ importPath)) as LayoutFileExport;
+
+			if (!layoutModule.default || typeof layoutModule.default !== 'function') {
+				if (this.developmentMode) {
+					console.warn(`[Layout] No default export in ${filePath}`);
+				}
+				return null;
+			}
+
+			const relativePath = relative(this.baseDirectory, filePath);
+			const pathSegments = relativePath.split('/').filter(Boolean);
+			const priority = Math.max(0, (pathSegments.length - 1) * 10);
+
+			const handler: LayoutHandler = {
+				component: layoutModule.default,
+				loader: layoutModule.layoutLoader,
+				path: filePath,
+				priority,
+			};
+
+			this.layoutCache.set(filePath, handler);
+			return handler;
+		} catch (error) {
+			if (this.developmentMode) {
+				console.warn(`[Layout] Failed to load ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return null;
+		}
+	}
+
+	/** Clears all caches */
+	clearCache(): void {
+		this.layoutCache.clear();
+		this.routeCache.clear();
+	}
+
+	/** Clears cache for a specific layout file */
+	clearLayoutCache(filePath: string): void {
+		this.layoutCache.delete(filePath);
+		this.routeCache.clear();
+	}
+
+	/** Gets cache statistics (for debugging) */
+	getCacheStats(): { layoutCount: number; routeCacheCount: number } {
+		return {
+			layoutCount: this.layoutCache.size,
+			routeCacheCount: this.routeCache.size,
+		};
+	}
+
+	/** Gets the current discovery options */
+	getOptions(): LayoutDiscoveryOptions {
+		return {
+			baseDirectory: this.baseDirectory,
+			filePattern: this.filePattern,
+			developmentMode: this.developmentMode,
+		};
+	}
+}

package/src/core/layout/layout-matcher.ts

@@ -0,0 +1,299 @@
+import type { LayoutRule, RouteInfo } from './layout-types.ts';
+
+/**
+ * Built-in layout rules for common scenarios
+ */
+export class BuiltInLayoutRules {
+	/**
+	 * Rule to skip HTML layouts for API routes
+	 * Requirements: 4.1
+	 */
+	static readonly API_ROUTES_SKIP_LAYOUTS: LayoutRule = {
+		matches: (route: RouteInfo): boolean => {
+			return route.path.startsWith('/api/');
+		},
+		apply: false,
+		priority: 100,
+	};
+
+	/**
+	 * Rule to apply mobile-specific layouts for mobile user agents
+	 * Requirements: 4.2
+	 */
+	static readonly MOBILE_LAYOUT_DETECTION: LayoutRule = {
+		matches: (route: RouteInfo, layoutPath?: string): boolean => {
+			const userAgent = route.headers.get('user-agent')?.toLowerCase() || '';
+			const isMobile = /mobile|android|iphone|ipad|phone|tablet/i.test(userAgent);
+			const isMobileLayout = layoutPath?.includes('/mobile/') ?? false;
+			// Skip mobile layouts for non-mobile user agents; skip non-mobile layouts for mobile users
+			if (isMobileLayout) return !isMobile;
+			return isMobile;
+		},
+		apply: false,
+		priority: 50,
+	};
+
+	/**
+	 * Rule to skip layouts based on specific headers
+	 * Requirements: 4.3
+	 */
+	static readonly HEADER_BASED_SKIP: LayoutRule = {
+		matches: (route: RouteInfo): boolean => {
+			const skipLayout = route.headers.get('x-skip-layout');
+			return skipLayout === 'true' || skipLayout === '1';
+		},
+		apply: false,
+		priority: 90,
+	};
+
+	/**
+	 * Rule to apply admin layouts only for admin routes
+	 * Requirements: 4.3
+	 */
+	static readonly ADMIN_LAYOUT_RESTRICTION: LayoutRule = {
+		matches: (route: RouteInfo, layoutPath?: string): boolean => {
+			// Only restrict admin layouts — if no layoutPath or not an admin layout, don't match
+			if (!layoutPath?.includes('/admin/')) return false;
+			// Admin layout should only apply to admin routes
+			return !route.path.startsWith('/admin/');
+		},
+		apply: false,
+		priority: 60,
+	};
+
+	static getAllRules(): LayoutRule[] {
+		return [
+			this.API_ROUTES_SKIP_LAYOUTS,
+			this.MOBILE_LAYOUT_DETECTION,
+			this.HEADER_BASED_SKIP,
+			this.ADMIN_LAYOUT_RESTRICTION,
+		];
+	}
+}
+
+/**
+ * Layout matcher class that handles conditional layout rendering based on rules
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5
+ */
+export class LayoutMatcher {
+	private rules: LayoutRule[] = [];
+	private readonly developmentMode: boolean;
+
+	constructor(options: { developmentMode?: boolean } = {}) {
+		this.developmentMode = options.developmentMode || false;
+		this.addBuiltInRules();
+	}
+
+	/**
+	 * Add a new layout rule
+	 * Requirements: 4.3
+	 */
+	addRule(rule: LayoutRule): void {
+		if (!rule.matches || typeof rule.matches !== 'function') {
+			throw new Error('Layout rule must have a valid matches function');
+		}
+		if (typeof rule.apply !== 'boolean') {
+			throw new TypeError('Layout rule must have a boolean apply property');
+		}
+		if (typeof rule.priority !== 'number') {
+			throw new TypeError('Layout rule must have a numeric priority');
+		}
+
+		this.rules.push(rule);
+		this.sortRulesByPriority();
+
+		if (this.developmentMode) {
+			console.log(`[LayoutMatcher] Added rule with priority ${rule.priority}`);
+		}
+	}
+
+	/**
+	 * Remove a layout rule
+	 * Requirements: 4.3
+	 */
+	removeRule(rule: LayoutRule): void {
+		const index = this.rules.indexOf(rule);
+		if (index > -1) {
+			this.rules.splice(index, 1);
+			if (this.developmentMode) {
+				console.log(`[LayoutMatcher] Removed rule with priority ${rule.priority}`);
+			}
+		}
+	}
+
+	/**
+	 * Check if a layout should be applied based on all rules
+	 * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5
+	 */
+	shouldApplyLayout(layoutPath: string, route: RouteInfo): boolean {
+		try {
+			const matchingRules = this.getMatchingRules(route, layoutPath);
+
+			if (matchingRules.length === 0) {
+				return true;
+			}
+
+			const result = this.resolveRuleConflicts(matchingRules);
+
+			if (this.developmentMode) {
+				console.log(
+					`[LayoutMatcher] Layout ${layoutPath} for route ${route.path}: ${result ? 'APPLY' : 'SKIP'} ` +
+						`(${matchingRules.length} rules matched)`,
+				);
+			}
+
+			return result;
+		} catch (error) {
+			if (this.developmentMode) {
+				console.warn(
+					`[LayoutMatcher] Error evaluating rules for layout ${layoutPath}: ${
+						error instanceof Error ? error.message : String(error)
+					}`,
+				);
+			}
+			return true;
+		}
+	}
+
+	getRules(): LayoutRule[] {
+		return [...this.rules];
+	}
+
+	clearRules(): void {
+		this.rules = [];
+		if (this.developmentMode) {
+			console.log('[LayoutMatcher] Cleared all rules');
+		}
+	}
+
+	private addBuiltInRules(): void {
+		for (const rule of BuiltInLayoutRules.getAllRules()) {
+			this.rules.push(rule);
+		}
+		this.sortRulesByPriority();
+		if (this.developmentMode) {
+			console.log(`[LayoutMatcher] Added ${this.rules.length} built-in rules`);
+		}
+	}
+
+	private sortRulesByPriority(): void {
+		this.rules.sort((a, b) => b.priority - a.priority);
+	}
+
+	private getMatchingRules(route: RouteInfo, layoutPath?: string): LayoutRule[] {
+		const matchingRules: LayoutRule[] = [];
+		for (const rule of this.rules) {
+			try {
+				if (rule.matches(route, layoutPath)) {
+					matchingRules.push(rule);
+				}
+			} catch (error) {
+				if (this.developmentMode) {
+					console.warn(
+						`[LayoutMatcher] Error in rule evaluation: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				}
+			}
+		}
+		return matchingRules;
+	}
+
+	private resolveRuleConflicts(matchingRules: LayoutRule[]): boolean {
+		if (matchingRules.length === 0) return true;
+		if (matchingRules.length === 1) return matchingRules[0].apply;
+
+		const rulesByPriority = new Map<number, LayoutRule[]>();
+		for (const rule of matchingRules) {
+			if (!rulesByPriority.has(rule.priority)) {
+				rulesByPriority.set(rule.priority, []);
+			}
+			rulesByPriority.get(rule.priority)!.push(rule);
+		}
+
+		const priorities = Array.from(rulesByPriority.keys()).sort((a, b) => b - a);
+		const highestPriorityRules = rulesByPriority.get(priorities[0])!;
+
+		if (highestPriorityRules.length === 1) {
+			return highestPriorityRules[0].apply;
+		}
+
+		return this.resolveEqualPriorityConflicts(highestPriorityRules);
+	}
+
+	private resolveEqualPriorityConflicts(rules: LayoutRule[]): boolean {
+		const applyCount = rules.filter(rule => rule.apply).length;
+		const skipCount = rules.filter(rule => !rule.apply).length;
+
+		if (skipCount > applyCount) {
+			if (this.developmentMode) console.log(`[LayoutMatcher] Conflict resolution: SKIP`);
+			return false;
+		} else if (applyCount > skipCount) {
+			if (this.developmentMode) console.log(`[LayoutMatcher] Conflict resolution: APPLY`);
+			return true;
+		} else {
+			if (this.developmentMode) console.log(`[LayoutMatcher] Conflict resolution: SKIP (tie-breaker)`);
+			return false;
+		}
+	}
+
+	/**
+	 * Create a custom rule
+	 * Requirements: 4.3
+	 */
+	static createCustomRule(matcher: (route: RouteInfo) => boolean, apply: boolean, priority: number = 10): LayoutRule {
+		return { matches: matcher, apply, priority };
+	}
+
+	static createPathRule(pathPattern: string | RegExp, apply: boolean, priority: number = 10): LayoutRule {
+		const matches =
+			typeof pathPattern === 'string'
+				? (route: RouteInfo) => route.path.includes(pathPattern)
+				: (route: RouteInfo) => pathPattern.test(route.path);
+		return { matches, apply, priority };
+	}
+
+	static createHeaderRule(
+		headerName: string,
+		headerValue: string | RegExp,
+		apply: boolean,
+		priority: number = 10,
+	): LayoutRule {
+		return {
+			matches: (route: RouteInfo) => {
+				const val = route.headers.get(headerName.toLowerCase());
+				if (!val) return false;
+				return typeof headerValue === 'string' ? val === headerValue : headerValue.test(val);
+			},
+			apply,
+			priority,
+		};
+	}
+
+	static createMethodRule(methods: string | string[], apply: boolean, priority: number = 10): LayoutRule {
+		const normalizedMethods = new Set((Array.isArray(methods) ? methods : [methods]).map(m => m.toUpperCase()));
+		return {
+			matches: (route: RouteInfo) => normalizedMethods.has(route.method.toUpperCase()),
+			apply,
+			priority,
+		};
+	}
+
+	getDebugInfo(
+		layoutPath: string,
+		route: RouteInfo,
+	): {
+		totalRules: number;
+		matchingRules: Array<{ priority: number; apply: boolean }>;
+		finalDecision: boolean;
+		conflictResolution?: string;
+	} {
+		const matchingRules = this.getMatchingRules(route, layoutPath);
+		const finalDecision = this.shouldApplyLayout(layoutPath, route);
+		return {
+			totalRules: this.rules.length,
+			matchingRules: matchingRules.map(rule => ({ priority: rule.priority, apply: rule.apply })),
+			finalDecision,
+			conflictResolution: matchingRules.length > 1 ? 'priority-based' : 'single-rule',
+		};
+	}
+}

package/src/core/layout/layout-types.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared layout type definitions for the core/layout module.
+ *
+ * These are pure TypeScript interfaces with NO zod dependency,
+ * intentionally kept separate from schemas/layout.ts to avoid
+ * importing zod at cold start time.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentType<P = any> = ((props: P) => any) | (new (props: P) => any);
+
+export interface LayoutContext {
+	request: Request;
+	params: Record<string, string>;
+	query: URLSearchParams;
+	state: Map<string, unknown>;
+	middlewareContext?: unknown;
+}
+
+export type LayoutData = Record<string, unknown>;
+
+export type LayoutLoader = (ctx: LayoutContext) => Promise<LayoutData>;
+
+export interface LayoutProps {
+	children: import('preact').ComponentChildren;
+	data: LayoutData;
+	frontmatter?: Record<string, unknown>;
+	route: {
+		path: string;
+		params: Record<string, string>;
+		query: URLSearchParams;
+	};
+}
+
+export interface LayoutHandler {
+	component: ComponentType<LayoutProps>;
+	loader?: LayoutLoader;
+	path: string;
+	priority: number;
+}
+
+export interface LayoutRoute {
+	pattern: URLPattern;
+	layoutPath: string;
+	priority: number;
+	type: 'root' | 'nested';
+	depth: number;
+}
+
+export interface LayoutDiscoveryOptions {
+	baseDirectory: string;
+	filePattern?: string;
+	excludeDirectories?: string[];
+	enableWatching?: boolean;
+	developmentMode?: boolean;
+}
+
+export interface LayoutConfig {
+	skipLayouts?: string[];
+	replaceLayout?: boolean;
+	onlyLayouts?: string[];
+	customLayout?: string;
+}
+
+export interface RouteInfo {
+	path: string;
+	params: Record<string, string>;
+	method: string;
+	headers: Headers;
+}
+
+export interface LayoutRule {
+	matches: (route: RouteInfo, layoutPath?: string) => boolean;
+	apply: boolean;
+	priority: number;
+}
+
+export interface LayoutErrorInfo {
+	layoutPath: string;
+	errorType: 'component' | 'loader' | 'rendering' | 'island';
+	timestamp: number;
+	componentStack?: string;
+	errorBoundary?: string;
+}
+
+export interface ResolvedLayout {
+	handlers: LayoutHandler[];
+	dataLoaders: LayoutLoader[];
+	errorBoundaries: unknown[];
+	streamingComponents: unknown[];
+	metadata: {
+		totalLayouts: number;
+		resolutionTime: number;
+		cacheHit: boolean;
+	};
+}
+
+export interface LayoutCache {
+	resolved: Map<string, ResolvedLayout>;
+	handlers: Map<string, LayoutHandler>;
+	data: Map<string, LayoutData>;
+	ttl: Map<string, number>;
+}
+
+export interface PageModule {
+	default: ComponentType<Record<string, unknown>>;
+	layoutConfig?: LayoutConfig;
+	loader?: LayoutLoader;
+	frontmatter?: Record<string, unknown>;
+}