@alepha/react 0.9.4 → 0.9.5

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alepha/react",
 	"description": "Build server-side rendered (SSR) or single-page React applications.",
-	"version": "0.9.4",
+	"version": "0.9.5",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -17,21 +17,22 @@
 		"src"
 	],
 	"dependencies": {
-		"@alepha/core": "0.9.4",
-		"@alepha/datetime": "0.9.4",
-		"@alepha/logger": "0.9.4",
-		"@alepha/router": "0.9.4",
-		"@alepha/server": "0.9.4",
-		"@alepha/server-cache": "0.9.4",
-		"@alepha/server-links": "0.9.4",
-		"@alepha/server-static": "0.9.4",
+		"@alepha/core": "0.9.5",
+		"@alepha/datetime": "0.9.5",
+		"@alepha/logger": "0.9.5",
+		"@alepha/router": "0.9.5",
+		"@alepha/server": "0.9.5",
+		"@alepha/server-cache": "0.9.5",
+		"@alepha/server-links": "0.9.5",
+		"@alepha/server-static": "0.9.5",
 		"react-dom": "^19.1.1"
 	},
 	"devDependencies": {
-		"@types/react": "^19.1.10",
-		"@types/react-dom": "^19.1.7",
+		"@biomejs/biome": "^2.2.4",
+		"@types/react": "^19.1.13",
+		"@types/react-dom": "^19.1.9",
 		"react": "^19.1.1",
-		"tsdown": "^0.14.1",
+		"tsdown": "^0.15.1",
 		"typescript": "^5.9.2",
 		"vitest": "^3.2.4"
 	},
@@ -41,6 +42,7 @@
 	"scripts": {
 		"check": "tsc",
 		"test": "vitest run",
+		"lint": "biome check --write --unsafe",
 		"build": "tsdown -c ../../tsdown.config.ts"
 	},
 	"homepage": "https://github.com/feunard/alepha",

package/src/components/Link.tsx

@@ -1,18 +1,15 @@
-import type React from "react";
 import type { AnchorHTMLAttributes } from "react";
 import { useRouter } from "../hooks/useRouter.ts";
 
 export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-	to: string;
