@alepha/react 0.9.4 → 0.10.0

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.10.0",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -17,30 +17,33 @@
 		"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",
-		"react-dom": "^19.1.1"
+		"@alepha/core": "0.10.0",
+		"@alepha/datetime": "0.10.0",
+		"@alepha/logger": "0.10.0",
+		"@alepha/router": "0.10.0",
+		"@alepha/server": "0.10.0",
+		"@alepha/server-cache": "0.10.0",
+		"@alepha/server-links": "0.10.0",
+		"@alepha/server-static": "0.10.0"
 	},
 	"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",
+		"react-dom": "^19.1.1",
+		"tsdown": "^0.15.3",
 		"typescript": "^5.9.2",
 		"vitest": "^3.2.4"
 	},
 	"peerDependencies": {
-		"react": "^19"
+		"react": "*",
+		"react-dom": "*"
 	},
 	"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,
@@ -15,6 +16,91 @@ import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 
 /**
  * Main descriptor for defining a React route in the application.
+ *
+ * The $page descriptor is the core building block for creating type-safe, SSR-enabled React routes.
+ * It provides a declarative way to define pages with powerful features:
+ *
+ * **Routing & Navigation**
+ * - URL pattern matching with parameters (e.g., `/users/:id`)
+ * - Nested routing with parent-child relationships
+ * - Type-safe URL parameter and query string validation
+ *
+ * **Data Loading**
+ * - Server-side data fetching with the `resolve` function
+ * - Automatic serialization and hydration for SSR
+ * - Access to request context, URL params, and parent data
+ *
+ * **Component Loading**
+ * - Direct component rendering or lazy loading for code splitting
+ * - Client-only rendering when browser APIs are needed
+ * - Automatic fallback handling during hydration
+ *
+ * **Performance Optimization**
+ * - Static generation for pre-rendered pages at build time
+ * - Server-side caching with configurable TTL and providers
+ * - Code splitting through lazy component loading
+ *
+ * **Error Handling**
+ * - Custom error handlers with support for redirects
+ * - Hierarchical error handling (child → parent)
+ * - HTTP status code handling (404, 401, etc.)
+ *
+ * **Page Animations**
+ * - CSS-based enter/exit animations
+ * - Dynamic animations based on page state
+ * - Custom timing and easing functions
+ *
+ * **Lifecycle Management**
+ * - Server response hooks for headers and status codes
+ * - Page leave handlers for cleanup (browser only)
+ * - Permission-based access control
+ *
+ * @example Simple page with data fetching
+ * ```typescript
+ * const userProfile = $page({
+ *   path: "/users/:id",
+ *   schema: {
+ *     params: t.object({ id: t.int() }),
+ *     query: t.object({ tab: t.optional(t.string()) })
+ *   },
+ *   resolve: async ({ params }) => {
+ *     const user = await userApi.getUser(params.id);
+ *     return { user };
+ *   },
+ *   lazy: () => import("./UserProfile.tsx")
+ * });
+ * ```
+ *
+ * @example Nested routing with error handling
+ * ```typescript
+ * const projectSection = $page({
+ *   path: "/projects/:id",
+ *   children: () => [projectBoard, projectSettings],
+ *   resolve: async ({ params }) => {
+ *     const project = await projectApi.get(params.id);
+ *     return { project };
+ *   },
+ *   errorHandler: (error) => {
+ *     if (HttpError.is(error, 404)) {
+ *       return <ProjectNotFound />;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Static generation with caching
+ * ```typescript
+ * const blogPost = $page({
+ *   path: "/blog/:slug",
+ *   static: {
+ *     entries: posts.map(p => ({ params: { slug: p.slug } }))
+ *   },
+ *   resolve: async ({ params }) => {
+ *     const post = await loadPost(params.slug);
+ *     return { post };
+ *   }
+ * });
+ * ```
  */
 export const $page = <
 	TConfig extends PageConfigSchema = PageConfigSchema,
