@alepha/react 0.9.5 → 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.5",
+	"version": "0.10.0",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -17,27 +17,28 @@
 		"src"
 	],
 	"dependencies": {
-		"@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"
+		"@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": {
 		"@biomejs/biome": "^2.2.4",
 		"@types/react": "^19.1.13",
 		"@types/react-dom": "^19.1.9",
 		"react": "^19.1.1",
-		"tsdown": "^0.15.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",

package/src/descriptors/$page.ts

@@ -16,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,

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

@@ -42,19 +42,19 @@ export const useRouterEvents = (
 		const onSuccess = opts.onSuccess;
 
 		if (onBegin) {
-			subs.push(alepha.on("react:transition:begin", cb(onBegin)));
+			subs.push(alepha.events.on("react:transition:begin", cb(onBegin)));
 		}
 
 		if (onEnd) {
-			subs.push(alepha.on("react:transition:end", cb(onEnd)));
+			subs.push(alepha.events.on("react:transition:end", cb(onEnd)));
 		}
 
 		if (onError) {
-			subs.push(alepha.on("react:transition:error", cb(onError)));
+			subs.push(alepha.events.on("react:transition:error", cb(onError)));
 		}
 
 		if (onSuccess) {
-			subs.push(alepha.on("react:transition:success", cb(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/providers/ReactBrowserProvider.ts

@@ -61,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")!;
 	}
 
 	/**
@@ -232,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,7 +241,7 @@ export class ReactBrowserProvider {
 
 			const element = this.router.root(this.state);
 
-			await this.alepha.emit("react:browser:render", {
+			await this.alepha.events.emit("react:browser:render", {
 				element,
 				root: this.getRootElement(),
 				hydration,

package/src/providers/ReactBrowserRouterProvider.ts

@@ -58,8 +58,8 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 
 		const state = entry as ReactRouterState;
 
-		await this.alepha.emit("react:transition:begin", {
-			previous: this.alepha.state("react.router.state")!,
+		await this.alepha.events.emit("react:transition:begin", {
+			previous: this.alepha.state.get("react.router.state")!,
 			state,
 		});
 
@@ -96,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 = [
@@ -108,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,
 			});
@@ -124,9 +124,9 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 			}
 		}
 
-		this.alepha.state("react.router.state", state);
+		this.alepha.state.set("react.router.state", state);
 
-		await this.alepha.emit("react:transition:end", {
+		await this.alepha.events.emit("react:transition:end", {
 			state,
 		});
 	}

package/src/providers/ReactPageProvider.ts

@@ -5,7 +5,6 @@ import {
 	Alepha,
 	type Static,
 	type TSchema,
-	TypeGuard,
 	t,
 } from "@alepha/core";
 import { $logger } from "@alepha/logger";
@@ -112,10 +111,10 @@ export class ReactPageProvider {
 		schema?: TSchema,
 		value?: any,
 	): any => {
-		if (TypeGuard.IsObject(schema) && typeof value === "object") {
+		if (t.schema.isObject(schema) && typeof value === "object") {
 			for (const key in schema.properties) {
 				if (
-					TypeGuard.IsObject(schema.properties[key]) &&
+					t.schema.isObject(schema.properties[key]) &&
 					typeof value[key] === "string"
 				) {
 					try {

package/src/providers/ReactServerProvider.ts

@@ -64,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",
@@ -73,7 +74,7 @@ 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);
@@ -150,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;
@@ -231,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,
 			});
 
@@ -245,7 +252,7 @@ export class ReactServerProvider {
 			}
 
 			if (!withIndex && !options.html) {
-				this.alepha.state("react.router.state", state);
+				this.alepha.state.set("react.router.state", state);
 
 				return {
 					state,
@@ -253,11 +260,8 @@ 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) {
 				return { state, html: "", redirect };
@@ -268,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;
 		};
@@ -300,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
@@ -331,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,
 			});
@@ -371,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);
 
@@ -391,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 = "";
@@ -452,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() {