@alepha/react 0.9.1 → 0.9.3

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/contexts/AlephaContext.ts

@@ -0,0 +1,4 @@
+import type { Alepha } from "@alepha/core";
+import { createContext } from "react";
+
+export const AlephaContext = createContext<Alepha | undefined>(undefined);

package/src/contexts/RouterContext.ts

@@ -1,4 +1,3 @@
-import type { Alepha } from "@alepha/core";
 import { createContext } from "react";
 import type {
 	PageReactContext,
@@ -6,7 +5,6 @@ import type {
 } from "../providers/PageDescriptorProvider.ts";
 
 export interface RouterContextValue {
-	alepha: Alepha;
 	state: RouterState;
 	context: PageReactContext;
 }

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/useAlepha.ts

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

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/useInject.ts

@@ -1,12 +1,9 @@
 import type { Service } from "@alepha/core";
-import { useContext, useMemo } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
+import { useMemo } from "react";
+import { useAlepha } from "./useAlepha.ts";
 
-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>");
-	}
+export const useInject = <T extends object>(service: Service<T>): T => {
+	const alepha = useAlepha();
 
-	return useMemo(() => ctx.alepha.inject(clazz), []);
+	return useMemo(() => alepha.inject(service), []);
 };

package/src/hooks/useQueryParams.ts

@@ -1,6 +1,6 @@
 import type { Alepha, Static, TObject } from "@alepha/core";