@@ -179,6 +265,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 +341,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 +382,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 +396,7 @@ export interface PageDescriptorRenderOptions {
 export interface PageDescriptorRenderResult {
 	html: string;
 	state: ReactRouterState;
+	redirect?: string;
 }
 
 export interface PageRequestConfig<
@@ -268,3 +417,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/useAlepha.ts

@@ -11,7 +11,7 @@ import { AlephaContext } from "../contexts/AlephaContext.ts";
  *
  * - alepha.state() for state management
  * - alepha.inject() for dependency injection
- * - alepha.emit() for event handling
+ * - alepha.events.emit() for event handling
  * etc...
  */
 export const useAlepha = (): Alepha => {

package/src/hooks/useQueryParams.ts

@@ -9,14 +9,14 @@ import { useRouter } from "./useRouter.ts";
 export const useQueryParams = <T extends TObject>(
 	schema: T,
 	options: UseQueryParamsHookOptions = {},
-): [Static<T>, (data: Static<T>) => void] => {
+): [Partial<Static<T>>, (data: Static<T>) => void] => {
 	const alepha = useAlepha();
 
 	const key = options.key ?? "q";
 	const router = useRouter();
 	const querystring = router.query[key];
 
-	const [queryParams, setQueryParams] = useState(
+	const [queryParams = {}, setQueryParams] = useState<Static<T> | undefined>(
 		decode(alepha, schema, router.query[key]),
 	);
 
@@ -47,10 +47,14 @@ const encode = (alepha: Alepha, schema: TObject, data: any) => {
 	return btoa(JSON.stringify(alepha.parse(schema, data)));
 };
 
-const decode = (alepha: Alepha, schema: TObject, data: any) => {
+const decode = <T extends TObject>(
+	alepha: Alepha,
+	schema: T,
+	data: any,
+): Static<T> | undefined => {
 	try {
 		return alepha.parse(schema, JSON.parse(atob(decodeURIComponent(data))));
-	} catch (_error) {
-		return {};
+	} catch {
+		return;
 	}
 };

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.events.on("react:transition:begin", cb(onBegin)));
 		}
 
 		if (onEnd) {
-			subs.push(
-				alepha.on("react:transition:end", {
-					callback: onEnd,
-				}),
-			);
+			subs.push(alepha.events.on("react:transition:end", cb(onEnd)));
 		}
 
 		if (onError) {
-			subs.push(
-				alepha.on("react:transition:error", {
-					callback: onError,
-				}),
-			);
+			subs.push(alepha.events.on("react:transition:error", cb(onError)));
+		}
+
+		if (onSuccess) {
+			subs.push(alepha.events.on("react:transition:success", cb(onSuccess)));
 		}
 
 		return () => {

package/src/hooks/useStore.ts

@@ -12,19 +12,19 @@ export const useStore = <Key extends keyof State>(
 	const alepha = useAlepha();
 
 	useMemo(() => {
-		if (defaultValue != null && alepha.state(key) == null) {
-			alepha.state(key, defaultValue);
+		if (defaultValue != null && alepha.state.get(key) == null) {
+			alepha.state.set(key, defaultValue);
 		}
 	}, [defaultValue]);
 
-	const [state, setState] = useState(alepha.state(key));
+	const [state, setState] = useState(alepha.state.get(key));
 
 	useEffect(() => {
 		if (!alepha.isBrowser()) {
 			return;
 		}
 
-		return alepha.on("state:mutate", (ev) => {
+		return alepha.events.on("state:mutate", (ev) => {
 			if (ev.key === key) {
 				setState(ev.value);
 			}
@@ -34,7 +34,7 @@ export const useStore = <Key extends keyof State>(
 	return [
 		state,
 		(value: State[Key]) => {
-			alepha.state(key, value);
+			alepha.state.set(key, value);
 		},
 	] as const;
 };

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