@alepha/react 0.7.0 → 0.7.1

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,6 +1,6 @@
 import { OPTIONS } from "@alepha/core";
-import React from "react";
 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";
@@ -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.anchor(to)} {...props}>
+		<a {...router.anchor(to)} {...anchorProps}>
 			{props.children ?? name}
 		</a>
 	);

package/src/components/NestedView.tsx

@@ -10,10 +10,25 @@ export interface NestedViewProps {
 }
 
 /**
- * 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);

package/src/descriptors/$page.ts

@@ -1,7 +1,15 @@
-import { type Async, OPTIONS, type Static, type TSchema } from "@alepha/core";
-import { KIND, NotImplementedError, __descriptor } from "@alepha/core";
+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 { RouterHookApi } from "../hooks/RouterHookApi.ts";
+import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
 import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
 const KEY = "PAGE";
@@ -13,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?: (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<
@@ -51,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,
@@ -93,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;
-		},
 	};
 };
 
@@ -112,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<

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;
 	}
 }

package/src/hooks/RouterHookApi.ts

@@ -1,6 +1,7 @@
 import type { PageDescriptor } from "../descriptors/$page.ts";
 import type {
 	AnchorProps,
+	PageRoute,
 	RouterState,
 } from "../providers/PageDescriptorProvider.ts";
 import type {
@@ -10,6 +11,7 @@ import type {
 
 export class RouterHookApi {
 	constructor(
+		private readonly pages: PageRoute[],
 		private readonly state: RouterState,
 		private readonly layer: {
 			path: string;
@@ -74,11 +76,21 @@ export class RouterHookApi {
 	 * @param pathname
 	 * @param layer
 	 */
