@alepha/react 0.9.2 → 0.9.3

package/src/components/Link.tsx

@@ -1,39 +1,19 @@
+import type 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";
 
 export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-	to: string | PageDescriptor;
+	to: string;
 	children?: React.ReactNode;
 }
 
 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;
-	}
-
-	const can = typeof props.to === "string" ? undefined : props.to.options.can;
-	if (can && !can()) {
-		return null;
-	}
-
-	const name = typeof props.to === "string" ? undefined : props.to.options.name;
-
-	const anchorProps = {
-		...props,
-		to: undefined,
-	};
+	const { to, ...anchorProps } = props;
 
 	return (
 		<a {...router.anchor(to)} {...anchorProps}>
-			{props.children ?? name}
+			{props.children}
 		</a>
 	);
 };

package/src/components/NestedView.tsx

@@ -41,7 +41,10 @@ const NestedView = (props: NestedViewProps) => {
 
 	useRouterEvents(
 		{
-			onEnd: ({ state }) => {
+			onEnd: ({ state, context }) => {
+				if (app) {
+					app.context = context;
+				}
 				if (!state.layers[index]?.cache) {
 					setView(state.layers[index]?.element);
 				}
@@ -57,7 +60,13 @@ const NestedView = (props: NestedViewProps) => {
 	const element = view ?? props.children ?? null;
 
 	return (
-		<ErrorBoundary fallback={app.context.onError!}>{element}</ErrorBoundary>
+		<ErrorBoundary
+			fallback={(error) => {
+				return app.context.onError?.(error, app.context) as ReactNode;
+			}}
+		>
+			{element}
+		</ErrorBoundary>
 	);
 };
 

package/src/components/NotFound.tsx

@@ -1,4 +1,6 @@
-export default function NotFoundPage() {
+import type { CSSProperties } from "react";
+
+export default function NotFoundPage(props: { style?: CSSProperties }) {
 	return (
 		<div
 			style={{
@@ -10,6 +12,7 @@ export default function NotFoundPage() {
 				textAlign: "center",
 				fontFamily: "sans-serif",
 				padding: "1rem",
+				...props.style,
 			}}
 		>
 			<h1 style={{ fontSize: "1rem", marginBottom: "0.5rem" }}>

package/src/descriptors/$page.ts

@@ -3,7 +3,6 @@ import {
 	createDescriptor,
 	Descriptor,
 	KIND,
-	NotImplementedError,
 	type Static,
 	type TSchema,
 } from "@alepha/core";
@@ -11,6 +10,7 @@ import type { ServerRequest } from "@alepha/server";
 import type { ServerRouteCache } from "@alepha/server-cache";
 import type { FC, ReactNode } from "react";
 import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
+import type { Redirection } from "../errors/Redirection.ts";
 import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
 /**
@@ -109,13 +109,52 @@ export interface PageDescriptorOptions<
 
 	can?: () => boolean;
 
-	errorHandler?: (error: Error) => ReactNode;
-
 	/**
-	 * If true, the page will be rendered on the build time.
-	 * Works only with viteAlepha plugin.
+	 * Catch any error from the `resolve` function or during `rendering`.
+	 *
+	 * Expected to return one of the following:
+	 * - a ReactNode to render an error page
+	 * - a Redirection to redirect the user
+	 * - undefined to let the error propagate
+	 *
+	 * If not defined, the error will be thrown and handled by the server or client error handler.
+	 * If a leaf $page does not define an error handler, the error can be caught by parent pages.
 	 *
+	 * @example Catch a 404 from API and render a custom not found component:
+	 * ```ts
+	 * resolve: async ({ params, query }) => {
+	 *    api.fetch("/api/resource", { params, query });
+	 * },
+	 * errorHandler: (error, context) => {
+	 *   if (HttpError.is(error, 404)) {
+	 *     return <ResourceNotFound />;
+	 *   }
+	 * }
+	 * ```
+	 *
+	 * @example Catch an 401 error and redirect the user to the login page:
+	 * ```ts
+	 * resolve: async ({ params, query }) => {
+	 *   // but the user is not authenticated
+	 *   api.fetch("/api/resource", { params, query });
+	 * },
+	 * errorHandler: (error, context) => {
+	 *   if (HttpError.is(error, 401)) {
+	 *     // throwing a Redirection is also valid!
+	 *     return new Redirection("/login");
+	 *   }
+	 * }
+	 * ```
+	 */
+	errorHandler?: ErrorHandler;
+
+	/**
+	 * If true, the page will be considered as a static page, immutable and cacheable.
 	 * Replace boolean by an object to define static entries. (e.g. list of params/query)
+	 *
+	 * For now, it only works with `@alepha/vite` which can pre-render the page at build time.
+	 *
+	 * It will act as timeless cached page server-side. You can use `cache` to configure the cache behavior.
 	 */
 	static?:
 		| boolean
@@ -123,21 +162,44 @@ export interface PageDescriptorOptions<
 				entries?: Array<Partial<PageRequestConfig<TConfig>>>;
 		  };
 
+	cache?: ServerRouteCache;
+
 	/**
-	 * If true, the page will be rendered on the client-side.
+	 * If true, force the page to be rendered only on the client-side.
+	 * It uses the `<ClientOnly/>` component to render the page.
 	 */
 	client?: boolean | ClientOnlyProps;
 
-	afterHandler?: (request: ServerRequest) => any;
+	/**
+	 * Called before the server response is sent to the client.
+	 */
+	onServerResponse?: (request: ServerRequest) => any;
 
-	cache?: ServerRouteCache;
+	/**
+	 * Called when user leaves the page. (browser only)
+	 */
+	onLeave?: () => void;
 }
 
+export type ErrorHandler = (
+	error: Error,
+	context: PageReactContext,
+) => ReactNode | Redirection | undefined;
+
 export class PageDescriptor<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
 	TPropsParent extends object = TPropsParentDefault,
 > extends Descriptor<PageDescriptorOptions<TConfig, TProps, TPropsParent>> {
+	protected onInit() {
+		if (this.options.static) {
+			this.options.cache ??= {
+				provider: "memory",
+				ttl: [1, "week"],
+			};
+		}
+	}
+
 	public get name(): string {
 		return this.options.name ?? this.config.propertyKey;
 	}
@@ -149,7 +211,7 @@ export class PageDescriptor<
 	public async render(
 		options?: PageDescriptorRenderOptions,
 	): Promise<PageDescriptorRenderResult> {
-		throw new NotImplementedError("");
+		throw new Error("render method is not implemented in this environment");
 	}
 }
 

package/src/errors/{RedirectionError.ts → Redirection.ts}

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

package/src/hooks/RouterHookApi.ts

@@ -1,6 +1,7 @@
 import type { PageDescriptor } from "../descriptors/$page.ts";
 import type {
 	AnchorProps,
+	PageDescriptorProvider,
 	PageReactContext,
 	PageRoute,
 	RouterState,
@@ -10,7 +11,7 @@ import type {
 	RouterGoOptions,
 } from "../providers/ReactBrowserProvider.ts";
 
-export class RouterHookApi {
+export class RouterHookApi<T extends object> {
 	constructor(
 		private readonly pages: PageRoute[],
 		private readonly context: PageReactContext,
@@ -18,9 +19,26 @@ export class RouterHookApi {
 		private readonly layer: {
 			path: string;
 		},
+		private readonly pageApi: PageDescriptorProvider,
 		private readonly browser?: ReactBrowserProvider,
 	) {}
 
+	public path(
+		name: keyof VirtualRouter<T>,
+		config: {
+			params?: Record<string, string>;
+			query?: Record<string, string>;
+		} = {},
+	): string {
+		return this.pageApi.pathname(name as string, {
+			params: {
+				...this.context.params,
+				...config.params,
+			},
+			query: config.query,
+		});
+	}
+
 	public getURL(): URL {
 		if (!this.browser) {
 			return this.context.url;
@@ -95,48 +113,54 @@ export class RouterHookApi {
 	}
 
 	public async go(path: string, options?: RouterGoOptions): Promise<void>;
-	public async go<T extends object>(
+	public async go(
 		path: keyof VirtualRouter<T>,
 		options?: RouterGoOptions,
 	): Promise<void>;
-	public async go(path: string, options?: RouterGoOptions): Promise<void> {
+	public async go(
+		path: string | keyof VirtualRouter<T>,
+		options?: RouterGoOptions,
+	): Promise<void> {
 		for (const page of this.pages) {
 			if (page.name === path) {
-				path = page.path ?? "";
-				break;
+				await this.browser?.go(
+					this.path(path as keyof VirtualRouter<T>, options),
+					options,
+				);
+				return;
 			}
 		}
 
-		await this.browser?.go(this.createHref(path, this.layer, options), options);
+		await this.browser?.go(path as string, options);
 	}
 
 	public anchor(
 		path: string,
 		options?: { params?: Record<string, any> },
 	): AnchorProps;
-	public anchor<T extends object>(
+	public anchor(
 		path: keyof VirtualRouter<T>,
 		options?: { params?: Record<string, any> },
 	): AnchorProps;
 	public anchor(
-		path: string,
+		path: string | keyof VirtualRouter<T>,
 		options: { params?: Record<string, any> } = {},
 	): AnchorProps {
+		let href = path as string;
 		for (const page of this.pages) {
 			if (page.name === path) {
-				path = page.path ?? "";
+				href = this.path(path as keyof VirtualRouter<T>, options);
 				break;
 			}
 		}
 
-		const href = this.createHref(path, this.layer, options);
 		return {
 			href,
 			onClick: (ev: any) => {
 				ev.stopPropagation();
 				ev.preventDefault();
 
-				this.go(path, options).catch(console.error);
+				this.go(href, options).catch(console.error);
 			},
 		};
 	}

package/src/hooks/useActive.ts

@@ -6,7 +6,7 @@ import type { HrefLike } from "./RouterHookApi.ts";
 import { useRouter } from "./useRouter.ts";
 import { useRouterEvents } from "./useRouterEvents.ts";
 
-export const useActive = (path: HrefLike): UseActiveHook => {
+export const useActive = (path?: HrefLike): UseActiveHook => {
 	const router = useRouter();
 	const ctx = useContext(RouterContext);
 	const layer = useContext(RouterLayerContext);
@@ -14,29 +14,36 @@ export const useActive = (path: HrefLike): UseActiveHook => {
 		throw new Error("useRouter must be used within a RouterProvider");
 	}
 
-	let name: string | undefined;
-	if (typeof path === "object" && path.options.name) {
-		name = path.options.name;
-	}
-
 	const [current, setCurrent] = useState(ctx.state.pathname);
-	const href = useMemo(() => router.createHref(path, layer), [path, layer]);
+	const href = useMemo(
+		() => router.createHref(path ?? "", layer),
+		[path, layer],
+	);
+
 	const [isPending, setPending] = useState(false);
-	const isActive = current === href;
 
-	useRouterEvents({
-		onEnd: ({ state }) => setCurrent(state.pathname),
-	});
+	// TODO: loose [default] or strict
+	// TODO: startWith: true (e.g. /p/1 should match /p/1/2)
+	const isActive =
+		current === href || current === `${href}/` || `${current}/` === href;
+
+	useRouterEvents(
+		{
+			onEnd: ({ state }) => {
+				path ? setCurrent(state.pathname) : undefined;
+			},
+		},
+		[path],
+	);
 
 	return {
-		name,
 		isPending,
 		isActive,
 		anchorProps: {
 			href,
-			onClick: (ev: any) => {
-				ev.stopPropagation();
-				ev.preventDefault();
+			onClick: (ev?: any) => {
+				ev?.stopPropagation();
+				ev?.preventDefault();
 				if (isActive) return;
 				if (isPending) return;
 

package/src/hooks/useClient.ts

@@ -4,9 +4,11 @@ import {
 	LinkProvider,
 } from "@alepha/server-links";
 import { useInject } from "./useInject.ts";
+import { useStore } from "./useStore.ts";
 
 export const useClient = <T extends object>(
 	_scope?: ClientScope,
 ): HttpVirtualClient<T> => {
+	useStore("user" as any);
 	return useInject(LinkProvider).client<T>();
 };

package/src/hooks/useRouter.ts

@@ -6,7 +6,7 @@ import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
 import { RouterHookApi } from "./RouterHookApi.ts";
 import { useAlepha } from "./useAlepha.ts";
 
-export const useRouter = (): RouterHookApi => {
+export const useRouter = <T extends object>(): RouterHookApi<T> => {
 	const alepha = useAlepha();
 	const ctx = useContext(RouterContext);
 	const layer = useContext(RouterLayerContext);
@@ -25,6 +25,7 @@ export const useRouter = (): RouterHookApi => {
 				ctx.context,
 				ctx.state,
 				layer,
+				alepha.inject(PageDescriptorProvider),
 				alepha.isBrowser() ? alepha.inject(ReactBrowserProvider) : undefined,
 			),
 		[layer],

package/src/hooks/useRouterEvents.ts

@@ -1,11 +1,14 @@
 import { useEffect } from "react";
-import type { RouterState } from "../providers/PageDescriptorProvider.ts";
+import type {
+	PageReactContext,
+	RouterState,
+} from "../providers/PageDescriptorProvider.ts";
 import { useAlepha } from "./useAlepha.ts";
 
 export const useRouterEvents = (
 	opts: {
 		onBegin?: (ev: { state: RouterState }) => void;
-		onEnd?: (ev: { state: RouterState }) => void;
+		onEnd?: (ev: { state: RouterState; context: PageReactContext }) => void;
 		onError?: (ev: { state: RouterState; error: Error }) => void;
 	} = {},
 	deps: any[] = [],

package/src/hooks/useStore.ts

@@ -1,5 +1,5 @@
 import type { State } from "@alepha/core";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 
 /**
@@ -7,8 +7,16 @@ import { useAlepha } from "./useAlepha.ts";
  */
 export const useStore = <Key extends keyof State>(
 	key: Key,
+	defaultValue?: State[Key],
 ): [State[Key], (value: State[Key]) => void] => {
 	const alepha = useAlepha();
+
+	useMemo(() => {
+		if (defaultValue != null && alepha.state(key) == null) {
+			alepha.state(key, defaultValue);
+		}
+	}, [defaultValue]);
+
 	const [state, setState] = useState(alepha.state(key));
 
 	useEffect(() => {

package/src/index.shared.ts

@@ -1,14 +1,14 @@
 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 Link, type LinkProps } from "./components/Link.tsx";
 export { default as NestedView } from "./components/NestedView.tsx";
 export { default as NotFound } from "./components/NotFound.tsx";
 export * from "./contexts/AlephaContext.ts";
 export * from "./contexts/RouterContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./descriptors/$page.ts";
-export * from "./errors/RedirectionError.ts";
+export * from "./errors/Redirection.ts";
 export * from "./hooks/RouterHookApi.ts";
 export * from "./hooks/useActive.ts";
 export * from "./hooks/useAlepha.ts";

package/src/providers/BrowserRouterProvider.ts

@@ -129,6 +129,15 @@ export class BrowserRouterProvider extends RouterProvider<BrowserRoute> {
 			options.state.search = state.search;
 		}
 
+		if (options.previous) {
+			for (let i = 0; i < options.previous.length; i++) {
+				const layer = options.previous[i];
+				if (state.layers[i]?.name !== layer.name) {
+					this.pageDescriptorProvider.page(layer.name)?.onLeave?.();
+				}
+			}
+		}
+
 		await this.alepha.emit("react:transition:end", {
 			state: options.state,
 			context,