-	children?: React.ReactNode;
+	href: string;
 }
 
 const Link = (props: LinkProps) => {
 	const router = useRouter();
-	const { to, ...anchorProps } = props;
 
 	return (
-		<a {...router.anchor(to)} {...anchorProps}>
+		<a {...props} {...router.anchor(props.href)}>
 			{props.children}
 		</a>
 	);

package/src/components/NestedView.tsx

@@ -1,13 +1,15 @@
-import type { ReactNode } from "react";
-import { useContext, useState } from "react";
+import { memo, type ReactNode, use, useRef, useState } from "react";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import type { PageAnimation } from "../descriptors/$page.ts";
 import { Redirection } from "../errors/Redirection.ts";
-import { useAlepha } from "../hooks/useAlepha.ts";
 import { useRouterEvents } from "../hooks/useRouterEvents.ts";
+import { useRouterState } from "../hooks/useRouterState.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import ErrorBoundary from "./ErrorBoundary.tsx";
 
 export interface NestedViewProps {
 	children?: ReactNode;
+	errorBoundary?: false | ((error: Error) => ReactNode);
 }
 
 /**
@@ -17,7 +19,7 @@ export interface NestedViewProps {
  *
  * @example
  * ```tsx
- * import { NestedView } from "@alepha/react";
+ * import { NestedView } from "alepha/react";
  *
  * class App {
  *   parent = $page({
@@ -32,30 +34,115 @@ export interface NestedViewProps {
  * ```
  */
 const NestedView = (props: NestedViewProps) => {
-	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 index = use(RouterLayerContext)?.index ?? 0;
+	const state = useRouterState();
 
 	const [view, setView] = useState<ReactNode | undefined>(
 		state.layers[index]?.element,
 	);
 
+	const [animation, setAnimation] = useState("");
+	const animationExitDuration = useRef<number>(0);
+	const animationExitNow = useRef<number>(0);
+
 	useRouterEvents(
 		{
-			onEnd: ({ state }) => {
-				if (!state.layers[index]?.cache) {
-					setView(state.layers[index]?.element);
+			onBegin: async ({ previous, state }) => {
+				// --------- Animations Begin ---------
+				const layer = previous.layers[index];
+				if (`${state.url.pathname}/`.startsWith(`${layer?.path}/`)) {
+					return;
+				}
+
+				const animationExit = parseAnimation(
+					layer.route?.animation,
+					state,
+					"exit",
+				);
+
+				if (animationExit) {
+					const duration = animationExit.duration || 200;
+					animationExitNow.current = Date.now();
+					animationExitDuration.current = duration;
+					setAnimation(animationExit.animation);
+				} else {
+					animationExitNow.current = 0;
+					animationExitDuration.current = 0;
+					setAnimation("");
+				}
+				// --------- Animations End ---------
+			},
+			onEnd: async ({ state }) => {
+				const layer = state.layers[index];
+
+				// --------- Animations Begin ---------
+				if (animationExitNow.current) {
+					const duration = animationExitDuration.current;
+					const diff = Date.now() - animationExitNow.current;
+					if (diff < duration) {
+						await new Promise((resolve) =>
+							setTimeout(resolve, duration - diff),
+						);
+					}
+				}
+				// --------- Animations End ---------
+
+				if (!layer?.cache) {
+					setView(layer?.element);
+
+					// --------- Animations Begin ---------
+					const animationEnter = parseAnimation(
+						layer?.route?.animation,
+						state,
+						"enter",
+					);
+
+					if (animationEnter) {
+						setAnimation(animationEnter.animation);
+					} else {
+						setAnimation("");
+					}
+					// --------- Animations End ---------
 				}
 			},
 		},
 		[],
 	);
 
-	const element = view ?? props.children ?? null;
+	let element = view ?? props.children ?? null;
+
+	// --------- Animations Begin ---------
+	if (animation) {
+		element = (
+			<div
+				style={{
+					display: "flex",
+					flex: 1,
+					height: "100%",
+					width: "100%",
+					position: "relative",
+					overflow: "hidden",
+				}}
+			>
+				<div
+					style={{ height: "100%", width: "100%", display: "flex", animation }}
+				>
+					{element}
+				</div>
+			</div>
+		);
+	}
+	// --------- Animations End ---------
+
+	if (props.errorBoundary === false) {
+		return <>{element}</>;
+	}
+
+	if (props.errorBoundary) {
+		return (
+			<ErrorBoundary fallback={props.errorBoundary}>{element}</ErrorBoundary>
+		);
+	}
 
 	return (
 		<ErrorBoundary
@@ -72,4 +159,60 @@ const NestedView = (props: NestedViewProps) => {
 	);
 };
 
-export default NestedView;
+export default memo(NestedView);
+
+function parseAnimation(
+	animationLike: PageAnimation | undefined,
+	state: ReactRouterState,
+	type: "enter" | "exit" = "enter",
+):
+	| {
+			duration: number;
+			animation: string;
+	  }
+	| undefined {
+	if (!animationLike) {
+		return undefined;
+	}
+
+	const DEFAULT_DURATION = 300;
+
+	const animation =
+		typeof animationLike === "function" ? animationLike(state) : animationLike;
+
+	if (typeof animation === "string") {
+		if (type === "exit") {
+			return;
+		}
+		return {
+			duration: DEFAULT_DURATION,
+			animation: `${DEFAULT_DURATION}ms ${animation}`,
+		};
+	}
+
+	if (typeof animation === "object") {
+		const anim = animation[type];
+		const duration =
+			typeof anim === "object"
+				? (anim.duration ?? DEFAULT_DURATION)
+				: DEFAULT_DURATION;
+		const name = typeof anim === "object" ? anim.name : anim;
+
+		if (type === "exit") {
+			const timing = typeof anim === "object" ? (anim.timing ?? "") : "";
+			return {
+				duration,
+				animation: `${duration}ms ${timing} ${name}`,
+			};
+		}
+
+		const timing = typeof anim === "object" ? (anim.timing ?? "") : "";
+
+		return {
+			duration,
+			animation: `${duration}ms ${timing} ${name}`,
+		};
+	}
+
+	return undefined;
+}

package/src/descriptors/$page.ts

@@ -1,4 +1,5 @@
 import {
+	AlephaError,
 	type Async,
 	createDescriptor,
 	Descriptor,
@@ -179,6 +180,50 @@ export interface PageDescriptorOptions<
 	 * Called when user leaves the page. (browser only)
 	 */
 	onLeave?: () => void;
+
+	/**
+	 * @experimental
+	 *
+	 * Add a css animation when the page is loaded or unloaded.
+	 * It uses CSS animations, so you need to define the keyframes in your CSS.
+	 *
+	 * @example Simple animation name
+	 * ```ts
+	 * animation: "fadeIn"
+	 * ```
+	 *
+	 * CSS example:
+	 * ```css
+	 * @keyframes fadeIn {
+	 *  from { opacity: 0; }
+	 *  to { opacity: 1; }
+	 * }
+	 * ```
+	 *
+	 * @example Detailed animation
+	 * ```ts
+	 * animation: {
+	 *   enter: { name: "fadeIn", duration: 300 },
+	 *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
+	 * }
+	 * ```
+	 *
+	 * @example Only exit animation
+	 * ```ts
+	 * animation: {
+	 *   exit: "fadeOut"
+	 * }
+	 * ```
+	 *
+	 * @example With custom timing function
+	 * ```ts
+	 * animation: {
+	 *   enter: { name: "fadeIn", duration: 300, timing: "cubic-bezier(0.4, 0, 0.2, 1)" },
+	 *   exit: { name: "fadeOut", duration: 200, timing: "ease-in-out" },
+	 * }
+	 * ```
+	 */
+	animation?: PageAnimation;
 }
 
 export type ErrorHandler = (
@@ -211,7 +256,18 @@ export class PageDescriptor<
 	public async render(
 		options?: PageDescriptorRenderOptions,
 	): Promise<PageDescriptorRenderResult> {
-		throw new Error("render method is not implemented in this environment");
+		throw new AlephaError(
+			"render() method is not implemented in this environment",
+		);
+	}
+
+	public async fetch(options?: PageDescriptorRenderOptions): Promise<{
+		html: string;
+		response: Response;
+	}> {
+		throw new AlephaError(
+			"fetch() method is not implemented in this environment",
+		);
 	}
 
 	public match(url: string): boolean {
@@ -241,6 +297,13 @@ export type TPropsParentDefault = {};
 export interface PageDescriptorRenderOptions {
 	params?: Record<string, string>;
 	query?: Record<string, string>;
+
+	/**
+	 * If true, the HTML layout will be included in the response.
+	 * If false, only the page content will be returned.
+	 *
+	 * @default true
+	 */
 	html?: boolean;
 	hydration?: boolean;
 }
@@ -248,6 +311,7 @@ export interface PageDescriptorRenderOptions {
 export interface PageDescriptorRenderResult {
 	html: string;
 	state: ReactRouterState;
+	redirect?: string;
 }
 
 export interface PageRequestConfig<
@@ -268,3 +332,22 @@ export type PageResolve<
 > = PageRequestConfig<TConfig> &
 	TPropsParent &
 	Omit<ReactRouterState, "layers" | "onError">;
+
+export type PageAnimation =
+	| PageAnimationObject
+	| ((state: ReactRouterState) => PageAnimationObject | undefined);
+
+type PageAnimationObject =
+	| CssAnimationName
+	| {
+			enter?: CssAnimation | CssAnimationName;
+			exit?: CssAnimation | CssAnimationName;
+	  };
+
+type CssAnimationName = string;
+
+type CssAnimation = {
+	name: string;
+	duration?: number;
+	timing?: string;
+};

package/src/hooks/useActive.ts

@@ -51,5 +51,4 @@ export interface UseActiveHook {
 	isActive: boolean;
 	anchorProps: AnchorProps;
 	isPending: boolean;
-	name?: string;
 }

package/src/hooks/useRouterEvents.ts

@@ -1,15 +1,23 @@
+import type { Hooks } from "@alepha/core";
 import { useEffect } from "react";
-import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { useAlepha } from "./useAlepha.ts";
 
+type Hook<T extends keyof Hooks> =
+	| ((ev: Hooks[T]) => void)
+	| {
+			priority?: "first" | "last";
+			callback: (ev: Hooks[T]) => void;
+	  };
+
 /**
  * Subscribe to various router events.
  */
 export const useRouterEvents = (
 	opts: {
-		onBegin?: (ev: { state: ReactRouterState }) => void;
-		onEnd?: (ev: { state: ReactRouterState }) => void;
-		onError?: (ev: { state: ReactRouterState; error: Error }) => void;
+		onBegin?: Hook<"react:transition:begin">;
+		onError?: Hook<"react:transition:error">;
+		onEnd?: Hook<"react:transition:end">;
+		onSuccess?: Hook<"react:transition:success">;
 	} = {},
 	deps: any[] = [],
 ) => {
@@ -20,33 +28,33 @@ export const useRouterEvents = (
 			return;
 		}
 
+		const cb = <T extends keyof Hooks>(callback: Hook<T>) => {
+			if (typeof callback === "function") {
+				return { callback };
+			}
+			return callback;
+		};
+
 		const subs: Function[] = [];
 		const onBegin = opts.onBegin;
 		const onEnd = opts.onEnd;
 		const onError = opts.onError;
+		const onSuccess = opts.onSuccess;
 
 		if (onBegin) {
-			subs.push(
-				alepha.on("react:transition:begin", {
-					callback: onBegin,
-				}),
-			);
+			subs.push(alepha.on("react:transition:begin", cb(onBegin)));
 		}
 
 		if (onEnd) {
-			subs.push(
-				alepha.on("react:transition:end", {
-					callback: onEnd,
-				}),
-			);
+			subs.push(alepha.on("react:transition:end", cb(onEnd)));
 		}
 
 		if (onError) {
-			subs.push(
-				alepha.on("react:transition:error", {
-					callback: onError,
-				}),
-			);
+			subs.push(alepha.on("react:transition:error", cb(onError)));
+		}
+
+		if (onSuccess) {
+			subs.push(alepha.on("react:transition:success", cb(onSuccess)));
 		}
 
 		return () => {

package/src/index.browser.ts

@@ -3,6 +3,7 @@ import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
 import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
+import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
 import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
 import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
@@ -24,6 +25,7 @@ export const AlephaReact = $module({
 		ReactBrowserRouterProvider,
 		ReactBrowserProvider,
 		ReactRouter,
+		ReactBrowserRendererProvider,
 	],
 	register: (alepha) =>
 		alepha
@@ -32,5 +34,6 @@ export const AlephaReact = $module({
 			.with(ReactPageProvider)
 			.with(ReactBrowserProvider)
 			.with(ReactBrowserRouterProvider)
+			.with(ReactBrowserRendererProvider)
 			.with(ReactRouter),
 });

package/src/index.ts

@@ -2,7 +2,8 @@ import { $module } from "@alepha/core";
 import { AlephaServer, type ServerRequest } from "@alepha/server";
 import { AlephaServerCache } from "@alepha/server-cache";
 import { AlephaServerLinks } from "@alepha/server-links";
-import { $page } from "./descriptors/$page.ts";
+import type { ReactNode } from "react";
+import { $page, type PageAnimation } from "./descriptors/$page.ts";
 import type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
 import {
 	ReactPageProvider,
@@ -37,11 +38,15 @@ declare module "@alepha/core" {
 		};
 		// -----------------------------------------------------------------------------------------------------------------
 		"react:browser:render": {
+			root: HTMLDivElement;
+			element: ReactNode;
 			state: ReactRouterState;
 			hydration?: ReactHydrationState;
 		};
 		"react:transition:begin": {
+			previous: ReactRouterState;
 			state: ReactRouterState;
+			animation?: PageAnimation;
 		};
 		"react:transition:success": {
 			state: ReactRouterState;

package/src/providers/ReactBrowserProvider.ts

@@ -10,7 +10,6 @@ import {
 import { DateTimeProvider } from "@alepha/datetime";
 import { $logger } from "@alepha/logger";
 import { LinkProvider } from "@alepha/server-links";
-import { createRoot, hydrateRoot, type Root } from "react-dom/client";
 import { ReactBrowserRouterProvider } from "./ReactBrowserRouterProvider.ts";
 import type {
 	PreviousLayerData,
@@ -37,7 +36,6 @@ export class ReactBrowserProvider {
 	protected readonly alepha = $inject(Alepha);
 	protected readonly router = $inject(ReactBrowserRouterProvider);
 	protected readonly dateTimeProvider = $inject(DateTimeProvider);
-	protected root?: Root;
 
 	public options: ReactBrowserRendererOptions = {
 		scrollRestoration: "top",
@@ -150,6 +148,7 @@ export class ReactBrowserProvider {
 		await this.render({
 			url,
 			previous: options.force ? [] : this.state.layers,
+			meta: options.meta,
 		});
 
 		// when redirecting in browser
@@ -161,9 +160,7 @@ export class ReactBrowserProvider {
 		this.pushState(url, options.replace);
 	}
 
-	protected async render(
-		options: { url?: string; previous?: PreviousLayerData[] } = {},
-	): Promise<void> {
+	protected async render(options: RouterRenderOptions = {}): Promise<void> {
 		const previous = options.previous ?? this.state.layers;
 		const url = options.url ?? this.url;
 		const start = this.dateTimeProvider.now();
@@ -180,6 +177,7 @@ export class ReactBrowserProvider {
 		const redirect = await this.router.transition(
 			new URL(`http://localhost${url}`),
 			previous,
+			options.meta,
 		);
 
 		if (redirect) {
@@ -215,7 +213,8 @@ export class ReactBrowserProvider {
 		handler: () => {
 			if (
 				this.options.scrollRestoration === "top" &&
-				typeof window !== "undefined"
+				typeof window !== "undefined" &&
+				!this.alepha.isTest()
 			) {
 				this.log.trace("Restoring scroll position to top");
 				window.scrollTo(0, 0);
@@ -241,14 +240,13 @@ export class ReactBrowserProvider {
 			await this.render({ previous });
 
 			const element = this.router.root(this.state);
-			if (hydration?.layers) {
-				this.root = hydrateRoot(this.getRootElement(), element);
-				this.log.info("Hydrated root element");
-			} else {
-				this.root ??= createRoot(this.getRootElement());
-				this.root.render(element);
-				this.log.info("Created root element");
-			}
+
+			await this.alepha.emit("react:browser:render", {
+				element,
+				root: this.getRootElement(),
+				hydration,
+				state: this.state,
+			});
 
 			window.addEventListener("popstate", () => {
 				// when you update silently queryParams or hash, skip rendering
@@ -274,6 +272,7 @@ export interface RouterGoOptions {
 	match?: TransitionOptions;
 	params?: Record<string, string>;
 	query?: Record<string, string>;
+	meta?: Record<string, any>;
 
 	/**
 	 * Recreate the whole page, ignoring the current state.
@@ -286,3 +285,9 @@ export type ReactHydrationState = {
 } & {
 	[key: string]: any;
 };
+
+export interface RouterRenderOptions {
+	url?: string;
+	previous?: PreviousLayerData[];
+	meta?: Record<string, any>;
+}

package/src/providers/ReactBrowserRendererProvider.ts

@@ -0,0 +1,22 @@
+import { $hook } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+
+export class ReactBrowserRendererProvider {
+	protected readonly log = $logger();
+	protected root?: Root;
+
+	protected readonly onBrowserRender = $hook({
+		on: "react:browser:render",
+		handler: async ({ hydration, root, element }) => {
+			if (hydration?.layers) {
+				this.root = hydrateRoot(root, element);
+				this.log.info("Hydrated root element");
+			} else {
+				this.root ??= createRoot(root);
+				this.root.render(element);
+				this.log.info("Created root element");
+			}
+		},
+	});
+}

package/src/providers/ReactBrowserRouterProvider.ts

@@ -43,6 +43,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 	public async transition(
 		url: URL,
 		previous: PreviousLayerData[] = [],
+		meta = {},
 	): Promise<string | void> {
 		const { pathname, search } = url;
 
@@ -52,11 +53,15 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 			params: {},
 			layers: [],
 			onError: () => null,
+			meta,
 		};
 
 		const state = entry as ReactRouterState;
 
-		await this.alepha.emit("react:transition:begin", { state });
+		await this.alepha.emit("react:transition:begin", {
+			previous: this.alepha.state("react.router.state")!,
+			state,
+		});
 
 		try {
 			const { route, params } = this.match(pathname);
@@ -119,11 +124,11 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 			}
 		}
 
+		this.alepha.state("react.router.state", state);
+
 		await this.alepha.emit("react:transition:end", {
 			state,
 		});
-
-		this.alepha.state("react.router.state", state);
 	}
 
 	public root(state: ReactRouterState): ReactNode {