@useavalon/avalon 0.1.0

package/src/components/IslandErrorBoundary.tsx

@@ -0,0 +1,145 @@
+import { Component, ComponentChildren, ComponentType } from 'preact';
+import type { LayoutErrorInfo } from '../types/layout.ts';
+
+export interface IslandErrorBoundaryProps {
+	children: ComponentChildren;
+	islandId: string;
+	onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+	fallback?: (error: Error, islandId: string) => ComponentChildren;
+	isolateError?: boolean;
+}
+
+export interface IslandErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+	errorInfo: LayoutErrorInfo | null;
+}
+
+/**
+ * Specialized error boundary for island components
+ * Provides error isolation to prevent island errors from affecting the main layout
+ */
+export class IslandErrorBoundary extends Component<IslandErrorBoundaryProps, IslandErrorBoundaryState> {
+	constructor(props: IslandErrorBoundaryProps) {
+		super(props);
+		this.state = { hasError: false, error: null, errorInfo: null };
+	}
+
+	static override getDerivedStateFromError(error: Error): Partial<IslandErrorBoundaryState> {
+		return { hasError: true, error };
+	}
+
+	override componentDidCatch(error: Error, errorInfo: { componentStack?: string }): void {
+		const layoutErrorInfo: LayoutErrorInfo = {
+			layoutPath: `island:${this.props.islandId}`,
+			errorType: 'island',
+			timestamp: Date.now(),
+			componentStack: errorInfo.componentStack,
+			errorBoundary: 'IslandErrorBoundary',
+		};
+
+		this.setState({ errorInfo: layoutErrorInfo });
+
+		if (this.props.onError) {
+			this.props.onError(error, layoutErrorInfo);
+		}
+
+		const isDevelopment = typeof Deno !== 'undefined' && Deno.env.get('NODE_ENV') === 'development';
+		if (isDevelopment) {
+			console.error(`Island Error [${this.props.islandId}]:`, error);
+		}
+
+		if (!this.props.isolateError) {
+			throw error;
+		}
+	}
+
+	private handleRemoveIsland = (): void => {
+		const islandElement = document.querySelector(`[data-island-id="${this.props.islandId}"]`);
+		if (islandElement) {
+			islandElement.remove();
+		}
+	};
+
+	private handleReloadIsland = (): void => {
+		this.setState({ hasError: false, error: null, errorInfo: null });
+	};
+
+	private renderFallback(): ComponentChildren {
+		const { error } = this.state;
+		const { fallback, islandId } = this.props;
+
+		if (fallback && error) {
+			return fallback(error, islandId);
+		}
+
+		const isDevelopment = typeof Deno !== 'undefined' && Deno.env.get('NODE_ENV') === 'development';
+
+		return (
+			<div class="island-error-boundary" data-island-error={islandId}>
+				<div class="island-error-container">
+					<div class="island-error-header">
+						<span class="island-error-icon">⚠️</span>
+						<span class="island-error-title">Island Error</span>
+					</div>
+
+					<p class="island-error-message">
+						An error occurred in island "{islandId}". The rest of the page should work normally.
+					</p>
+
+					<div class="island-error-actions">
+						<button onClick={this.handleReloadIsland} class="island-reload-button">
+							Reload Island
+						</button>
+						<button onClick={this.handleRemoveIsland} class="island-remove-button">
+							Remove Island
+						</button>
+					</div>
+
+					{isDevelopment && error && (
+						<details class="island-error-details">
+							<summary>Error Details (Development)</summary>
+							<div class="island-error-info">
+								<p><strong>Island ID:</strong> {islandId}</p>
+								<p><strong>Error:</strong> {error.message}</p>
+							</div>
+							<pre class="island-error-stack">{error.stack}</pre>
+						</details>
+					)}
+				</div>
+			</div>
+		);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return this.renderFallback();
+		}
+		return this.props.children;
+	}
+}
+
+/**
+ * Higher-order component to wrap islands with error boundaries
+ */
+export function withIslandErrorBoundary<P extends object>(
+	WrappedComponent: ComponentType<P>,
+	islandId: string,
+	options?: {
+		fallback?: (error: Error, islandId: string) => ComponentChildren;
+		isolateError?: boolean;
+		onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+	}
+) {
+	return function IslandWithErrorBoundary(props: P) {
+		return (
+			<IslandErrorBoundary
+				islandId={islandId}
+				fallback={options?.fallback}
+				isolateError={options?.isolateError ?? true}
+				onError={options?.onError}>
+				<WrappedComponent {...props} />
+			</IslandErrorBoundary>
+		);
+	};
+}

