@alepha/react 0.9.4 → 0.10.0

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",
@@ -63,7 +61,7 @@ export class ReactBrowserProvider {
 	};
 
 	public get state(): ReactRouterState {
-		return this.alepha.state("react.router.state")!;
+		return this.alepha.state.get("react.router.state")!;
 	}
 
 	/**
@@ -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);
@@ -233,7 +232,7 @@ export class ReactBrowserProvider {
 				// low budget, but works for now
 				for (const [key, value] of Object.entries(hydration)) {
 					if (key !== "layers") {
-						this.alepha.state(key as keyof State, value);
+						this.alepha.state.set(key as keyof State, value);
 					}
 				}
 			}
@@ -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.events.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.events.emit("react:transition:begin", {
+			previous: this.alepha.state.get("react.router.state")!,
+			state,
+		});
 
 		try {
 			const { route, params } = this.match(pathname);
@@ -91,7 +96,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 				});
 			}
 
-			await this.alepha.emit("react:transition:success", { state });
+			await this.alepha.events.emit("react:transition:success", { state });
 		} catch (e) {
 			this.log.error("Transition has failed", e);
 			state.layers = [
@@ -103,7 +108,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 				},
 			];
 
-			await this.alepha.emit("react:transition:error", {
+			await this.alepha.events.emit("react:transition:error", {
 				error: e as Error,
 				state,
 			});
@@ -119,11 +124,11 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 			}
 		}
 
-		await this.alepha.emit("react:transition:end", {
+		this.alepha.state.set("react.router.state", state);
+
+		await this.alepha.events.emit("react:transition:end", {
 			state,
 		});
-
-		this.alepha.state("react.router.state", state);
 	}
 
 	public root(state: ReactRouterState): ReactNode {

package/src/providers/ReactPageProvider.ts

@@ -1,4 +1,12 @@
-import { $env, $hook, $inject, Alepha, type Static, t } from "@alepha/core";
+import {
+	$env,
+	$hook,
+	$inject,
+	Alepha,
+	type Static,
+	type TSchema,
+	t,
+} from "@alepha/core";
 import { $logger } from "@alepha/logger";
 import { createElement, type ReactNode, StrictMode } from "react";
 import ClientOnly from "../components/ClientOnly.tsx";
@@ -99,6 +107,30 @@ export class ReactPageProvider {
 		return root;
 	}
 
+	protected convertStringObjectToObject = (
+		schema?: TSchema,
+		value?: any,
+	): any => {
+		if (t.schema.isObject(schema) && typeof value === "object") {
+			for (const key in schema.properties) {
+				if (
+					t.schema.isObject(schema.properties[key]) &&
+					typeof value[key] === "string"
+				) {
+					try {
+						value[key] = this.alepha.parse(
+							schema.properties[key],
+							decodeURIComponent(value[key]),
+						);
+					} catch (e) {
+						// ignore
+					}
+				}
+			}
+		}
+		return value;
+	};
+
 	/**
 	 * Create a new RouterState based on a given route and request.
 	 * This method resolves the layers for the route, applying any query and params schemas defined in the route.
@@ -126,6 +158,7 @@ export class ReactPageProvider {
 			const config: Record<string, any> = {};
 
 			try {
+				this.convertStringObjectToObject(route.schema?.query, state.query);
 				config.query = route.schema?.query
 					? this.alepha.parse(route.schema.query, state.query)
 					: {};
@@ -331,6 +364,12 @@ export class ReactPageProvider {
 		page: PageRoute,
 		props: Record<string, any>,
 	): Promise<ReactNode> {
+		if (page.lazy && page.component) {
+			this.log.warn(
+				`Page ${page.name} has both lazy and component options, lazy will be used`,
+			);
+		}
+
 		if (page.lazy) {
 			const component = await page.lazy(); // load component
 			return createElement(component.default, props);
@@ -605,6 +644,11 @@ export interface ReactRouterState {
 	 * Query parameters extracted from the URL for the current page.
 	 */
 	query: Record<string, string>;
