@useavalon/avalon 0.1.12 → 0.1.13

package/src/components/Image.tsx

@@ -0,0 +1,123 @@
+/**
+ * Image Component for Avalon
+ *
+ * A responsive image component that works with vite-imagetools to provide
+ * optimized images with automatic srcset generation.
+ *
+ * Usage:
+ * ```tsx
+ * import { Image } from '@useavalon/avalon/client';
+ * import heroSrc from './hero.jpg?w=400;800;1200&format=webp&as=srcset';
+ *
+ * <Image
+ *   src={heroSrc}
+ *   alt="Hero image"
+ *   sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
+ * />
+ * ```
+ *
+ * Or with the simpler single-image approach:
+ * ```tsx
+ * import heroSrc from './hero.jpg?w=800&format=webp';
+ *
+ * <Image src={heroSrc} alt="Hero image" width={800} height={600} />
+ * ```
+ */
+
+import type { JSX } from "preact";
+
+export interface ImageProps {
+  /** 
+   * Image source - can be:
+   * - A string URL (single image)
+   * - A srcset string from ?as=srcset (contains " Xw" width descriptors)
+   * - An object with src/srcset/width/height from vite-imagetools
+   */
+  src: string | { src: string; srcset?: string; width?: number; height?: number };
+
+  /** Alt text for accessibility (required) */
+  alt: string;
+
+  /** Sizes attribute for responsive images (required when using srcset) */
+  sizes?: string;
+
+  /** Loading strategy */
+  loading?: "lazy" | "eager";
+
+  /** Decoding hint */
+  decoding?: "async" | "sync" | "auto";
+
+  /** Optional width (auto-detected from srcset if available) */
+  width?: number | string;
+
+  /** Optional height (auto-detected from srcset if available) */
+  height?: number | string;
+
+  /** CSS class name */
+  className?: string;
+
+  /** Inline styles */
+  style?: string | Record<string, string | number>;
+}
+
+/**
+ * Check if a string looks like a srcset (contains width descriptors like "400w")
+ */
+function isSrcsetString(value: string): boolean {
+  return /\s\d+w/.test(value);
+}
+
+/**
+ * Responsive image component with built-in optimization support
+ */
+export function Image({
+  src,
+  alt,
+  sizes,
+  loading = "lazy",
+  decoding = "async",
+  width,
+  height,
+  className,
+  style,
+}: Readonly<ImageProps>): JSX.Element {
+  let imgSrc: string | undefined;
+  let srcSet: string | undefined;
+  let autoWidth: number | undefined;
+  let autoHeight: number | undefined;
+
+  if (typeof src === "object" && src !== null) {
+    // Object from vite-imagetools (e.g., ?as=metadata or custom output)
+    imgSrc = src.src;
+    srcSet = src.srcset;
+    autoWidth = src.width;
+    autoHeight = src.height;
+  } else if (typeof src === "string") {
+    if (isSrcsetString(src)) {
+      // srcset string from ?as=srcset - use first URL as fallback src
+      srcSet = src;
+      const firstUrl = src.split(",")[0]?.trim().split(" ")[0];
+      imgSrc = firstUrl;
+    } else {
+      // Regular URL string
+      imgSrc = src;
+    }
+  }
+
+  return (
+    <img
+      src={imgSrc}
+      srcSet={srcSet}
+      sizes={sizes}
+      alt={alt}
+      loading={loading}
+      decoding={decoding}
+      width={width ?? autoWidth}
+      height={height ?? autoHeight}
+      className={className}
+      style={style}
+    />
+  );
+}
+
+export default Image;

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;