package/src/components/LayoutDataErrorBoundary.tsx

@@ -0,0 +1,141 @@
+import { Component, ComponentChildren } from 'preact';
+import type { LayoutErrorInfo, LayoutContext, LayoutData } from '../types/layout.ts';
+
+export interface LayoutDataErrorBoundaryProps {
+	children: ComponentChildren;
+	layoutPath: string;
+	context: LayoutContext;
+	onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+	fallbackData?: LayoutData;
+	retryLoader?: () => Promise<LayoutData>;
+}
+
+export interface LayoutDataErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+	errorInfo: LayoutErrorInfo | null;
+	retryCount: number;
+	isRetrying: boolean;
+	fallbackData: LayoutData | null;
+}
+
+/**
+ * Specialized error boundary for layout data loading errors
+ * Provides specific handling for data loader failures with retry and fallback mechanisms
+ */
+export class LayoutDataErrorBoundary extends Component<LayoutDataErrorBoundaryProps, LayoutDataErrorBoundaryState> {
+	private maxRetries = 3;
+
+	constructor(props: LayoutDataErrorBoundaryProps) {
+		super(props);
+		this.state = {
+			hasError: false,
+			error: null,
+			errorInfo: null,
+			retryCount: 0,
+			isRetrying: false,
+			fallbackData: props.fallbackData || null,
+		};
+	}
+
+	static override getDerivedStateFromError(error: Error): Partial<LayoutDataErrorBoundaryState> {
+		return { hasError: true, error };
+	}
+
+	override componentDidCatch(error: Error, errorInfo: { componentStack?: string }): void {
+		const layoutErrorInfo: LayoutErrorInfo = {
+			layoutPath: this.props.layoutPath,
+			errorType: 'loader',
+			timestamp: Date.now(),
+			componentStack: errorInfo.componentStack,
+			errorBoundary: 'LayoutDataErrorBoundary',
+		};
+
+		this.setState({ errorInfo: layoutErrorInfo });
+
+		if (this.props.onError) {
+			this.props.onError(error, layoutErrorInfo);
+		}
+	}
+
+	private handleRetry = async (): Promise<void> => {
+		if (this.state.retryCount >= this.maxRetries || !this.props.retryLoader) {
+			return;
+		}
+
+		this.setState({ isRetrying: true });
+
+		try {
+			const data = await this.props.retryLoader();
+			this.setState({
+				hasError: false,
+				error: null,
+				errorInfo: null,
+				retryCount: this.state.retryCount + 1,
+				isRetrying: false,
+				fallbackData: data,
+			});
+		} catch (retryError) {
+			this.setState({
+				retryCount: this.state.retryCount + 1,
+				isRetrying: false,
+				error: retryError instanceof Error ? retryError : new Error(String(retryError)),
+			});
+		}
+	};
+
+	private handleUseFallback = (): void => {
+		if (this.state.fallbackData) {
+			this.setState({ hasError: false, error: null, errorInfo: null });
+		}
+	};
+
+	private renderErrorUI(): ComponentChildren {
+		const { error, retryCount, isRetrying, fallbackData } = this.state;
+		const canRetry = retryCount < this.maxRetries && this.props.retryLoader;
+		const hasFallback = fallbackData !== null;
+		const isDevelopment = typeof Deno !== 'undefined' && Deno.env.get('NODE_ENV') === 'development';
+
+		return (
+			<div class="layout-data-error-boundary">
+				<div class="error-container">
+					<h3>Data Loading Error</h3>
+					<p>Failed to load data for layout: {this.props.layoutPath}</p>
+
+					<div class="error-actions">
+						{canRetry && (
+							<button onClick={this.handleRetry} disabled={isRetrying} class="retry-button">
+								{isRetrying ? 'Retrying...' : `Retry (${this.maxRetries - retryCount} left)`}
+							</button>
+						)}
+
+						{hasFallback && (
+							<button onClick={this.handleUseFallback} class="fallback-button">
+								Use Cached Data
+							</button>
+						)}
+					</div>
+
+					{isDevelopment && error && (
+						<details class="error-details">
+							<summary>Error Details (Development)</summary>
+							<div class="error-info">
+								<p><strong>Error:</strong> {error.message}</p>
+								<p><strong>Layout:</strong> {this.props.layoutPath}</p>
+								<p><strong>Retry Count:</strong> {retryCount}</p>
+							</div>
+							<pre class="error-stack">{error.stack}</pre>
+						</details>
+					)}
+				</div>
+			</div>
+		);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return this.renderErrorUI();
+		}
+		return this.props.children;
+	}
+}