-	public createHref(pathname: HrefLike, layer: { path: string } = this.layer) {
+	public createHref(
+		pathname: HrefLike,
+		layer: { path: string } = this.layer,
+		options: { params?: Record<string, any> } = {},
+	) {
 		if (typeof pathname === "object") {
 			pathname = pathname.options.path ?? "";
 		}
 
+		if (options.params) {
+			for (const [key, value] of Object.entries(options.params)) {
+				pathname = pathname.replace(`:${key}`, String(value));
+			}
+		}
+
 		return pathname.startsWith("/")
 			? pathname
 			: `${layer.path}/${pathname}`.replace(/\/\/+/g, "/");
@@ -90,18 +102,43 @@ export class RouterHookApi {
 		options?: RouterGoOptions,
 	): Promise<void>;
 	public async go(path: string, options?: RouterGoOptions): Promise<void> {
-		await this.browser?.go(this.createHref(path, this.layer), options);
+		for (const page of this.pages) {
+			if (page.name === path) {
+				path = page.path ?? "";
+				break;
+			}
+		}
+
+		await this.browser?.go(this.createHref(path, this.layer, options), options);
 	}
 
-	public anchor(path: string): AnchorProps {
-		const href = this.createHref(path, this.layer);
+	public anchor(
+		path: string,
+		options?: { params?: Record<string, any> },
+	): AnchorProps;
+	public anchor<T extends object>(
+		path: keyof VirtualRouter<T>,
+		options?: { params?: Record<string, any> },
+	): AnchorProps;
+	public anchor(
+		path: string,
+		options: { params?: Record<string, any> } = {},
+	): AnchorProps {
+		for (const page of this.pages) {
+			if (page.name === path) {
+				path = page.path ?? "";
+				break;
+			}
+		}
+
+		const href = this.createHref(path, this.layer, options);
 		return {
 			href,
 			onClick: (ev: any) => {
 				ev.stopPropagation();
 				ev.preventDefault();
 
-				this.go(path).catch(console.error);
+				this.go(path, options).catch(console.error);
 			},
 		};
 	}

package/src/hooks/useAlepha.ts

@@ -0,0 +1,12 @@
+import type { Alepha } from "@alepha/core";
+import { useContext } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+
+export const useAlepha = (): Alepha => {
+	const routerContext = useContext(RouterContext);
+	if (!routerContext) {
+		throw new Error("useAlepha must be used within a RouterProvider");
+	}
+
+	return routerContext.alepha;
+};

package/src/hooks/useClient.ts

@@ -1,10 +1,12 @@
-import { HttpClient } from "@alepha/server";
+import {
+	type ClientScope,
+	HttpClient,
+	type HttpVirtualClient,
+} from "@alepha/server";
 import { useInject } from "./useInject.ts";
 
-export const useClient = (): HttpClient => {
-	return useInject(HttpClient);
-};
-
-export const useApi = <T extends object>() => {
+export const useClient = <T extends object>(
+	_scope?: ClientScope,
+): HttpVirtualClient<T> => {
 	return useInject(HttpClient).of<T>();
 };

package/src/hooks/useInject.ts

@@ -1,8 +1,8 @@
-import type { Class } from "@alepha/core";
+import type { Service } from "@alepha/core";
 import { useContext, useMemo } from "react";
 import { RouterContext } from "../contexts/RouterContext.ts";
 
-export const useInject = <T extends object>(clazz: Class<T>): T => {
+export const useInject = <T extends object>(clazz: Service<T>): T => {
 	const ctx = useContext(RouterContext);
 	if (!ctx) {
 		throw new Error("useRouter must be used within a <RouterProvider>");

package/src/hooks/useQueryParams.ts

@@ -50,7 +50,7 @@ const encode = (alepha: Alepha, schema: TObject, data: any) => {
 const decode = (alepha: Alepha, schema: TObject, data: any) => {
 	try {
 		return alepha.parse(schema, JSON.parse(atob(decodeURIComponent(data))));
-	} catch (error) {
+	} catch (_error) {
 		return {};
 	}
 };

package/src/hooks/useRouter.ts

@@ -1,6 +1,7 @@
 import { useContext, useMemo } from "react";
 import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { PageDescriptorProvider } from "../providers/PageDescriptorProvider.ts";
 import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
 import { RouterHookApi } from "./RouterHookApi.ts";
 
@@ -11,9 +12,14 @@ export const useRouter = (): RouterHookApi => {
 		throw new Error("useRouter must be used within a RouterProvider");
 	}
 
+	const pages = useMemo(() => {
+		return ctx.alepha.get(PageDescriptorProvider).getPages();
+	}, []);
+
 	return useMemo(
 		() =>
 			new RouterHookApi(
+				pages,
 				ctx.state,
 				layer,
 				ctx.alepha.isBrowser()

package/src/index.browser.ts

@@ -1,4 +1,4 @@
-import { $inject, Alepha, __bind } from "@alepha/core";
+import { __bind, $inject, Alepha } from "@alepha/core";
 import { $page } from "./descriptors/$page.ts";
 import { BrowserRouterProvider } from "./providers/BrowserRouterProvider.ts";
 import { PageDescriptorProvider } from "./providers/PageDescriptorProvider.ts";

package/src/index.shared.ts

@@ -1,16 +1,22 @@
-export { default as NestedView } from "./components/NestedView.tsx";
-export { default as Link } from "./components/Link.tsx";
+export { default as ClientOnly } from "./components/ClientOnly.tsx";
 export { default as ErrorBoundary } from "./components/ErrorBoundary.tsx";
+export * from "./components/ErrorViewer.tsx";
+export { default as Link } from "./components/Link.tsx";
+export { default as NestedView } from "./components/NestedView.tsx";
 
 export * from "./contexts/RouterContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
+
 export * from "./descriptors/$page.ts";
+
+export * from "./errors/RedirectionError.ts";
+
 export * from "./hooks/RouterHookApi.ts";
-export * from "./hooks/useInject.ts";
+export * from "./hooks/useActive.ts";
+export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
+export * from "./hooks/useInject.ts";
 export * from "./hooks/useQueryParams.ts";
 export * from "./hooks/useRouter.ts";
 export * from "./hooks/useRouterEvents.ts";
 export * from "./hooks/useRouterState.ts";
-export * from "./hooks/useActive.ts";
-export * from "./errors/RedirectionError.ts";