@alepha/react 0.9.2 → 0.9.4

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

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import { useContext, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { Redirection } from "../errors/Redirection.ts";
+import { useAlepha } from "../hooks/useAlepha.ts";
 import { useRouterEvents } from "../hooks/useRouterEvents.ts";
 import ErrorBoundary from "./ErrorBoundary.tsx";
 
@@ -31,12 +32,16 @@ export interface NestedViewProps {
  * ```
  */
 const NestedView = (props: NestedViewProps) => {
-	const app = useContext(RouterContext);
 	const layer = useContext(RouterLayerContext);
 	const index = layer?.index ?? 0;
+	const alepha = useAlepha();
+	const state = alepha.state("react.router.state");
+	if (!state) {
+		throw new Error("<NestedView/> must be used inside a RouterLayerContext.");
+	}
 
 	const [view, setView] = useState<ReactNode | undefined>(
-		app?.state.layers[index]?.element,
+		state.layers[index]?.element,
 	);
 
 	useRouterEvents(
@@ -47,17 +52,23 @@ const NestedView = (props: NestedViewProps) => {
 				}
 			},
 		},
-		[app],
+		[],
 	);
 
-	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>
+		<ErrorBoundary
+			fallback={(error) => {
+				const result = state.onError(error, state); // TODO: onError is not refreshed
+				if (result instanceof Redirection) {
+					return "Redirection inside ErrorBoundary is not allowed.";
+				}
+				return result 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,10 +12,11 @@ export default function NotFoundPage() {
 				textAlign: "center",
 				fontFamily: "sans-serif",
 				padding: "1rem",
+				...props.style,
 			}}
 		>
 			<h1 style={{ fontSize: "1rem", marginBottom: "0.5rem" }}>
-				This page does not exist
+				404 - This page does not exist
 			</h1>
 		</div>
 	);

package/src/descriptors/$page.ts

@@ -3,7 +3,6 @@ import {
 	createDescriptor,
 	Descriptor,
 	KIND,
-	NotImplementedError,
 	type Static,
 	type TSchema,
 } from "@alepha/core";
@@ -11,7 +10,8 @@ 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 { PageReactContext } from "../providers/PageDescriptorProvider.ts";
+import type { Redirection } from "../errors/Redirection.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 
 /**
  * Main descriptor for defining a React route in the application.
@@ -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,
+	state: ReactRouterState,
+) => 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,17 @@ export class PageDescriptor<
 	public async render(
 		options?: PageDescriptorRenderOptions,
 	): Promise<PageDescriptorRenderResult> {
-		throw new NotImplementedError("");
+		throw new Error("render method is not implemented in this environment");
+	}
+
+	public match(url: string): boolean {
+		// TODO: Implement a way to match the URL against the pathname
+		return false;
+	}
+
+	public pathname(config: any) {
+		// TODO: Implement a way to generate the pathname based on the config
+		return this.options.path || "";
 	}
 }
 
@@ -175,7 +247,7 @@ export interface PageDescriptorRenderOptions {
 
 export interface PageDescriptorRenderResult {
 	html: string;
-	context: PageReactContext;
+	state: ReactRouterState;
 }
 
 export interface PageRequestConfig<
@@ -193,4 +265,6 @@ export interface PageRequestConfig<
 export type PageResolve<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TPropsParent extends object = TPropsParentDefault,
-> = PageRequestConfig<TConfig> & TPropsParent & PageReactContext;
+> = PageRequestConfig<TConfig> &
+	TPropsParent &
+	Omit<ReactRouterState, "layers" | "onError">;

package/src/errors/Redirection.ts

@@ -0,0 +1,13 @@
+/**
+ * Used for Redirection during the page loading.
+ *
+ * Depends on the context, it can be thrown or just returned.
+ */
+export class Redirection extends Error {
+	public readonly redirect: string;
+
+	constructor(redirect: string) {
+		super("Redirection");
+		this.redirect = redirect;
+	}
+}

package/src/hooks/useActive.ts

@@ -1,49 +1,47 @@
-import { useContext, useMemo, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { AnchorProps } from "../providers/PageDescriptorProvider.ts";
-import type { HrefLike } from "./RouterHookApi.ts";
+import { useState } from "react";
+import type { AnchorProps } from "../providers/ReactPageProvider.ts";
 import { useRouter } from "./useRouter.ts";
-import { useRouterEvents } from "./useRouterEvents.ts";
+import { useRouterState } from "./useRouterState.ts";
 
-export const useActive = (path: HrefLike): UseActiveHook => {
+export interface UseActiveOptions {
+	href: string;
+	startWith?: boolean;
+}
+
+export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
 	const router = useRouter();
-	const ctx = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!ctx || !layer) {
-		throw new Error("useRouter must be used within a RouterProvider");
-	}
+	const [isPending, setPending] = useState(false);
+	const state = useRouterState();
+	const current = state.url.pathname;
 
-	let name: string | undefined;
-	if (typeof path === "object" && path.options.name) {
-		name = path.options.name;
-	}
+	const options: UseActiveOptions =
+		typeof args === "string" ? { href: args } : { ...args, href: args.href };
+	const href = options.href;
 
-	const [current, setCurrent] = useState(ctx.state.pathname);
-	const href = useMemo(() => router.createHref(path, layer), [path, layer]);
-	const [isPending, setPending] = useState(false);
-	const isActive = current === href;
+	let isActive =
+		current === href || current === `${href}/` || `${current}/` === href;
 
-	useRouterEvents({
-		onEnd: ({ state }) => setCurrent(state.pathname),
-	});
+	if (options.startWith && !isActive) {
+		isActive = current.startsWith(href);
+	}
 
 	return {
-		name,
 		isPending,
 		isActive,
 		anchorProps: {
-			href,
-			onClick: (ev: any) => {
-				ev.stopPropagation();
-				ev.preventDefault();
+			href: router.base(href),
+			onClick: async (ev?: any) => {
+				ev?.stopPropagation();
+				ev?.preventDefault();
 				if (isActive) return;
 				if (isPending) return;
 
 				setPending(true);
-				router.go(href).then(() => {
+				try {
+					await router.go(href);
+				} finally {
 					setPending(false);
-				});
+				}
 			},
 		},
 	};

package/src/hooks/useAlepha.ts

@@ -1,11 +1,25 @@
-import type { Alepha } from "@alepha/core";
+import { type Alepha, AlephaError } from "@alepha/core";
 import { useContext } from "react";
 import { AlephaContext } from "../contexts/AlephaContext.ts";
 
+/**
+ * Main Alepha hook.
+ *
+ * It provides access to the Alepha instance within a React component.
+ *
+ * With Alepha, you can access the core functionalities of the framework:
+ *
+ * - alepha.state() for state management
+ * - alepha.inject() for dependency injection
+ * - alepha.emit() for event handling
+ * etc...
+ */
 export const useAlepha = (): Alepha => {
 	const alepha = useContext(AlephaContext);
 	if (!alepha) {
-		throw new Error("useAlepha must be used within an AlephaContext.Provider");
+		throw new AlephaError(
+			"Hook 'useAlepha()' must be used within an AlephaContext.Provider",
+		);
 	}
 
 	return alepha;

package/src/hooks/useClient.ts

@@ -5,8 +5,13 @@ import {
 } from "@alepha/server-links";
 import { useInject } from "./useInject.ts";
 
+/**
+ * Hook to get a virtual client for the specified scope.
+ *
+ * It's the React-hook version of `$client()`, from `AlephaServerLinks` module.
+ */
 export const useClient = <T extends object>(
-	_scope?: ClientScope,
+	scope?: ClientScope,
 ): HttpVirtualClient<T> => {
-	return useInject(LinkProvider).client<T>();
+	return useInject(LinkProvider).client<T>(scope);
 };

package/src/hooks/useInject.ts

@@ -2,8 +2,11 @@ import type { Service } from "@alepha/core";
 import { useMemo } from "react";
 import { useAlepha } from "./useAlepha.ts";
 
+/**
+ * Hook to inject a service instance.
+ * It's a wrapper of `useAlepha().inject(service)` with a memoization.
+ */
 export const useInject = <T extends object>(service: Service<T>): T => {
 	const alepha = useAlepha();
-
 	return useMemo(() => alepha.inject(service), []);
 };

package/src/hooks/useQueryParams.ts

@@ -3,12 +3,9 @@ import { useEffect, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 import { useRouter } from "./useRouter.ts";
 
-export interface UseQueryParamsHookOptions {
-	format?: "base64" | "querystring";
-	key?: string;
-	push?: boolean;
-}
-
+/**
+ * Not well tested. Use with caution.
+ */
 export const useQueryParams = <T extends TObject>(
 	schema: T,
 	options: UseQueryParamsHookOptions = {},
@@ -40,6 +37,12 @@ export const useQueryParams = <T extends TObject>(
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface UseQueryParamsHookOptions {
+	format?: "base64" | "querystring";
+	key?: string;
+	push?: boolean;
+}
+
 const encode = (alepha: Alepha, schema: TObject, data: any) => {
 	return btoa(JSON.stringify(alepha.parse(schema, data)));
 };

package/src/hooks/useRouter.ts

@@ -1,32 +1,20 @@
-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";
-import { useAlepha } from "./useAlepha.ts";
+import { ReactRouter } from "../services/ReactRouter.ts";
+import { useInject } from "./useInject.ts";
 
-export const useRouter = (): RouterHookApi => {
-	const alepha = useAlepha();
-	const ctx = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!ctx || !layer) {
-		throw new Error("useRouter must be used within a RouterProvider");
-	}
-
-	const pages = useMemo(() => {
-		return alepha.inject(PageDescriptorProvider).getPages();
-	}, []);
-
-	return useMemo(
-		() =>
-			new RouterHookApi(
-				pages,
-				ctx.context,
-				ctx.state,
-				layer,
-				alepha.isBrowser() ? alepha.inject(ReactBrowserProvider) : undefined,
-			),
-		[layer],
-	);
+/**
+ * Use this hook to access the React Router instance.
+ *
+ * You can add a type parameter to specify the type of your application.
+ * This will allow you to use the router in a typesafe way.
+ *
+ * @example
+ * class App {
+ *   home = $page();
+ * }
+ *
+ * const router = useRouter<App>();
+ * router.go("home"); // typesafe
+ */
+export const useRouter = <T extends object = any>(): ReactRouter<T> => {
+	return useInject(ReactRouter<T>);
 };

package/src/hooks/useRouterEvents.ts

@@ -1,12 +1,15 @@
 import { useEffect } from "react";
-import type { RouterState } from "../providers/PageDescriptorProvider.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { useAlepha } from "./useAlepha.ts";
 
+/**
+ * Subscribe to various router events.
+ */
 export const useRouterEvents = (
 	opts: {
-		onBegin?: (ev: { state: RouterState }) => void;
-		onEnd?: (ev: { state: RouterState }) => void;
-		onError?: (ev: { state: RouterState; error: Error }) => void;
+		onBegin?: (ev: { state: ReactRouterState }) => void;
+		onEnd?: (ev: { state: ReactRouterState }) => void;
+		onError?: (ev: { state: ReactRouterState; error: Error }) => void;
 	} = {},
 	deps: any[] = [],
 ) => {

package/src/hooks/useRouterState.ts

@@ -1,23 +1,11 @@
-import { useContext, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { RouterState } from "../providers/PageDescriptorProvider.ts";
-import { useRouterEvents } from "./useRouterEvents.ts";
-
-export const useRouterState = (): RouterState => {
-	const router = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!router || !layer) {
-		throw new Error(
-			"useRouterState must be used within a RouterContext.Provider",
-		);
+import { AlephaError } from "@alepha/core";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
+import { useStore } from "./useStore.ts";
+
+export const useRouterState = (): ReactRouterState => {
+	const [state] = useStore("react.router.state");
+	if (!state) {
+		throw new AlephaError("Missing react router state");
 	}
-
-	const [state, setState] = useState(router.state);
-
-	useRouterEvents({
-		onEnd: ({ state }) => setState({ ...state }),
-	});
-
 	return state;
 };

package/src/hooks/useSchema.ts

@@ -4,11 +4,7 @@ import {
 	HttpClient,
 	type RequestConfigSchema,
 } from "@alepha/server";
-import {
-	type HttpClientLink,
-	LinkProvider,
-	type VirtualAction,
-} from "@alepha/server-links";
+import { LinkProvider, type VirtualAction } from "@alepha/server-links";
 import { useEffect, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 import { useInject } from "./useInject.ts";
@@ -19,7 +15,6 @@ export const useSchema = <TConfig extends RequestConfigSchema>(
 	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>,
 	);
@@ -34,7 +29,7 @@ export const useSchema = <TConfig extends RequestConfigSchema>(
 		};
 
 		httpClient
-			.fetch(`${linkProvider.URL_LINKS}/${name}/schema`, {}, opts)
+			.fetch(`${LinkProvider.path.apiLinks}/${name}/schema`, {}, opts)
 			.then((it) => setSchema(it.data as UseSchemaReturn<TConfig>));
 	}, [name]);
 
@@ -54,26 +49,26 @@ 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 ?? [];
+		const linkProvider = alepha.inject(LinkProvider);
 
 		// check if user can access the link
-		const can = links.find((it) => it.name === name);
+		const can = linkProvider
+			.getServerLinks()
+			.find((link) => link.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;
+			const schema = 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 :)
+				// attach to user link, it will be used in the client during hydration
 				can.schema = schema;
 				return schema;
 			}
 		}
+
 		return { loading: true };
 	}
 
@@ -81,7 +76,7 @@ export const ssrSchemaLoading = (alepha: Alepha, name: string) => {
 	// check if we have the schema already loaded
 	const schema = alepha
 		.inject(LinkProvider)
-		.links?.find((it) => it.name === name)?.schema;
+		.links.find((it) => it.name === name)?.schema;
 
 	// yes!
 	if (schema) {

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(() => {
@@ -23,13 +31,6 @@ export const useStore = <Key extends keyof State>(
 		});
 	}, []);
 
-	if (!alepha.isBrowser()) {
-		const value = alepha.context.get(key) as State[Key];
-		if (value !== null) {
-			return [value, (_: State[Key]) => {}] as const;
-		}
-	}
-
 	return [
 		state,
 		(value: State[Key]) => {