package/src/components/LayoutErrorBoundary.tsx

@@ -0,0 +1,127 @@
+import { Component, ComponentChildren } from 'preact';
+import type { LayoutErrorInfo, ErrorRecoveryStrategy } from '../types/layout.ts';
+
+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 LayoutErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+	errorInfo: LayoutErrorInfo | null;
+	retryCount: number;
+}
+
+export class LayoutErrorBoundary extends Component<LayoutErrorBoundaryProps, LayoutErrorBoundaryState> {
+	private maxRetries = 3;
+
+	constructor(props: LayoutErrorBoundaryProps) {
+		super(props);
+		this.state = {
+			hasError: false,
+			error: null,
+			errorInfo: null,
+			retryCount: 0,
+		};
+	}
+
+	static override getDerivedStateFromError(error: Error): Partial<LayoutErrorBoundaryState> {
+		return {
+			hasError: true,
+			error,
+		};
+	}
+
+	override componentDidCatch(error: Error, errorInfo: any): void {
+		const layoutErrorInfo: LayoutErrorInfo = {
+			layoutPath: this.props.layoutPath || 'unknown',
+			errorType: this.props.errorType || 'component',
+			timestamp: Date.now(),
+			componentStack: errorInfo.componentStack,
+			errorBoundary: this.constructor.name,
+		};
+
+		this.setState({
+			errorInfo: layoutErrorInfo,
+		});
+
+		// Call onError callback if provided
+		if (this.props.onError) {
+			this.props.onError(error, layoutErrorInfo);
+		}
+
+		// Log error in development mode
+		if (typeof Deno !== 'undefined' && Deno.env.get('NODE_ENV') === 'development') {
+			console.error('Layout Error Boundary caught an error:', error);
+			console.error('Error Info:', layoutErrorInfo);
+			console.error('Component Stack:', errorInfo.componentStack);
+		}
+	}
+
+	private handleRetry = (): void => {
+		if (this.state.retryCount < this.maxRetries) {
+			this.setState({
+				hasError: false,
+				error: null,
+				errorInfo: null,
+				retryCount: this.state.retryCount + 1,
+			});
+		}
+	};
+
+	private renderFallback(): ComponentChildren {
+		const { error } = this.state;
+		const { fallback } = this.props;
+
+		if (fallback && error) {
+			return fallback(error, this.handleRetry);
+		}
+
+		// Default fallback UI
+		return (
+			<div class="layout-error-boundary">
+				<div class="error-container">
+					<h2>Something went wrong</h2>
+					<p>An error occurred while rendering this layout.</p>
+					{this.state.retryCount < this.maxRetries && (
+						<button onClick={this.handleRetry} class="retry-button">
+							Try Again ({this.maxRetries - this.state.retryCount} attempts left)
+						</button>
+					)}
+					{typeof Deno !== 'undefined' && Deno.env.get('NODE_ENV') === 'development' && (
+						<details class="error-details">
+							<summary>Error Details (Development)</summary>
+							<pre>{error?.stack}</pre>
+							{this.state.errorInfo && (
+								<div>
+									<p>
+										<strong>Layout Path:</strong> {this.state.errorInfo.layoutPath}
+									</p>
+									<p>
+										<strong>Error Type:</strong> {this.state.errorInfo.errorType}
+									</p>
+									<p>
+										<strong>Timestamp:</strong> {new Date(this.state.errorInfo.timestamp).toISOString()}
+									</p>
+								</div>
+							)}
+						</details>
+					)}
+				</div>
+			</div>
+		);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return this.renderFallback();
+		}
+
+		return this.props.children;
+	}
+}

