@alepha/react 0.6.10 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alepha/react",
-	"version": "0.6.10",
+	"version": "0.7.1",
 	"type": "module",
 	"license": "MIT",
 	"main": "./dist/index.js",
@@ -13,25 +13,26 @@
 		"src"
 	],
 	"dependencies": {
-		"@alepha/core": "0.6.10",
-		"@alepha/router": "0.6.10",
-		"@alepha/server": "0.6.10",
-		"@alepha/server-static": "0.6.10",
+		"@alepha/core": "0.7.1",
+		"@alepha/router": "0.7.1",
+		"@alepha/server": "0.7.1",
+		"@alepha/server-static": "0.7.1",
 		"react-dom": "^19.1.0"
 	},
 	"devDependencies": {
-		"@types/react": "^19.1.4",
-		"@types/react-dom": "^19.1.5",
-		"pkgroll": "^2.12.2",
+		"@types/react": "^19.1.8",
+		"@types/react-dom": "^19.1.6",
+		"pkgroll": "^2.13.1",
 		"react": "^19.1.0",
-		"vitest": "^3.1.3"
+		"vitest": "^3.2.4"
 	},
 	"peerDependencies": {
 		"@types/react": "^19",
 		"react": "^19"
 	},
 	"scripts": {
-		"build": "pkgroll --clean-dist --sourcemap"
+		"test": "vitest run",
+		"build": "pkgroll --clean-dist"
 	},
 	"homepage": "https://github.com/feunard/alepha",
 	"repository": {

package/src/components/ClientOnly.tsx

@@ -0,0 +1,35 @@
+import {
+	type PropsWithChildren,
+	type ReactNode,
+	useEffect,
+	useState,
+} from "react";
+
+export interface ClientOnlyProps {
+	fallback?: ReactNode;
+	disabled?: boolean;
+}
+
+/**
+ * A small utility component that renders its children only on the client side.
+ *
+ * Optionally, you can provide a fallback React node that will be rendered.
+ *
+ * You should use this component when
+ * - you have code that relies on browser-specific APIs
+ * - you want to avoid server-side rendering for a specific part of your application
+ * - you want to prevent pre-rendering of a component
+ */
+const ClientOnly = (props: PropsWithChildren<ClientOnlyProps>) => {
+	const [mounted, setMounted] = useState(false);
+
+	useEffect(() => setMounted(true), []);
+
+	if (props.disabled) {
+		return props.children;
+	}
+
+	return mounted ? props.children : props.fallback;
+};
+
+export default ClientOnly;

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,72 @@
+import React, {
+	type ErrorInfo,
+	type PropsWithChildren,
+	type ReactNode,
+} from "react";
+
+/**
+ * Props for the ErrorBoundary component.
+ */
+export interface ErrorBoundaryProps {
+	/**
+	 * Fallback React node to render when an error is caught.
+	 * If not provided, a default error message will be shown.
+	 */
+	fallback: (error: Error) => ReactNode;
+
+	/**
+	 * Optional callback that receives the error and error info.
+	 * Use this to log errors to a monitoring service.
+	 */
+	onError?: (error: Error, info: ErrorInfo) => void;
+}
+
+/**
+ * State of the ErrorBoundary component.
+ */
+interface ErrorBoundaryState {
+	error?: Error;
+}
+
+/**
+ * A reusable error boundary for catching rendering errors
+ * in any part of the React component tree.
+ */
+export class ErrorBoundary extends React.Component<
+	PropsWithChildren<ErrorBoundaryProps>,
+	ErrorBoundaryState
+> {
+	constructor(props: ErrorBoundaryProps) {
+		super(props);
+		this.state = {};
+	}
+
+	/**
+	 * Update state so the next render shows the fallback UI.
+	 */
+	static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+		return {
+			error,
+		};
+	}
+
+	/**
+	 * Lifecycle method called when an error is caught.
+	 * You can log the error or perform side effects here.
+	 */
+	componentDidCatch(error: Error, info: ErrorInfo): void {
+		if (this.props.onError) {
+			this.props.onError(error, info);
+		}
+	}
+
+	render(): ReactNode {
+		if (this.state.error) {
+			return this.props.fallback(this.state.error);
+		}
+
+		return this.props.children;
+	}
+}
+
+export default ErrorBoundary;

package/src/components/ErrorViewer.tsx

