@useavalon/avalon 0.1.0

package/src/layout-system.d.ts

@@ -0,0 +1,592 @@
+/// <reference lib="dom" />
+/// <reference path="./types/urlpattern.d.ts" />
+/**
+ * Advanced Layout System - TypeScript Declarations
+ *
+ * This file provides comprehensive TypeScript declarations for the layout system,
+ * ensuring proper type checking and IntelliSense support.
+ */
+
+import type { ComponentType, ComponentChildren } from 'preact';
+import type { Component } from 'preact';
+
+// === Core Layout Types ===
+
+export interface LayoutContext {
+	request: Request;
+	params: Record<string, string>;
+	query: URLSearchParams;
+	state: Map<string, unknown>;
+	middlewareContext?: Record<string, unknown>;
+}
+
+export interface LayoutData {
+	[key: string]: unknown;
+}
+
+export interface LayoutRoute {
+	pattern: URLPattern;
+	layoutPath: string;
+	priority: number;
+	type: 'root' | 'nested';
+	depth: number;
+}
+
+export interface LayoutHandler {
+	component: ComponentType<LayoutProps>;
+	loader?: LayoutLoader;
+	path: string;
+	priority: number;
+}
+
+export interface LayoutProps {
+	children: ComponentChildren;
+	data: LayoutData;
+	route: {
+		path: string;
+		params: Record<string, string>;
+		query: URLSearchParams;
+	};
+}
+
+export interface LayoutDiscoveryOptions {
+	baseDirectory: string;
+	filePattern?: string;
+	excludeDirectories?: string[];
+	enableWatching?: boolean;
+	developmentMode?: boolean;
+}
+
+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 LayoutConfig {
+	skipLayouts?: string[];
+	replaceLayout?: boolean;
+	onlyLayouts?: string[];
+	customLayout?: string;
+}
+
+// === Function Types ===
+
+export type LayoutLoader = (ctx: LayoutContext) => Promise<LayoutData>;
+export type LayoutMatcherFunction = (route: RouteInfo, layoutPath?: string) => boolean;
+export type LayoutErrorHandler = (error: Error, errorInfo: LayoutErrorInfo) => void;
+export type LayoutRetryFunction = () => void;
+export type LayoutFallbackRenderer = (error: Error, retry: LayoutRetryFunction) => ComponentChildren;
+
+// === Persistent Islands Types ===
+
+export interface IslandState {
+	[key: string]: unknown;
+}
+
+export interface PersistentIslandProps {
+	persistentId: string;
+	children: ComponentChildren;
+}
+
+export interface PersistentIslandContext {
+	saveState: (state: IslandState) => void;
+	loadState: () => IslandState | null;
+	clearState: () => void;
+}
+
+export type IslandStateSaver = (state: IslandState) => void;
+export type IslandStateLoader = () => IslandState | null;
+export type IslandStateClearer = () => void;
+
+// === Error Boundary Types ===
+
+export interface LayoutErrorInfo {
+	layoutPath: string;
+	errorType: 'component' | 'loader' | 'rendering' | 'island';
+	timestamp: number;
+	componentStack?: string;
+	errorBoundary?: string;
+}
+
+export interface LayoutErrorBoundaryProps {
+	children: ComponentChildren;
+	fallback?: (error: Error, retry: () => void) => ComponentChildren;
+	onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+	recoveryStrategy?: ErrorRecoveryStrategy;
+	layoutPath?: string;
+	errorType?: 'component' | 'loader' | 'rendering' | 'island';
+}
+
+export interface ErrorRecoveryStrategy {
+	type: 'retry' | 'fallback' | 'skip' | 'redirect';
+	maxRetries?: number;
+	fallbackComponent?: ComponentType;
+	redirectUrl?: string;
+}
+
+// === Streaming Types ===
+
+export interface StreamingLayoutProps {
+	children: ComponentChildren;
+	fallback?: ComponentChildren;
+	priority?: 'high' | 'medium' | 'low';
+}
+
+export interface StreamingComponent {
+	component: ComponentType;
+	fallback: ComponentType;
+	priority: number;
+	isReady: () => Promise<boolean>;
+}
+
+export type StreamingReadyCheck = () => Promise<boolean>;
+
+// === Resolution Types ===
+
+export interface ResolvedLayout {
+	handlers: LayoutHandler[];
+	dataLoaders: LayoutLoader[];
+	errorBoundaries: ComponentType<LayoutErrorBoundaryProps>[];
+	streamingComponents: StreamingComponent[];
+	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 EnhancedLayoutContext extends LayoutContext {
+	layouts: LayoutHandler[];
+	parentData: LayoutData[];
+	islandStates: Map<string, IslandState>;
+	streamingEnabled: boolean;
+	errorBoundaries: ComponentType<LayoutErrorBoundaryProps>[];
+}
+
+// === Interface Definitions ===
+
+export interface ILayoutDiscovery {
+	discoverLayouts(routePath: string): Promise<LayoutRoute[]>;
+	buildLayoutChain(url: URL): Promise<LayoutHandler[]>;
+	setWatching(enabled: boolean): void;
+	getOptions(): LayoutDiscoveryOptions;
+}
+
+export interface ILayoutMatcher {
+	addRule(rule: LayoutRule): void;
+	removeRule(rule: LayoutRule): void;
+	shouldApplyLayout(layoutPath: string, route: RouteInfo): boolean;
+	getRules(): LayoutRule[];
+	clearRules(): void;
+}
+
+export interface ILayoutComposer {
+	resolveLayouts(routePath: string, pageModule: PageModule): Promise<LayoutHandler[]>;
+	applyConfiguration(layouts: LayoutHandler[], config: LayoutConfig): Promise<LayoutHandler[]>;
+	validateLayoutConfig(config: LayoutConfig): { valid: boolean; errors: string[] };
+	clearCache(): void;
+	getCompositionStats(): {
+		customLayoutCacheSize: number;
+		discoveryStats: { layoutCount: number; routeCacheCount: number };
+	};
+}
+
+export interface IIslandPersistence {
+	saveState(id: string, state: IslandState): void;
+	loadState(id: string): IslandState | null;
+	clearState(id: string): void;
+	hasState(id: string): boolean;
+	getStoredIds(): string[];
+	clearAllStates(): void;
+}
+
+export interface ILayoutErrorRecovery {
+	handleLayoutError(error: Error, context: LayoutContext): Promise<Response>;
+	registerStrategy(errorType: string, strategy: ErrorRecoveryStrategy): void;
+	getStrategy(error: Error): ErrorRecoveryStrategy | null;
+}
+
+export interface ILayoutStreaming {
+	renderWithStreaming(layout: LayoutHandler, props: LayoutProps): Promise<ReadableStream>;
+	isStreamingSupported(): boolean;
+	createStreamingResponse(components: StreamingComponent[]): ReadableStream;
+	generateSkeleton(component: StreamingComponent): string;
+}
+
+export interface IEnhancedLayoutResolver {
+	resolveAndRender(routePath: string, pageModule: PageModule, context: LayoutContext): Promise<ResolvedLayout>;
+	getCachedResolution(routePath: string): ResolvedLayout | null;
+	clearCache(): void;
+	setCaching(enabled: boolean): void;
+}
+
+// === Component Interface Definitions ===
+
+export interface ILayoutComponent {
+	props: LayoutProps;
+	layoutLoader?: LayoutLoader;
+	layoutConfig?: LayoutConfig;
+}
+
+export interface IPersistentIslandComponent {
+	props: PersistentIslandProps;
+	saveState(): void;
+	loadState(): void;
+	clearState(): void;
+	hasState(): boolean;
+}
+
+export interface ILayoutErrorBoundaryComponent extends Component<LayoutErrorBoundaryProps> {
+	handleRetry(): void;
+	getErrorState(): { hasError: boolean; error?: Error };
+	resetErrorState(): void;
+}
+
+export interface IStreamingLayoutComponent {
+	props: StreamingLayoutProps;
+	isReady(): Promise<boolean>;
+	renderFallback(): ComponentChildren;
+	getPriority(): number;
+}
+
+// === Utility Type Definitions ===
+
+export interface LayoutModule {
+	default: ComponentType<LayoutProps>;
+	layoutLoader?: LayoutLoader;
+	layoutConfig?: LayoutConfig;
+	ErrorBoundary?: ComponentType<LayoutErrorBoundaryProps>;
+}
+
+export interface PageModule {
+	default: ComponentType<Record<string, unknown>>;
+	layoutConfig?: LayoutConfig;
+	loader?: (ctx: LayoutContext) => Promise<LayoutData>;
+}
+
+export interface LayoutResolutionContext {
+	route: RouteInfo;
+	pageModule: PageModule;
+	layoutContext: LayoutContext;
+	cachingEnabled: boolean;
+	streamingEnabled: boolean;
+	developmentMode: boolean;
+}
+
+export interface LayoutPerformanceMetrics {
+	discoveryTime: number;
+	dataLoadingTime: number;
+	renderingTime: number;
+	totalTime: number;
+	layoutCount: number;
+	cacheHit: boolean;
+	memoryUsage?: number;
+}
+
+export interface LayoutDebugInfo {
+	resolutionChain: string[];
+	appliedRules: LayoutRule[];
+	skippedLayouts: string[];
+	errors: LayoutErrorInfo[];
+	metrics: LayoutPerformanceMetrics;
+	cacheInfo: {
+		hit: boolean;
+		key: string;
+		size: number;
+	};
+}
+
+// === Event Type Definitions ===
+
+export type LayoutEventType =
+	| 'layout-discovered'
+	| 'layout-loaded'
+	| 'layout-rendered'
+	| 'layout-error'
+	| 'layout-cached'
+	| 'island-state-saved'
+	| 'island-state-loaded'
+	| 'streaming-started'
+	| 'streaming-completed';
+
+export interface LayoutEventData {
+	type: LayoutEventType;
+	timestamp: number;
+	layoutPath?: string;
+	error?: Error;
+	metrics?: LayoutPerformanceMetrics;
+	data?: unknown;
+}
+
+export type LayoutEventHandler = (event: LayoutEventData) => void;
+
+export interface ILayoutEventEmitter {
+	on(event: LayoutEventType, handler: LayoutEventHandler): void;
+	off(event: LayoutEventType, handler: LayoutEventHandler): void;
+	emit(event: LayoutEventType, data?: unknown): void;
+	removeAllListeners(): void;
+}
+
+// === Utility Types ===
+
+export interface LayoutUtilitiesConfig {
+	cache?: CacheConfig;
+	debug?: DebugConfig;
+	performance?: PerformanceConfig;
+	validation?: ValidationConfig;
+}
+
+export interface LayoutUtilitiesSuite {
+	cache: CacheConfig;
+	debug: DebugConfig;
+	performance: PerformanceConfig;
+	validation: ValidationConfig;
+}
+
+export interface CacheConfig {
+	maxSize?: number;
+	ttl?: number;
+	cleanupInterval?: number;
+}
+
+export interface DebugConfig {
+	enabled?: boolean;
+	logLevel?: 'error' | 'warn' | 'info' | 'debug';
+	includeStackTrace?: boolean;
+}
+
+export interface PerformanceConfig {
+	monitoring?: boolean;
+	thresholds?: PerformanceThresholds;
+	alerting?: boolean;
+}
+
+export interface ValidationConfig {
+	strict?: boolean;
+	warnings?: boolean;
+	customRules?: ValidationRule[];
+}
+
+export interface PerformanceThresholds {
+	discoveryTime?: number;
+	dataLoadingTime?: number;
+	renderingTime?: number;
+	totalTime?: number;
+}
+
+export interface ValidationRule {
+	name: string;
+	validate: (config: LayoutConfig) => ValidationResult;
+}
+
+export interface ValidationResult {
+	isValid: boolean;
+	errors: ValidationError[];
+	warnings: ValidationWarning[];
+}
+
+export interface ValidationError {
+	field: string;
+	message: string;
+	code: string;
+}
+
+export interface ValidationWarning {
+	field: string;
+	message: string;
+	code: string;
+}
+
+// === Class Declarations ===
+
+export declare class LayoutDiscovery implements ILayoutDiscovery {
+	constructor(options: LayoutDiscoveryOptions);
+	discoverLayouts(routePath: string): Promise<LayoutRoute[]>;
+	buildLayoutChain(url: URL): Promise<LayoutHandler[]>;
+	setWatching(enabled: boolean): void;
+	getOptions(): LayoutDiscoveryOptions;
+}
+
+export declare class LayoutMatcher implements ILayoutMatcher {
+	constructor();
+	addRule(rule: LayoutRule): void;
+	removeRule(rule: LayoutRule): void;
+	shouldApplyLayout(layoutPath: string, route: RouteInfo): boolean;
+	getRules(): LayoutRule[];
+	clearRules(): void;
+}
+
+export declare class LayoutComposer implements ILayoutComposer {
+	constructor();
+	resolveLayouts(routePath: string, pageModule: PageModule): Promise<LayoutHandler[]>;
+	applyConfiguration(layouts: LayoutHandler[], config: LayoutConfig): Promise<LayoutHandler[]>;
+	validateLayoutConfig(config: LayoutConfig): { valid: boolean; errors: string[] };
+	clearCache(): void;
+	getCompositionStats(): {
+		customLayoutCacheSize: number;
+		discoveryStats: { layoutCount: number; routeCacheCount: number };
+	};
+}
+
+export declare class IslandPersistence implements IIslandPersistence {
+	constructor();
+	saveState(id: string, state: IslandState): void;
+	loadState(id: string): IslandState | null;
+	clearState(id: string): void;
+	hasState(id: string): boolean;
+	getStoredIds(): string[];
+	clearAllStates(): void;
+}
+
+export declare class LayoutErrorRecovery implements ILayoutErrorRecovery {
+	constructor();
+	handleLayoutError(error: Error, context: LayoutContext): Promise<Response>;
+	registerStrategy(errorType: string, strategy: ErrorRecoveryStrategy): void;
+	getStrategy(error: Error): ErrorRecoveryStrategy | null;
+}
+
+export declare class LayoutStreaming implements ILayoutStreaming {
+	constructor();
+	renderWithStreaming(layout: LayoutHandler, props: LayoutProps): Promise<ReadableStream>;
+	isStreamingSupported(): boolean;
+	createStreamingResponse(components: StreamingComponent[]): ReadableStream;
+	generateSkeleton(component: StreamingComponent): string;
+}
+
+export declare class EnhancedLayoutResolver implements IEnhancedLayoutResolver {
+	constructor(options?: LayoutDiscoveryOptions);
+	resolveAndRender(routePath: string, pageModule: PageModule, context: LayoutContext): Promise<ResolvedLayout>;
+	getCachedResolution(routePath: string): ResolvedLayout | null;
+	clearCache(): void;
+	setCaching(enabled: boolean): void;
+}
+
+// === Component Declarations ===
+
+export declare class LayoutErrorBoundary
+	extends Component<LayoutErrorBoundaryProps>
+	implements ILayoutErrorBoundaryComponent
+{
+	constructor(props: LayoutErrorBoundaryProps);
+	render(): ComponentChildren;
+	handleRetry(): void;
+	getErrorState(): { hasError: boolean; error?: Error };
+	resetErrorState(): void;
+}
+
+export declare class PersistentIsland extends Component<PersistentIslandProps> implements IPersistentIslandComponent {
+	constructor(props: PersistentIslandProps);
+	render(): ComponentChildren;
+	saveState(): void;
+	loadState(): void;
+	clearState(): void;
+	hasState(): boolean;
+}
+
+export declare function StreamingLayout(props: StreamingLayoutProps): ComponentChildren;
+
+// === Factory Functions ===
+
+export declare function createEnhancedLayoutResolver(options?: LayoutDiscoveryOptions): EnhancedLayoutResolver;
+export declare function createLayoutDataLoader(options?: LayoutDiscoveryOptions): LayoutLoader;
+export declare function createLayoutUtilities(config?: LayoutUtilitiesConfig): LayoutUtilitiesSuite;
+export declare function createPersistentIslandContext(
+	persistentId: string,
+	persistence?: IslandPersistence,
+): PersistentIslandContext;
+
+// === Hook Declarations ===
+
+export declare function usePersistentIslandContext(): PersistentIslandContext;
+export declare function useStreamingState(): { isReady: boolean; error?: Error };
+
+// === Utility Functions ===
+
+export declare function validateLayoutConfiguration(config: LayoutConfig): ValidationResult;
+export declare function getLayoutSystemHealthReport(): {
+	healthy: boolean;
+	metrics: LayoutPerformanceMetrics;
+	errors: LayoutErrorInfo[];
+};
+export declare function withLayoutUtilities<P = Record<string, unknown>>(component: ComponentType<P>): ComponentType<P>;
+export declare function withStreaming<P = Record<string, unknown>>(component: ComponentType<P>): ComponentType<P>;
+export declare function withIslandErrorBoundary<P = Record<string, unknown>>(
+	component: ComponentType<P>,
+): ComponentType<P>;
+
+// === Constants ===
+
+export declare const LAYOUT_SYSTEM_VERSION: string;
+export declare const LAYOUT_SYSTEM_FEATURES: {
+	readonly DISCOVERY: true;
+	readonly DATA_LOADING: true;
+	readonly CONDITIONAL_RENDERING: true;
+	readonly COMPOSITION_CONTROL: true;
+	readonly PERSISTENT_ISLANDS: true;
+	readonly ERROR_BOUNDARIES: true;
+	readonly STREAMING: true;
+	readonly CACHING: true;
+	readonly PERFORMANCE_MONITORING: true;
+	readonly DEBUG_UTILITIES: true;
+};
+
+export declare const LAYOUT_SYSTEM_DEFAULTS: {
+	readonly DISCOVERY: {
+		readonly baseDirectory: 'src/pages';
+		readonly filePattern: '_layout.tsx';
+		readonly excludeDirectories: readonly ['node_modules', '.git', 'dist'];
+		readonly enableWatching: false;
+		readonly developmentMode: false;
+	};
+	readonly CACHING: {
+		readonly enabled: true;
+		readonly ttl: 300000;
+		readonly maxSize: 100;
+		readonly cleanupInterval: 60000;
+	};
+	readonly STREAMING: {
+		readonly enabled: true;
+		readonly priority: 'medium';
+		readonly timeout: 5000;
+	};
+	readonly ERROR_BOUNDARIES: {
+		readonly enabled: true;
+		readonly maxRetries: 3;
+		readonly fallbackStrategy: 'component';
+	};
+	readonly PERFORMANCE: {
+		readonly monitoring: true;
+		readonly thresholds: {
+			readonly discoveryTime: 100;
+			readonly dataLoadingTime: 500;
+			readonly renderingTime: 200;
+			readonly totalTime: 1000;
+		};
+	};
+};
+
+// === Default Instances ===
+
+export declare const defaultLayoutSystem: EnhancedLayoutResolver;
+export declare const defaultPersistence: IslandPersistence;
+export declare const defaultUtilities: LayoutUtilitiesSuite;
+
+// === Convenience Aliases ===
+
+export { EnhancedLayoutResolver as LayoutSystem };
+export { createEnhancedLayoutResolver as createLayoutSystem };