package/src/components/PersistentIsland.tsx

@@ -0,0 +1,52 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from 'preact';
+import { PersistentIslandProvider } from '../core/islands/persistent-island-context.tsx';
+import { defaultIslandPersistence, type IslandPersistence } from '../core/islands/island-persistence.ts';
+
+interface PersistentIslandProps {
+	/** Unique ID used as the storage key for this island's state */
+	persistentId: string;
+	/** The island component(s) to wrap with persistence context */
+	children: ComponentChildren;
+	/** Custom persistence instance (defaults to sessionStorage-backed) */
+	persistence?: IslandPersistence;
+}
+
+/**
+ * PersistentIsland — provides automatic state persistence context to child islands.
+ *
+ * Wrap any island with this component and use `usePersistentIslandContext()` inside
+ * the island to get `saveState`, `loadState`, and `clearState` functions.
+ *
+ * Usage in a page:
+ * ```tsx
+ * <PersistentIsland persistentId="my-counter" island={{ condition: 'on:client' }}>
+ *   <MyCounter />
+ * </PersistentIsland>
+ * ```
+ *
+ * Usage inside the island:
+ * ```tsx
+ * import { usePersistentIslandContext } from '@useavalon/avalon';
+ *
+ * function MyCounter() {
+ *   const { saveState, loadState, clearState } = usePersistentIslandContext();
+ *   // ...
+ * }
+ * ```
+ */
+export function PersistentIsland({
+	persistentId,
+	children,
+	persistence = defaultIslandPersistence,
+}: Readonly<PersistentIslandProps>) {
+	return (
+		<PersistentIslandProvider persistentId={persistentId} persistence={persistence}>
+			<div data-persistent-id={persistentId}>
+				{children}
+			</div>
+		</PersistentIslandProvider>
+	);
+}
+
+export default PersistentIsland;

package/src/components/StreamingErrorBoundary.tsx