@@ -0,0 +1,161 @@
+import { useState } from "react";
+import { useAlepha } from "../hooks/useAlepha.ts";
+
+interface ErrorViewerProps {
+	error: Error;
+}
+
+// TODO: design this better
+
+const ErrorViewer = ({ error }: ErrorViewerProps) => {
+	const [expanded, setExpanded] = useState(false);
+	const isProduction = useAlepha().isProduction();
+	// const status = isHttpError(error) ? error.status : 500;
+
+	if (isProduction) {
+		return <ErrorViewerProduction />;
+	}
+
+	const stackLines = error.stack?.split("\n") ?? [];
+	const previewLines = stackLines.slice(0, 5);
+	const hiddenLineCount = stackLines.length - previewLines.length;
+
+	const copyToClipboard = (text: string) => {
+		navigator.clipboard.writeText(text).catch((err) => {
+			console.error("Clipboard error:", err);
+		});
+	};
+
+	const styles = {
+		container: {
+			padding: "24px",
+			backgroundColor: "#FEF2F2",
+			color: "#7F1D1D",
+			border: "1px solid #FECACA",
+			borderRadius: "16px",
+			boxShadow: "0 8px 24px rgba(0,0,0,0.05)",
+			fontFamily: "monospace",
+			maxWidth: "768px",
+			margin: "40px auto",
+		},
+		heading: {
+			fontSize: "20px",
+			fontWeight: "bold",
+			marginBottom: "4px",
+		},
+		name: {
+			fontSize: "16px",
+			fontWeight: 600,
+		},
+		message: {
+			fontSize: "14px",
+			marginBottom: "16px",
+		},
+		sectionHeader: {
+			display: "flex",
+			justifyContent: "space-between",
+			alignItems: "center",
+			fontSize: "12px",
+			marginBottom: "4px",
+			color: "#991B1B",
+		},
+		copyButton: {
+			fontSize: "12px",
+			color: "#DC2626",
+			background: "none",
+			border: "none",
+			cursor: "pointer",
+			textDecoration: "underline",
+		},
+		stackContainer: {
+			backgroundColor: "#FEE2E2",
+			padding: "12px",
+			borderRadius: "8px",
+			fontSize: "13px",
+			lineHeight: "1.4",
+			overflowX: "auto" as const,
+			whiteSpace: "pre-wrap" as const,
+		},
+		expandLine: {
+			color: "#F87171",
+			cursor: "pointer",
+			marginTop: "8px",
+		},
+	};
+
+	return (
+		<div style={styles.container}>
+			<div>
+				<div style={styles.heading}>🔥 Error</div>
+				<div style={styles.name}>{error.name}</div>
+				<div style={styles.message}>{error.message}</div>
+			</div>
+
+			{stackLines.length > 0 && (
+				<div>
+					<div style={styles.sectionHeader}>
+						<span>Stack trace</span>
+						<button
+							onClick={() => copyToClipboard(error.stack!)}
+							style={styles.copyButton}
+						>
+							Copy all
+						</button>
+					</div>
+					<pre style={styles.stackContainer}>
+						{(expanded ? stackLines : previewLines).map((line, i) => (
+							<div key={i}>{line}</div>
+						))}
+						{!expanded && hiddenLineCount > 0 && (
+							<div style={styles.expandLine} onClick={() => setExpanded(true)}>
+								+ {hiddenLineCount} more lines...
+							</div>
+						)}
+					</pre>
+				</div>
+			)}
+		</div>
+	);
+};
+
+export default ErrorViewer;
+
+const ErrorViewerProduction = () => {
+	const styles = {
+		container: {
+			padding: "24px",
+			backgroundColor: "#FEF2F2",
+			color: "#7F1D1D",
+			border: "1px solid #FECACA",
+			borderRadius: "16px",
+			boxShadow: "0 8px 24px rgba(0,0,0,0.05)",
+			fontFamily: "monospace",
+			maxWidth: "768px",
+			margin: "40px auto",
+			textAlign: "center" as const,
+		},
+		heading: {
+			fontSize: "20px",
+			fontWeight: "bold",
+			marginBottom: "8px",
+		},
+		name: {
+			fontSize: "16px",
+			fontWeight: 600,
+			marginBottom: "4px",
+		},
+		message: {
+			fontSize: "14px",
+			opacity: 0.85,
+		},
+	};
+
+	return (
+		<div style={styles.container}>
+			<div style={styles.heading}>🚨 An error occurred</div>
+			<div style={styles.message}>
+				Something went wrong. Please try again later.
+			</div>
+		</div>
+	);
+};

package/src/components/Link.tsx

@@ -1,9 +1,9 @@
-import React from "react";
+import { OPTIONS } from "@alepha/core";
 import type { AnchorHTMLAttributes } from "react";
+import React from "react";
 import { RouterContext } from "../contexts/RouterContext.ts";
 import type { PageDescriptor } from "../descriptors/$page.ts";
 import { useRouter } from "../hooks/useRouter.ts";
-import { OPTIONS } from "@alepha/core";
 
 export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
 	to: string | PageDescriptor;