+
+	/**
+	 * Optional meta information associated with the current page.
+	 */
+	meta: Record<string, any>;
 }
 
 export interface RouterStackItem {

package/src/providers/ReactServerProvider.ts

@@ -12,6 +12,7 @@ import {
 import { $logger } from "@alepha/logger";
 import {
 	type ServerHandler,
+	ServerProvider,
 	ServerRouterProvider,
 	ServerTimingProvider,
 } from "@alepha/server";
@@ -21,6 +22,7 @@ import { renderToString } from "react-dom/server";
 import {
 	$page,
 	type PageDescriptorRenderOptions,
+	type PageDescriptorRenderResult,
 } from "../descriptors/$page.ts";
 import { Redirection } from "../errors/Redirection.ts";
 import type { ReactHydrationState } from "./ReactBrowserProvider.ts";
@@ -53,6 +55,7 @@ export class ReactServerProvider {
 	protected readonly log = $logger();
 	protected readonly alepha = $inject(Alepha);
 	protected readonly pageApi = $inject(ReactPageProvider);
+	protected readonly serverProvider = $inject(ServerProvider);
 	protected readonly serverStaticProvider = $inject(ServerStaticProvider);
 	protected readonly serverRouterProvider = $inject(ServerRouterProvider);
 	protected readonly serverTimingProvider = $inject(ServerTimingProvider);
@@ -61,6 +64,7 @@ export class ReactServerProvider {
 		`<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
 		"is",
 	);
+	protected preprocessedTemplate: PreprocessedTemplate | null = null;
 
 	public readonly onConfigure = $hook({
 		on: "configure",
@@ -70,10 +74,23 @@ export class ReactServerProvider {
 			const ssrEnabled =
 				pages.length > 0 && this.env.REACT_SSR_ENABLED !== false;
 
-			this.alepha.state("react.server.ssr", ssrEnabled);
+			this.alepha.state.set("react.server.ssr", ssrEnabled);
 
 			for (const page of pages) {
 				page.render = this.createRenderFunction(page.name);
+				page.fetch = async (options) => {
+					const response = await fetch(
+						`${this.serverProvider.hostname}/${page.pathname(options)}`,
+					);
+					const html = await response.text();
+					if (options?.html) return { html, response };
+					// take only text inside the root div
+					const match = html.match(this.ROOT_DIV_REGEX);
+					if (match) {
+						return { html: match[3], response };
+					}
+					throw new AlephaError("Invalid HTML response");
+				};
 			}
 
 			// development mode
@@ -134,6 +151,12 @@ export class ReactServerProvider {
 	}
 
 	protected async registerPages(templateLoader: TemplateLoader) {
+		// Preprocess template once
+		const template = await templateLoader();
+		if (template) {
+			this.preprocessedTemplate = this.preprocessTemplate(template);
+		}
+
 		for (const page of this.pageApi.getPages()) {
 			if (page.children?.length) {
 				continue;
@@ -194,7 +217,9 @@ export class ReactServerProvider {
 	 * For testing purposes, creates a render function that can be used.
 	 */
 	protected createRenderFunction(name: string, withIndex = false) {
-		return async (options: PageDescriptorRenderOptions = {}) => {
+		return async (
+			options: PageDescriptorRenderOptions = {},
+		): Promise<PageDescriptorRenderResult> => {
 			const page = this.pageApi.page(name);
 			const url = new URL(this.pageApi.url(name, options));
 
@@ -204,6 +229,7 @@ export class ReactServerProvider {
 				query: options.query ?? {},
 				onError: () => null,
 				layers: [],
+				meta: {},
 			};
 
 			const state = entry as ReactRouterState;
@@ -212,7 +238,7 @@ export class ReactServerProvider {
 				url,
 			});
 
-			await this.alepha.emit("react:server:render:begin", {
+			await this.alepha.events.emit("react:server:render:begin", {
 				state,
 			});
 
@@ -222,11 +248,11 @@ export class ReactServerProvider {
 			);
 
 			if (redirect) {
-				throw new AlephaError("Redirection is not supported in this context");
+				return { state, html: "", redirect };
 			}
 
 			if (!withIndex && !options.html) {
-				this.alepha.state("react.router.state", state);
+				this.alepha.state.set("react.router.state", state);
 
 				return {
 					state,
@@ -234,14 +260,11 @@ export class ReactServerProvider {
 				};
 			}
 
-			const html = this.renderToHtml(
-				this.template ?? "",
-				state,
-				options.hydration,
-			);
+			const template = this.template ?? "";
+			const html = this.renderToHtml(template, state, options.hydration);
 
 			if (html instanceof Redirection) {
-				throw new Error("Redirection is not supported in this context");
+				return { state, html: "", redirect };
 			}
 
 			const result = {
@@ -249,7 +272,7 @@ export class ReactServerProvider {
 				html,
 			};
 
-			await this.alepha.emit("react:server:render:end", result);
+			await this.alepha.events.emit("react:server:render:end", result);
 
 			return result;
 		};
@@ -281,7 +304,7 @@ export class ReactServerProvider {
 			const state = entry as ReactRouterState;
 
 			if (this.alepha.has(ServerLinksProvider)) {
-				this.alepha.state(
+				this.alepha.state.set(
 					"api",
 					await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
 						user: (serverRequest as any).user, // TODO: fix type
@@ -312,7 +335,7 @@ export class ReactServerProvider {
 			// 	return;
 			// }
 
-			await this.alepha.emit("react:server:render:begin", {
+			await this.alepha.events.emit("react:server:render:begin", {
 				request: serverRequest,
 				state,
 			});
@@ -352,7 +375,7 @@ export class ReactServerProvider {
 				html,
 			};
 
-			await this.alepha.emit("react:server:render:end", event);
+			await this.alepha.events.emit("react:server:render:end", event);
 
 			route.onServerResponse?.(serverRequest);
 
@@ -372,7 +395,7 @@ export class ReactServerProvider {
 		const element = this.pageApi.root(state);
 
 		// attach react router state to the http request context
-		this.alepha.state("react.router.state", state);
+		this.alepha.state.set("react.router.state", state);
 
 		this.serverTimingProvider.beginTiming("renderToString");
 		let app = "";
@@ -433,36 +456,80 @@ export class ReactServerProvider {
 		return response.html;
 	}
 
+	protected preprocessTemplate(template: string): PreprocessedTemplate {
+		// Find the body close tag for script injection
+		const bodyCloseMatch = template.match(/<\/body>/i);
+		const bodyCloseIndex = bodyCloseMatch?.index ?? template.length;
+
+		const beforeScript = template.substring(0, bodyCloseIndex);
+		const afterScript = template.substring(bodyCloseIndex);
+
+		// Check if there's an existing root div
+		const rootDivMatch = beforeScript.match(this.ROOT_DIV_REGEX);
+
+		if (rootDivMatch) {
+			// Split around the existing root div content
+			const beforeDiv = beforeScript.substring(0, rootDivMatch.index!);
+			const afterDivStart = rootDivMatch.index! + rootDivMatch[0].length;
+			const afterDiv = beforeScript.substring(afterDivStart);
+
+			const beforeApp = `${beforeDiv}<div${rootDivMatch[1]} id="${this.env.REACT_ROOT_ID}"${rootDivMatch[2]}>`;
+			const afterApp = `</div>${afterDiv}`;
+
+			return { beforeApp, afterApp, beforeScript: "", afterScript };
+		}
+
+		// No existing root div, find body tag to inject new div
+		const bodyMatch = beforeScript.match(/<body([^>]*)>/i);
+		if (bodyMatch) {
+			const beforeBody = beforeScript.substring(
+				0,
+				bodyMatch.index! + bodyMatch[0].length,
+			);
+			const afterBody = beforeScript.substring(
+				bodyMatch.index! + bodyMatch[0].length,
+			);
+
+			const beforeApp = `${beforeBody}<div id="${this.env.REACT_ROOT_ID}">`;
+			const afterApp = `</div>${afterBody}`;
+
+			return { beforeApp, afterApp, beforeScript: "", afterScript };
+		}
+
+		// Fallback: no body tag found, just wrap everything
+		return {
+			beforeApp: `<div id="${this.env.REACT_ROOT_ID}">`,
+			afterApp: `</div>`,
+			beforeScript,
+			afterScript,
+		};
+	}
+
 	protected fillTemplate(
 		response: { html: string },
 		app: string,
 		script: string,
 	) {
-		if (this.ROOT_DIV_REGEX.test(response.html)) {
-			// replace contents of the existing <div id="root">
-			response.html = response.html.replace(
-				this.ROOT_DIV_REGEX,
-				(_match, beforeId, afterId) => {
-					return `<div${beforeId} id="${this.env.REACT_ROOT_ID}"${afterId}>${app}</div>`;
-				},
-			);
-		} else {
-			const bodyOpenTag = /<body([^>]*)>/i;
-			if (bodyOpenTag.test(response.html)) {
-				response.html = response.html.replace(bodyOpenTag, (match) => {
-					return `${match}<div id="${this.env.REACT_ROOT_ID}">${app}</div>`;
-				});
-			}
+		if (!this.preprocessedTemplate) {
+			// Fallback to old logic if preprocessing failed
+			this.preprocessedTemplate = this.preprocessTemplate(response.html);
 		}
 
-		const bodyCloseTagRegex = /<\/body>/i;
-		if (bodyCloseTagRegex.test(response.html)) {
-			response.html = response.html.replace(
-				bodyCloseTagRegex,
-				`${script}</body>`,
-			);
-		}
+		// Pure concatenation - no regex replacements needed
+		response.html =
+			this.preprocessedTemplate.beforeApp +
+			app +
+			this.preprocessedTemplate.afterApp +
+			script +
+			this.preprocessedTemplate.afterScript;
 	}
 }
 
 type TemplateLoader = () => Promise<string | undefined>;
+
+interface PreprocessedTemplate {
+	beforeApp: string;
+	afterApp: string;
+	beforeScript: string;
+	afterScript: string;
+}

package/src/services/ReactRouter.ts

@@ -15,7 +15,7 @@ export class ReactRouter<T extends object> {
 	protected readonly pageApi = $inject(ReactPageProvider);
 
 	public get state(): ReactRouterState {
-		return this.alepha.state("react.router.state")!;
+		return this.alepha.state.get("react.router.state")!;
 	}
 
 	public get pages() {
@@ -33,8 +33,8 @@ export class ReactRouter<T extends object> {
 	public path(
 		name: keyof VirtualRouter<T>,
 		config: {
-			params?: Record<string, string>;
-			query?: Record<string, string>;
+			params?: Record<string, any>;
+			query?: Record<string, any>;
 		} = {},
 	): string {
 		return this.pageApi.pathname(name as string, {
@@ -116,17 +116,14 @@ export class ReactRouter<T extends object> {
 		await this.browser?.go(path as string, options);
 	}
 
-	public anchor(
-		path: string,
-		options?: { params?: Record<string, any> },
-	): AnchorProps;
+	public anchor(path: string, options?: RouterGoOptions): AnchorProps;
 	public anchor(
 		path: keyof VirtualRouter<T>,
-		options?: { params?: Record<string, any> },
+		options?: RouterGoOptions,
 	): AnchorProps;
 	public anchor(
 		path: string | keyof VirtualRouter<T>,
-		options: { params?: Record<string, any> } = {},
+		options: RouterGoOptions = {},
 	): AnchorProps {
 		let href = path as string;