@@ -0,0 +1,233 @@
+/**
+ * StreamingErrorBoundary - Error boundary component for streaming contexts
+ * 
+ * This component provides error isolation for Suspense boundaries in streaming SSR.
+ * It ensures that errors in one component don't break the entire page.
+ */
+
+import { Component, type ComponentChildren } from 'preact';
+
+export interface StreamingErrorBoundaryProps {
+	children: ComponentChildren;
+	fallback?: (error: Error, retry: () => void) => ComponentChildren;
+	onError?: (error: Error, errorInfo: any) => void;
+	componentId?: string;
+	isolateError?: boolean; // If true, error won't propagate to parent
+}
+
+export interface StreamingErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+	errorInfo: any;
+}
+
+/**
+ * Error boundary component for streaming contexts
+ * 
+ * Wraps Suspense boundaries to provide error isolation and recovery.
+ * Prevents errors in one component from breaking the entire page.
+ */
+export class StreamingErrorBoundary extends Component<
+	StreamingErrorBoundaryProps,
+	StreamingErrorBoundaryState
+> {
+	constructor(props: StreamingErrorBoundaryProps) {
+		super(props);
+		this.state = {
+			hasError: false,
+			error: null,
+			errorInfo: null,
+		};
+	}
+
+	static override getDerivedStateFromError(error: Error): Partial<StreamingErrorBoundaryState> {
+		return {
+			hasError: true,
+			error,
+		};
+	}
+
+	override componentDidCatch(error: Error, errorInfo: any): void {
+		this.setState({
+			errorInfo,
+		});
+
+		// Log the error
+		console.error('[StreamingErrorBoundary] Caught error:', {
+			componentId: this.props.componentId,
+			error: error.message,
+			stack: error.stack,
+			componentStack: errorInfo.componentStack,
+		});
+
+		// Call onError callback if provided
+		if (this.props.onError) {
+			this.props.onError(error, errorInfo);
+		}
+
+		// If isolateError is false, re-throw to propagate to parent
+		if (!this.props.isolateError) {
+			throw error;
+		}
+	}
+
+	private handleRetry = (): void => {
+		this.setState({
+			hasError: false,
+			error: null,
+			errorInfo: null,
+		});
+	};
+
+	private renderFallback(): ComponentChildren {
+		const { error } = this.state;
+		const { fallback, componentId } = this.props;
+
+		if (fallback && error) {
+			return fallback(error, this.handleRetry);
+		}
+
+		// Default fallback UI
+		const isDevelopment = typeof Deno !== 'undefined' && Deno.env.get('DENO_ENV') !== 'production';
+
+		return (
+			<div
+				class="streaming-error-boundary"
+				data-error-boundary="true"
+				data-component-id={componentId}
+				style={{
+					background: '#fff3cd',
+					border: '2px solid #ffc107',
+					borderRadius: '8px',
+					padding: '20px',
+					margin: '20px 0',
+					fontFamily: 'system-ui, -apple-system, sans-serif',
+				}}
+			>
+				<div
+					class="error-boundary-header"
+					style={{
+						display: 'flex',
+						alignItems: 'center',
+						gap: '10px',
+						marginBottom: '10px',
+					}}
+				>
+					<span style={{ fontSize: '24px' }}>⚠️</span>
+					<h3 style={{ margin: 0, color: '#856404' }}>Component Error</h3>
+				</div>
+
+				<p style={{ margin: '10px 0', color: '#856404' }}>
+					An error occurred while rendering this component. The rest of the page should work normally.
+				</p>
+
+				<button
+					onClick={this.handleRetry}
+					style={{
+						background: '#ffc107',
+						border: 'none',
+						borderRadius: '4px',
+						padding: '8px 16px',
+						cursor: 'pointer',
+						fontWeight: 'bold',
+						color: '#856404',
+						marginTop: '10px',
+					}}
+				>
+					Retry
+				</button>
+
+				{isDevelopment && error && (
+					<details style={{ marginTop: '15px' }}>
+						<summary
+							style={{
+								cursor: 'pointer',
+								color: '#856404',
+								fontWeight: 'bold',
+							}}
+						>
+							Error Details (Development Mode)
+						</summary>
+						<div style={{ marginTop: '10px' }}>
+							{componentId && (
+								<p>
+									<strong>Component ID:</strong> {componentId}
+								</p>
+							)}
+							<p>
+								<strong>Error:</strong> {error.message}
+							</p>
+							{error.stack && (
+								<pre
+									style={{
+										background: '#f5f5f5',
+										padding: '10px',
+										borderRadius: '4px',
+										overflowX: 'auto',
+										fontSize: '12px',
+										marginTop: '10px',
+									}}
+								>
+									{error.stack}
+								</pre>
+							)}
+							{this.state.errorInfo?.componentStack && (
+								<div>
+									<p>
+										<strong>Component Stack:</strong>
+									</p>
+									<pre
+										style={{
+											background: '#f5f5f5',
+											padding: '10px',
+											borderRadius: '4px',
+											overflowX: 'auto',
+											fontSize: '12px',
+											marginTop: '10px',
+										}}
+									>
+										{this.state.errorInfo.componentStack}
+									</pre>
+								</div>
+							)}
+						</div>
+					</details>
+				)}
+			</div>
+		);
+	}
+
+	render() {
+		if (this.state.hasError) {
+			return this.renderFallback();
+		}
+
+		return this.props.children;
+	}
+}
+
+/**
+ * Higher-order component to wrap components with streaming error boundaries
+ */
+export function withStreamingErrorBoundary<P extends object>(
+	WrappedComponent: (props: P) => ComponentChildren,
+	options?: {
+		fallback?: (error: Error, retry: () => void) => ComponentChildren;
+		componentId?: string;
+		isolateError?: boolean;
+		onError?: (error: Error, errorInfo: any) => void;
+	}
+) {
+	return function ComponentWithErrorBoundary(props: P) {
+		return (
+			<StreamingErrorBoundary
+				componentId={options?.componentId}
+				fallback={options?.fallback}
+				isolateError={options?.isolateError ?? true}
+				onError={options?.onError}
+			>
+				<WrappedComponent {...props} />
+			</StreamingErrorBoundary>
+		);
+	};
+}