@@ -13,6 +13,8 @@ export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
 const Link = (props: LinkProps) => {
 	React.useContext(RouterContext);
 
+	const router = useRouter();
+
 	const to = typeof props.to === "string" ? props.to : props.to[OPTIONS].path;
 	if (!to) {
 		return null;
@@ -26,9 +28,13 @@ const Link = (props: LinkProps) => {
 	const name =
 		typeof props.to === "string" ? undefined : props.to[OPTIONS].name;
 
-	const router = useRouter();
+	const anchorProps = {
+		...props,
+		to: undefined,
+	};
+
 	return (
-		<a {...router.createAnchorProps(to)} {...props}>
+		<a {...router.anchor(to)} {...anchorProps}>
 			{props.children ?? name}
 		</a>
 	);

package/src/components/NestedView.tsx

@@ -3,16 +3,32 @@ import { useContext, useState } from "react";
 import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
 import { useRouterEvents } from "../hooks/useRouterEvents.ts";
+import ErrorBoundary from "./ErrorBoundary.tsx";
 
 export interface NestedViewProps {
 	children?: ReactNode;
 }
 
 /**
- * Nested view component
+ * A component that renders the current view of the nested router layer.
  *
- * @param props
- * @constructor
+ * To be simple, it renders the `element` of the current child page of a parent page.
+ *
+ * @example
+ * ```tsx
+ * import { NestedView } from "@alepha/react";
+ *
+ * class App {
+ *   parent = $page({
+ *     component: () => <NestedView />,
+ *   });
+ *
+ *   child = $page({
+ *     parent: this.root,
+ *     component: () => <div>Child Page</div>,
+ *   });
+ * }
+ * ```
  */
 const NestedView = (props: NestedViewProps) => {
 	const app = useContext(RouterContext);
@@ -32,7 +48,15 @@ const NestedView = (props: NestedViewProps) => {
 		[app],
 	);
 
-	return view ?? props.children ?? null;
+	if (!app) {
+		throw new Error("NestedView must be used within a RouterContext.");
+	}
+
+	const element = view ?? props.children ?? null;
+
+	return (
+		<ErrorBoundary fallback={app.context.onError!}>{element}</ErrorBoundary>
+	);
 };
 
 export default NestedView;

package/src/descriptors/$page.ts

@@ -1,7 +1,16 @@
-import { type Async, OPTIONS, type Static, type TSchema } from "@alepha/core";
-import { KIND, NotImplementedError, __descriptor } from "@alepha/core";
-import type { FC } from "react";
-import type { RouterHookApi } from "../hooks/RouterHookApi.ts";
+import {
+	__descriptor,
+	type Async,
+	KIND,
+	NotImplementedError,
+	OPTIONS,
+	type Static,
+	type TSchema,
+} from "@alepha/core";
+import type { ServerRoute } from "@alepha/server";
+import type { FC, ReactNode } from "react";
+import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
+import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
 const KEY = "PAGE";
 
@@ -12,34 +21,100 @@ export interface PageConfigSchema {
 
 export type TPropsDefault = any;
 
-export type TPropsParentDefault = object;
+export type TPropsParentDefault = {};
 
 export interface PageDescriptorOptions<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
 	TPropsParent extends object = TPropsParentDefault,
-> {
+> extends Pick<ServerRoute, "cache"> {
+	/**
+	 * Name your page.
+	 *
+	 * @default Descriptor key
+	 */
 	name?: string;
 
+	/**
+	 * Optional description of the page.
+	 */
+	description?: string;
+
+	/**
+	 * Add a pathname to the page.
+	 *
+	 * Pathname can contain parameters, like `/post/:slug`.
+	 *
+	 * @default ""
+	 */
 	path?: string;
 
+	/**
+	 * Add an input schema to define:
+	 * - `params`: parameters from the pathname.
+	 * - `query`: query parameters from the URL.
+	 */
 	schema?: TConfig;
 
-	resolve?: (config: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
-
+	/**
+	 * Load data before rendering the page.
+	 *
+	 * This function receives
+	 * - the request context and
+	 * - the parent props (if page has a parent)
+	 *
+	 * In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
+	 *
+	 * Resolve can be stopped by throwing an error, which will be handled by the `errorHandler` function.
+	 * It's common to throw a `NotFoundError` to display a 404 page.
+	 *
+	 * RedirectError can be thrown to redirect the user to another page.
+	 */
+	resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
+
+	/**
+	 * The component to render when the page is loaded.
+	 *
+	 * If `lazy` is defined, this will be ignored.
+	 * Prefer using `lazy` to improve the initial loading time.
+	 */
 	component?: FC<TProps & TPropsParent>;
 
+	/**
+	 * Lazy load the component when the page is loaded.
+	 *
+	 * It's recommended to use this for components to improve the initial loading time
+	 * and enable code-splitting.
+	 */
 	lazy?: () => Promise<{ default: FC<TProps & TPropsParent> }>;
 
+	/**
+	 * Set some children pages and make the page a parent page.
+	 *
+	 * /!\ Parent page can't be rendered directly. /!\
+	 *
+	 * If you still want to render at this pathname, add a child page with an empty path.
+	 */
 	children?: Array<{ [OPTIONS]: PageDescriptorOptions }>;
 
-	parent?: { [OPTIONS]: PageDescriptorOptions<any, TPropsParent> };
+	parent?: { [OPTIONS]: PageDescriptorOptions<PageConfigSchema, TPropsParent> };
 
 	can?: () => boolean;
 
 	head?: Head | ((props: TProps, previous?: Head) => Head);
 
-	errorHandler?: FC<{ error: Error; url: string }>;
+	errorHandler?: (error: Error) => ReactNode;
+
+	prerender?:
+		| boolean
+		| {
+				entries?: Array<Partial<PageRequestConfig<TConfig>>>;
+		  };
+
+	/**
+	 * If true, the page will be rendered on the client-side.
+	 */
+	client?: boolean | ClientOnlyProps;
 }
 
 export interface PageDescriptor<
@@ -50,18 +125,18 @@ export interface PageDescriptor<
 	[KIND]: typeof KEY;
 	[OPTIONS]: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
 
-	render: (options?: {
-		params?: Record<string, string>;
-		query?: Record<string, string>;
-	}) => Promise<string>;
-	go: () => void;
-	createAnchorProps: (routerHook: RouterHookApi) => {
-		href: string;
-		onClick: () => void;
-	};
-	can: () => boolean;
+	/**
+	 * For testing or build purposes, this will render the page (with or without the HTML layout) and return the HTML and context.
+	 * Only valid for server-side rendering, it will throw an error if called on the client-side.
+	 */
+	render: (
+		options?: PageDescriptorRenderOptions,
+	) => Promise<PageDescriptorRenderResult>;
 }
 
+/**
+ * Main descriptor for defining a React route in the application.
+ */
 export const $page = <
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
@@ -92,18 +167,6 @@ export const $page = <
 		render: () => {
 			throw new NotImplementedError(KEY);
 		},
-		go: () => {
-			throw new NotImplementedError(KEY);
-		},
-		createAnchorProps: () => {
-			throw new NotImplementedError(KEY);
-		},
-		can: () => {
-			if (options.can) {
-				return options.can();
-			}
-			return true;
-		},
 	};
 };
 
@@ -111,12 +174,59 @@ $page[KIND] = KEY;
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface PageDescriptorRenderOptions {
+	params?: Record<string, string>;
+	query?: Record<string, string>;
+	withLayout?: boolean;
+}
+
+export interface PageDescriptorRenderResult {
+	html: string;
+	context: PageReactContext;
+}
+
 export interface Head {
 	title?: string;
+	description?: string;
 	titleSeparator?: string;
 	htmlAttributes?: Record<string, string>;
 	bodyAttributes?: Record<string, string>;
 	meta?: Array<{ name: string; content: string }>;
+
+	// TODO
+	keywords?: string[];
+	author?: string;
+	robots?: string;
+	themeColor?: string;
+	viewport?:
+		| string
+		| {
+				width?: string;
+				height?: string;
+				initialScale?: string;
+				maximumScale?: string;
+				userScalable?: "no" | "yes" | "0" | "1";
+				interactiveWidget?:
+					| "resizes-visual"
+					| "resizes-content"
+					| "overlays-content";
+		  };
+
+	og?: {
+		title?: string;
+		description?: string;
+		image?: string;
+		url?: string;
+		type?: string;
+	};
+
+	twitter?: {
+		card?: string;
+		title?: string;
+		description?: string;
+		image?: string;
+		site?: string;
+	};
 }
 
 export interface PageRequestConfig<
@@ -134,9 +244,4 @@ export interface PageRequestConfig<
 export type PageResolve<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TPropsParent extends object = TPropsParentDefault,
-> = PageRequestConfig<TConfig> & TPropsParent & PageResolveContext;
-
-export interface PageResolveContext {
-	url: URL;
-	head: Head;
-}
+> = PageRequestConfig<TConfig> & TPropsParent & PageReactContext;

package/src/errors/RedirectionError.ts

@@ -1,7 +1,10 @@
 import type { HrefLike } from "../hooks/RouterHookApi.ts";
 
 export class RedirectionError extends Error {
-	constructor(public readonly page: HrefLike) {
+	public readonly page: HrefLike;
+
+	constructor(page: HrefLike) {
 		super("Redirection");
+		this.page = page;
 	}
 }