-import { useContext, useEffect, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
+import { useEffect, useState } from "react";
+import { useAlepha } from "./useAlepha.ts";
 import { useRouter } from "./useRouter.ts";
 
 export interface UseQueryParamsHookOptions {
@@ -13,21 +13,18 @@ export const useQueryParams = <T extends TObject>(
 	schema: T,
 	options: UseQueryParamsHookOptions = {},
 ): [Static<T>, (data: Static<T>) => void] => {
-	const ctx = useContext(RouterContext);
-	if (!ctx) {
-		throw new Error("useQueryParams must be used within a RouterProvider");
-	}
+	const alepha = useAlepha();
 
 	const key = options.key ?? "q";
 	const router = useRouter();
 	const querystring = router.query[key];
 
 	const [queryParams, setQueryParams] = useState(
-		decode(ctx.alepha, schema, router.query[key]),
+		decode(alepha, schema, router.query[key]),
 	);
 
 	useEffect(() => {
-		setQueryParams(decode(ctx.alepha, schema, querystring));
+		setQueryParams(decode(alepha, schema, querystring));
 	}, [querystring]);
 
 	return [
@@ -35,7 +32,7 @@ export const useQueryParams = <T extends TObject>(
 		(queryParams: Static<T>) => {
 			setQueryParams(queryParams);
 			router.setQueryParams((data) => {
-				return { ...data, [key]: encode(ctx.alepha, schema, queryParams) };
+				return { ...data, [key]: encode(alepha, schema, queryParams) };
 			});
 		},
 	];

package/src/hooks/useRouter.ts

@@ -4,8 +4,10 @@ import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
 import { PageDescriptorProvider } from "../providers/PageDescriptorProvider.ts";
 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);
 	if (!ctx || !layer) {
@@ -13,7 +15,7 @@ export const useRouter = (): RouterHookApi => {
 	}
 
 	const pages = useMemo(() => {
-		return ctx.alepha.inject(PageDescriptorProvider).getPages();
+		return alepha.inject(PageDescriptorProvider).getPages();
 	}, []);
 
 	return useMemo(
@@ -23,9 +25,8 @@ export const useRouter = (): RouterHookApi => {
 				ctx.context,
 				ctx.state,
 				layer,
-				ctx.alepha.isBrowser()
-					? ctx.alepha.inject(ReactBrowserProvider)
-					: undefined,
+				alepha.inject(PageDescriptorProvider),
+				alepha.isBrowser() ? alepha.inject(ReactBrowserProvider) : undefined,
 			),
 		[layer],
 	);

package/src/hooks/useRouterEvents.ts

@@ -1,22 +1,22 @@
-import { useContext, useEffect } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import type { RouterState } from "../providers/PageDescriptorProvider.ts";
+import { useEffect } from "react";
+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[] = [],
 ) => {
-	const ctx = useContext(RouterContext);
-	if (!ctx) {
-		throw new Error("useRouter must be used within a RouterProvider");
-	}
+	const alepha = useAlepha();
 
 	useEffect(() => {
-		if (!ctx.alepha.isBrowser()) {
+		if (!alepha.isBrowser()) {
 			return;
 		}
 
@@ -27,7 +27,7 @@ export const useRouterEvents = (
 
 		if (onBegin) {
 			subs.push(
-				ctx.alepha.on("react:transition:begin", {
+				alepha.on("react:transition:begin", {
 					callback: onBegin,
 				}),
 			);
@@ -35,7 +35,7 @@ export const useRouterEvents = (
 
 		if (onEnd) {
 			subs.push(
-				ctx.alepha.on("react:transition:end", {
+				alepha.on("react:transition:end", {
 					callback: onEnd,
 				}),
 			);
@@ -43,7 +43,7 @@ export const useRouterEvents = (
 
 		if (onError) {
 			subs.push(
-				ctx.alepha.on("react:transition:error", {
+				alepha.on("react:transition:error", {
 					callback: onError,
 				}),
 			);

package/src/hooks/useRouterState.ts

@@ -5,13 +5,15 @@ import type { RouterState } from "../providers/PageDescriptorProvider.ts";
 import { useRouterEvents } from "./useRouterEvents.ts";
 
 export const useRouterState = (): RouterState => {
-	const ctx = useContext(RouterContext);
+	const router = useContext(RouterContext);
 	const layer = useContext(RouterLayerContext);
-	if (!ctx || !layer) {
-		throw new Error("useRouter must be used within a RouterProvider");
+	if (!router || !layer) {
+		throw new Error(
+			"useRouterState must be used within a RouterContext.Provider",
+		);
 	}
 
-	const [state, setState] = useState(ctx.state);
+	const [state, setState] = useState(router.state);
 
 	useRouterEvents({
 		onEnd: ({ state }) => setState({ ...state }),

package/src/hooks/useSchema.ts

@@ -0,0 +1,93 @@
+import type { Alepha } from "@alepha/core";
+import {
+	type FetchOptions,
+	HttpClient,
+	type RequestConfigSchema,
+} from "@alepha/server";
+import {
+	type HttpClientLink,
+	LinkProvider,
+	type VirtualAction,
+} from "@alepha/server-links";
+import { useEffect, useState } from "react";
+import { useAlepha } from "./useAlepha.ts";
+import { useInject } from "./useInject.ts";
+
+export const useSchema = <TConfig extends RequestConfigSchema>(
+	action: VirtualAction<TConfig>,
+): UseSchemaReturn<TConfig> => {
+	const name = action.name;
+	const alepha = useAlepha();
+	const httpClient = useInject(HttpClient);
+	const linkProvider = useInject(LinkProvider);
+	const [schema, setSchema] = useState<UseSchemaReturn<TConfig>>(
+		ssrSchemaLoading(alepha, name) as UseSchemaReturn<TConfig>,
+	);
+
+	useEffect(() => {
+		if (!schema.loading) {
+			return;
+		}
+
+		const opts: FetchOptions = {
+			cache: true,
+		};
+
+		httpClient
+			.fetch(`${linkProvider.URL_LINKS}/${name}/schema`, {}, opts)
+			.then((it) => setSchema(it.data as UseSchemaReturn<TConfig>));
+	}, [name]);
+
+	return schema;
+};
+
+export type UseSchemaReturn<TConfig extends RequestConfigSchema> = TConfig & {
+	loading: boolean;
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Get an action schema during server-side rendering (SSR) or client-side rendering (CSR).
+ */
+export const ssrSchemaLoading = (alepha: Alepha, name: string) => {
+	// server-side rendering (SSR) context
+	if (!alepha.isBrowser()) {
+		// get user links
+		const links =
+			alepha.context.get<{ links: HttpClientLink[] }>("links")?.links ?? [];
+
+		// check if user can access the link
+		const can = links.find((it) => it.name === name);
+
+		// yes!
+		if (can) {
+			// user-links have no schema, so we need to get it from the provider
+			const schema = alepha
+				.inject(LinkProvider)
+				.links?.find((it) => it.name === name)?.schema;
+
+			// oh, we have a schema!
+			if (schema) {
+				// attach to user link, it will be used in the client during hydration :)
+				can.schema = schema;
+				return schema;
+			}
+		}
+		return { loading: true };
+	}
+
+	// browser side rendering (CSR) context
+	// check if we have the schema already loaded
+	const schema = alepha
+		.inject(LinkProvider)
+		.links?.find((it) => it.name === name)?.schema;
+
+	// yes!
+	if (schema) {
+		return schema;
+	}
+
+	// no, we need to load it
+	return { loading: true };
+};