@alepha/react 0.9.3 → 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.3",
+	"version": "0.9.5",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -17,27 +17,32 @@
 		"src"
 	],
 	"dependencies": {
-		"@alepha/core": "0.9.3",
-		"@alepha/router": "0.9.3",
-		"@alepha/server": "0.9.3",
-		"@alepha/server-cache": "0.9.3",
-		"@alepha/server-links": "0.9.3",
-		"@alepha/server-static": "0.9.3",
+		"@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.9",
-		"@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.13.2",
+		"tsdown": "^0.15.1",
+		"typescript": "^5.9.2",
 		"vitest": "^3.2.4"
 	},
 	"peerDependencies": {
-		"@types/react": "^19",
 		"react": "^19"
 	},
 	"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,12 +1,15 @@
-import type { ReactNode } from "react";
-import { useContext, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
+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 { 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);
 }
 
 /**
@@ -16,7 +19,7 @@ export interface NestedViewProps {
  *
  * @example
  * ```tsx
- * import { NestedView } from "@alepha/react";
+ * import { NestedView } from "alepha/react";
  *
  * class App {
  *   parent = $page({
@@ -31,38 +34,124 @@ export interface NestedViewProps {
  * ```
  */
 const NestedView = (props: NestedViewProps) => {
-	const app = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	const index = layer?.index ?? 0;
+	const index = use(RouterLayerContext)?.index ?? 0;
+	const state = useRouterState();
 
 	const [view, setView] = useState<ReactNode | undefined>(
-		app?.state.layers[index]?.element,
+		state.layers[index]?.element,
 	);
 
+	const [animation, setAnimation] = useState("");
+	const animationExitDuration = useRef<number>(0);
+	const animationExitNow = useRef<number>(0);
+
 	useRouterEvents(
 		{
-			onEnd: ({ state, context }) => {
-				if (app) {
-					app.context = context;
+			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),
+						);
+					}
 				}
-				if (!state.layers[index]?.cache) {
-					setView(state.layers[index]?.element);
+				// --------- 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 ---------
 				}
 			},
 		},
-		[app],
+		[],
 	);
 
-	if (!app) {
-		throw new Error("NestedView must be used within a RouterContext.");
+	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 ---------
 
-	const element = view ?? props.children ?? null;
+	if (props.errorBoundary === false) {
+		return <>{element}</>;
+	}
+
+	if (props.errorBoundary) {
+		return (
+			<ErrorBoundary fallback={props.errorBoundary}>{element}</ErrorBoundary>
+		);
+	}
 
 	return (
 		<ErrorBoundary
 			fallback={(error) => {
-				return app.context.onError?.(error, app.context) as ReactNode;
+				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}
@@ -70,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/components/NotFound.tsx

@@ -16,7 +16,7 @@ export default function NotFoundPage(props: { style?: CSSProperties }) {
 			}}
 		>
 			<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

@@ -1,4 +1,5 @@
 import {
+	AlephaError,
 	type Async,
 	createDescriptor,
 	Descriptor,
@@ -11,7 +12,7 @@ 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";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 
 /**
  * Main descriptor for defining a React route in the application.
@@ -179,11 +180,55 @@ 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 = (
 	error: Error,
-	context: PageReactContext,
+	state: ReactRouterState,
 ) => ReactNode | Redirection | undefined;
 
 export class PageDescriptor<
@@ -211,7 +256,28 @@ 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 {
+		// 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 || "";
 	}
 }
 
@@ -231,13 +297,21 @@ 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;
 }
 
 export interface PageDescriptorRenderResult {
 	html: string;
-	context: PageReactContext;
+	state: ReactRouterState;
+	redirect?: string;
 }
 
 export interface PageRequestConfig<
@@ -255,4 +329,25 @@ 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">;
+
+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/errors/Redirection.ts

@@ -1,10 +1,13 @@
-import type { HrefLike } from "../hooks/RouterHookApi.ts";
-
+/**
+ * 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 page: HrefLike;
+	public readonly redirect: string;
 
-	constructor(page: HrefLike) {
+	constructor(redirect: string) {
 		super("Redirection");
-		this.page = page;
+		this.redirect = redirect;
 	}
 }

package/src/hooks/useActive.ts

@@ -1,56 +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 => {
-	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 [current, setCurrent] = useState(ctx.state.pathname);
-	const href = useMemo(
-		() => router.createHref(path ?? "", layer),
-		[path, layer],
-	);
+export interface UseActiveOptions {
+	href: string;
+	startWith?: boolean;
+}
 
+export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
+	const router = useRouter();
 	const [isPending, setPending] = useState(false);
+	const state = useRouterState();
+	const current = state.url.pathname;
 
-	// TODO: loose [default] or strict
-	// TODO: startWith: true (e.g. /p/1 should match /p/1/2)
-	const isActive =
+	const options: UseActiveOptions =
+		typeof args === "string" ? { href: args } : { ...args, href: args.href };
+	const href = options.href;
+
+	let isActive =
 		current === href || current === `${href}/` || `${current}/` === href;
 
-	useRouterEvents(
-		{
-			onEnd: ({ state }) => {
-				path ? setCurrent(state.pathname) : undefined;
-			},
-		},
-		[path],
-	);
+	if (options.startWith && !isActive) {
+		isActive = current.startsWith(href);
+	}
 
 	return {
 		isPending,
 		isActive,
 		anchorProps: {
-			href,
-			onClick: (ev?: any) => {
+			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);
-				});
+				}
 			},
 		},
 	};
@@ -60,5 +51,4 @@ export interface UseActiveHook {
 	isActive: boolean;
 	anchorProps: AnchorProps;
 	isPending: boolean;
-	name?: string;
 }

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

@@ -4,11 +4,14 @@ import {
 	LinkProvider,
 } from "@alepha/server-links";
 import { useInject } from "./useInject.ts";
-import { useStore } from "./useStore.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> => {
-	useStore("user" as any);
-	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)));
 };