@alepha/react 0.7.7 → 0.8.1

package/src/descriptors/$page.ts

@@ -15,6 +15,46 @@ import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
 const KEY = "PAGE";
 
+/**
+ * Main descriptor for defining a React route in the application.
+ */
+export const $page = <
+	TConfig extends PageConfigSchema = PageConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+>(
+	options: PageDescriptorOptions<TConfig, TProps, TPropsParent>,
+): PageDescriptor<TConfig, TProps, TPropsParent> => {
+	__descriptor(KEY);
+
+	// if (options.children) {
+	// 	for (const child of options.children) {
+	// 		child[OPTIONS].parent = {
+	// 			[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
+	// 		};
+	// 	}
+	// }
+
+	// if (options.parent) {
+	// 	options.parent[OPTIONS].children ??= [];
+	// 	options.parent[OPTIONS].children.push({
+	// 		[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
+	// 	});
+	// }
+
+	return {
+		[KIND]: KEY,
+		[OPTIONS]: options,
+		render: () => {
+			throw new NotImplementedError(KEY);
+		},
+	};
+};
+
+$page[KIND] = KEY;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 export interface PageConfigSchema {
 	query?: TSchema;
 	params?: TSchema;
@@ -96,7 +136,9 @@ export interface PageDescriptorOptions<
 	 *
 	 * If you still want to render at this pathname, add a child page with an empty path.
 	 */
-	children?: Array<{ [OPTIONS]: PageDescriptorOptions }>;
+	children?:
+		| Array<{ [OPTIONS]: PageDescriptorOptions }>
+		| (() => Array<{ [OPTIONS]: PageDescriptorOptions }>);
 
 	parent?: { [OPTIONS]: PageDescriptorOptions<PageConfigSchema, TPropsParent> };
 
@@ -104,7 +146,13 @@ export interface PageDescriptorOptions<
 
 	errorHandler?: (error: Error) => ReactNode;
 
-	prerender?:
+	/**
+	 * If true, the page will be rendered on the build time.
+	 * Works only with viteAlepha plugin.
+	 *
+	 * Replace boolean by an object to define static entries. (e.g. list of params/query)
+	 */
+	static?:
 		| boolean
 		| {
 				entries?: Array<Partial<PageRequestConfig<TConfig>>>;
@@ -137,46 +185,6 @@ export interface PageDescriptor<
 	) => Promise<PageDescriptorRenderResult>;
 }
 
-/**
- * Main descriptor for defining a React route in the application.
- */
-export const $page = <
-	TConfig extends PageConfigSchema = PageConfigSchema,
-	TProps extends object = TPropsDefault,
-	TPropsParent extends object = TPropsParentDefault,
->(
-	options: PageDescriptorOptions<TConfig, TProps, TPropsParent>,
-): PageDescriptor<TConfig, TProps, TPropsParent> => {
-	__descriptor(KEY);
-
-	if (options.children) {
-		for (const child of options.children) {
-			child[OPTIONS].parent = {
-				[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
-			};
-		}
-	}
-
-	if (options.parent) {
-		options.parent[OPTIONS].children ??= [];
-		options.parent[OPTIONS].children.push({
-			[OPTIONS]: options as PageDescriptorOptions<any, any, any>,
-		});
-	}
-
-	return {
-		[KIND]: KEY,
-		[OPTIONS]: options,
-		render: () => {
-			throw new NotImplementedError(KEY);
-		},
-	};
-};
-
-$page[KIND] = KEY;
-
-// ---------------------------------------------------------------------------------------------------------------------
-
 export interface PageDescriptorRenderOptions {
 	params?: Record<string, string>;
 	query?: Record<string, string>;

package/src/hooks/RouterHookApi.ts

@@ -1,6 +1,7 @@
 import type { PageDescriptor } from "../descriptors/$page.ts";
 import type {
 	AnchorProps,
+	PageReactContext,
 	PageRoute,
 	RouterState,
 } from "../providers/PageDescriptorProvider.ts";
@@ -12,6 +13,7 @@ import type {
 export class RouterHookApi {
 	constructor(
 		private readonly pages: PageRoute[],
+		private readonly context: PageReactContext,
 		private readonly state: RouterState,
 		private readonly layer: {
 			path: string;
@@ -19,6 +21,21 @@ export class RouterHookApi {
 		private readonly browser?: ReactBrowserProvider,
 	) {}
 
+	public getURL(): URL {
+		if (!this.browser) {
+			return this.context.url;
+		}
+		return new URL(this.location.href);
+	}
+
+	public get location(): Location {
+		if (!this.browser) {
+			throw new Error("Browser is required");
+		}
+
+		return this.browser.location;
+	}
+
 	public get current(): RouterState {
 		return this.state;
 	}

package/src/hooks/useRouter.ts

@@ -20,6 +20,7 @@ export const useRouter = (): RouterHookApi => {
 		() =>
 			new RouterHookApi(
 				pages,
+				ctx.context,
 				ctx.state,
 				layer,
 				ctx.alepha.isBrowser()

package/src/index.browser.ts

@@ -1,4 +1,6 @@
 import { __bind, type Alepha, type Module } from "@alepha/core";
+import { AlephaServer } from "@alepha/server";
+import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
 import { BrowserRouterProvider } from "./providers/BrowserRouterProvider.ts";
 import { PageDescriptorProvider } from "./providers/PageDescriptorProvider.ts";
@@ -18,6 +20,8 @@ export class AlephaReact implements Module {
 	public readonly name = "alepha.react";
 	public readonly $services = (alepha: Alepha) =>
 		alepha
+			.with(AlephaServer)
+			.with(AlephaServerLinks)
 			.with(PageDescriptorProvider)
 			.with(ReactBrowserProvider)
 			.with(BrowserRouterProvider)

package/src/index.shared.ts

@@ -3,6 +3,7 @@ export { default as ErrorBoundary } from "./components/ErrorBoundary.tsx";
 export * from "./components/ErrorViewer.tsx";
 export { default as Link } from "./components/Link.tsx";
 export { default as NestedView } from "./components/NestedView.tsx";
+export { default as NotFound } from "./components/NotFound.tsx";
 export * from "./contexts/RouterContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./descriptors/$page.ts";

package/src/index.ts

@@ -1,6 +1,7 @@
 import { __bind, type Alepha, type 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 {
 	PageDescriptorProvider,
@@ -65,10 +66,132 @@ declare module "@alepha/core" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Alepha React Module
+ * Provides full-stack React development with declarative routing, server-side rendering, and client-side hydration.
  *
- * Alepha React Module contains a router for client-side navigation and server-side rendering.
- * Routes can be defined using the `$page` descriptor.
+ * The React module enables building modern React applications using the `$page` descriptor on class properties.
+ * It delivers seamless server-side rendering, automatic code splitting, and client-side navigation with full
+ * type safety and schema validation for route parameters and data.
+ *
+ * **Key Features:**
+ * - Declarative page definition with `$page` descriptor
+ * - Server-side rendering (SSR) with automatic hydration
+ * - Type-safe routing with parameter validation
+ * - Schema-based data resolution and validation
+ * - SEO-friendly meta tag management
+ * - Automatic code splitting and lazy loading
+ * - Client-side navigation with browser history
+ *
+ * **Basic Usage:**
+ * ```ts
+ * import { Alepha, run, t } from "alepha";
+ * import { AlephaReact, $page } from "alepha/react";
+ *
+ * class AppRoutes {
+ *   // Home page
+ *   home = $page({
+ *     path: "/",
+ *     component: () => (
+ *       <div>
+ *         <h1>Welcome to Alepha</h1>
+ *         <p>Build amazing React applications!</p>
+ *       </div>
+ *     ),
+ *   });
+ *
+ *   // About page with meta tags
+ *   about = $page({
+ *     path: "/about",
+ *     head: {
+ *       title: "About Us",
+ *       description: "Learn more about our mission",
+ *     },
+ *     component: () => (
+ *       <div>
+ *         <h1>About Us</h1>
+ *         <p>Learn more about our mission.</p>
+ *       </div>
+ *     ),
+ *   });
+ * }
+ *
+ * const alepha = Alepha.create()
+ *   .with(AlephaReact)
+ *   .with(AppRoutes);
+ *
+ * run(alepha);
+ * ```
+ *
+ * **Dynamic Routes with Parameters:**
+ * ```tsx
+ * class UserRoutes {
+ *   userProfile = $page({
+ *     path: "/users/:id",
+ *     schema: {
+ *       params: t.object({
+ *         id: t.string(),
+ *       }),
+ *     },
+ *     resolve: async ({ params }) => {
+ *       // Fetch user data server-side
+ *       const user = await getUserById(params.id);
+ *       return { user };
+ *     },
+ *     head: ({ user }) => ({
+ *       title: `${user.name} - Profile`,
+ *       description: `View ${user.name}'s profile`,
+ *     }),
+ *     component: ({ user }) => (
+ *       <div>
+ *         <h1>{user.name}</h1>
+ *         <p>Email: {user.email}</p>
+ *       </div>
+ *     ),
+ *   });
+ *
+ *   userSettings = $page({
+ *     path: "/users/:id/settings",
+ *     schema: {
+ *       params: t.object({
+ *         id: t.string(),
+ *       }),
+ *     },
+ *     component: ({ params }) => (
+ *       <UserSettings userId={params.id} />
+ *     ),
+ *   });
+ * }
+ * ```
+ *
+ * **Static Generation:**
+ * ```tsx
+ * class BlogRoutes {
+ *   blogPost = $page({
+ *     path: "/blog/:slug",
+ *     schema: {
+ *       params: t.object({
+ *         slug: t.string(),
+ *       }),
+ *     },
+ *     static: {
+ *       entries: [
+ *         { params: { slug: "getting-started" } },
+ *         { params: { slug: "advanced-features" } },
+ *         { params: { slug: "deployment" } },
+ *       ],
+ *     },
+ *     resolve: ({ params }) => {
+ *       const post = getBlogPost(params.slug);
+ *       return { post };
+ *     },
+ *     component: ({ post }) => (
+ *       <article>
+ *         <h1>{post.title}</h1>
+ *         <div>{post.content}</div>
+ *       </article>
+ *     ),
+ *   });
+ * }
+ * ```
  *
  * @see {@link $page}
  * @module alepha.react
@@ -79,6 +202,7 @@ export class AlephaReact implements Module {
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerCache)
+			.with(AlephaServerLinks)
 			.with(ReactServerProvider)
 			.with(PageDescriptorProvider);
 }

package/src/providers/BrowserRouterProvider.ts

@@ -28,7 +28,7 @@ export class BrowserRouterProvider extends RouterProvider<BrowserRoute> {
 	}
 
 	protected readonly configure = $hook({
-		name: "configure",
+		on: "configure",
 		handler: async () => {
 			for (const page of this.pageDescriptorProvider.getPages()) {
 				// mount only if a view is provided

package/src/providers/PageDescriptorProvider.ts

@@ -109,7 +109,7 @@ export class PageDescriptorProvider {
 			try {
 				config.query = route.schema?.query
 					? this.alepha.parse(route.schema.query, request.query)
-					: request.query;
+					: {};
 			} catch (e) {
 				it.error = e as Error;
 				break;
@@ -118,7 +118,7 @@ export class PageDescriptorProvider {
 			try {
 				config.params = route.schema?.params
 					? this.alepha.parse(route.schema.params, request.params)
-					: request.params;
+					: {};
 			} catch (e) {
 				it.error = e as Error;
 				break;
@@ -129,11 +129,6 @@ export class PageDescriptorProvider {
 				...config,
 			};
 
-			// no resolve, render a basic view by default
-			if (!route.resolve) {
-				continue;
-			}
-
 			// check if previous layer is the same, reuse if possible
 			const previous = request.previous;
 			if (previous?.[i] && !forceRefresh && previous[i].name === route.name) {
@@ -153,16 +148,23 @@ export class PageDescriptorProvider {
 					// part is the same, reuse previous layer
 					it.props = previous[i].props;
 					it.error = previous[i].error;
+					it.cache = true;
 					context = {
 						...context,
 						...it.props,
 					};
 					continue;
 				}
+
 				// part is different, force refresh of next layers
 				forceRefresh = true;
 			}
 
+			// no resolve, render a basic view by default
+			if (!route.resolve) {
+				continue;
+			}
+
 			try {
 				const props =
 					(await route.resolve?.({
@@ -209,13 +211,6 @@ export class PageDescriptorProvider {
 				params[key] = String(params[key]);
 			}
 
-			// if (it.route.head && !it.error) {
-			// 	this.fillHead(it.route, request, {
-			// 		...props,
-			// 		...context,
-			// 	});
-			// }
-
 			acc += "/";
 			acc += it.route.path ? this.compile(it.route.path, params) : "";
 			const path = acc.replace(/\/+/, "/");
@@ -240,7 +235,7 @@ export class PageDescriptorProvider {
 					element: this.renderView(i + 1, path, element, it.route),
 					index: i + 1,
 					path,
-					route,
+					route: it.route,
 				});
 				break;
 			}
@@ -260,7 +255,8 @@ export class PageDescriptorProvider {
 				element: this.renderView(i + 1, path, element, it.route),
 				index: i + 1,
 				path,
-				route,
+				route: it.route,
+				cache: it.cache,
 			});
 		}
 
@@ -357,24 +353,38 @@ export class PageDescriptorProvider {
 	}
 
 	protected readonly configure = $hook({
-		name: "configure",
+		on: "configure",
 		handler: () => {
 			let hasNotFoundHandler = false;
 			const pages = this.alepha.getDescriptorValues($page);
+
+			const hasParent = (it: { [OPTIONS]: PageDescriptorOptions }) => {
+				for (const page of pages) {
+					const children = page.value[OPTIONS].children
+						? Array.isArray(page.value[OPTIONS].children)
+							? page.value[OPTIONS].children
+							: page.value[OPTIONS].children()
+						: [];
+					if (children.includes(it)) {
+						return true;
+					}
+				}
+			};
+
 			for (const { value, key } of pages) {
 				value[OPTIONS].name ??= key;
 			}
 
 			for (const { value } of pages) {
-				// skip children, we only want root pages
-				if (value[OPTIONS].parent) {
-					continue;
-				}
-
 				if (value[OPTIONS].path === "/*") {
 					hasNotFoundHandler = true;
 				}
 
+				// skip children, we only want root pages
+				if (hasParent(value)) {
+					continue;
+				}
+
 				this.add(this.map(pages, value));
 			}
 
@@ -397,7 +407,11 @@ export class PageDescriptorProvider {
 		pages: Array<{ value: { [OPTIONS]: PageDescriptorOptions } }>,
 		target: { [OPTIONS]: PageDescriptorOptions },
 	): PageRouteEntry {
-		const children = target[OPTIONS].children ?? [];
+		const children = target[OPTIONS].children
+			? Array.isArray(target[OPTIONS].children)
+				? target[OPTIONS].children
+				: target[OPTIONS].children()
+			: [];
 
 		return {
 			...target[OPTIONS],
@@ -488,6 +502,7 @@ export interface Layer {
 	index: number;
 	path: string;
 	route?: PageRoute;
+	cache?: boolean;
 }
 
 export type PreviousLayerData = Omit<Layer, "element" | "index" | "path">;
@@ -514,6 +529,7 @@ export interface RouterStackItem {
 	config?: Record<string, any>;
 	props?: Record<string, any>;
 	error?: Error;
+	cache?: boolean;
 }
 
 export interface RouterRenderResult {

package/src/providers/ReactBrowserProvider.ts

@@ -35,8 +35,35 @@ export class ReactBrowserProvider {
 		return window.history;
 	}
 
+	public get location() {
+		return window.location;
+	}
+
 	public get url(): string {
-		return window.location.pathname + window.location.search;
+		let url = this.location.pathname + this.location.search;
+
+		if (import.meta?.env?.BASE_URL) {
+			url = url.replace(import.meta.env?.BASE_URL, "");
+			if (!url.startsWith("/")) {
+				url = `/${url}`;
+			}
+		}
+
+		return url;
+	}
+
+	public pushState(url: string, replace?: boolean) {
+		let path = url;
+
+		if (import.meta?.env?.BASE_URL) {
+			path = (import.meta.env?.BASE_URL + path).replaceAll("//", "/");
+		}
+
+		if (replace) {
+			this.history.replaceState({}, "", path);
+		} else {
+			this.history.pushState({}, "", path);
+		}
 	}
 
 	public async invalidate(props?: Record<string, any>) {
@@ -72,16 +99,16 @@ export class ReactBrowserProvider {
 		// when redirecting in browser
 		if (result.context.url.pathname !== url) {
 			// TODO: check if losing search params is acceptable?
-			this.history.replaceState({}, "", result.context.url.pathname);
+			this.pushState(result.context.url.pathname);
 			return;
 		}
 
 		if (options.replace) {
-			this.history.replaceState({}, "", url);
+			this.pushState(url);
 			return;
 		}
 
-		this.history.pushState({}, "", url);
+		this.pushState(url);
 	}
 
 	protected async render(
@@ -125,7 +152,7 @@ export class ReactBrowserProvider {
 	// -------------------------------------------------------------------------------------------------------------------
 
 	public readonly ready = $hook({
-		name: "ready",
+		on: "ready",
 		handler: async () => {
 			const hydration = this.getHydrationState();
 			const previous = hydration?.layers ?? [];
@@ -145,6 +172,12 @@ export class ReactBrowserProvider {
 			});
 
 			window.addEventListener("popstate", () => {
+				// when you update silently queryparams or hash, skip rendering
+				// if you want to force a rendering, use #go()
+				if (this.state.pathname === location.pathname) {
+					return;
+				}
+
 				this.render();
 			});
 		},

package/src/providers/ReactBrowserRenderer.ts

@@ -17,6 +17,10 @@ declare module "@alepha/core" {
 	interface Env extends Partial<Static<typeof envSchema>> {}
 }
 
+export interface ReactBrowserRendererOptions {
+	scrollRestoration?: "top" | "manual";
+}
+
 // TODO: move to ReactBrowserProvider when it will be removed from server-side imports
 export class ReactBrowserRenderer {
 	protected readonly browserProvider = $inject(ReactBrowserProvider);
@@ -26,6 +30,10 @@ export class ReactBrowserRenderer {
 
 	protected root!: Root;
 
+	public options: ReactBrowserRendererOptions = {
+		scrollRestoration: "top",
+	};
+
 	protected getRootElement() {
 		const root = this.browserProvider.document.getElementById(
 			this.env.REACT_ROOT_ID,
@@ -43,7 +51,7 @@ export class ReactBrowserRenderer {
 	}
 
 	public readonly ready = $hook({
-		name: "react:browser:render",
+		on: "react:browser:render",
 		handler: async ({ state, context, hydration }) => {
 			const element = this.browserRouterProvider.root(state, context);
 
@@ -57,6 +65,18 @@ export class ReactBrowserRenderer {
 			}
 		},
 	});
+
+	protected readonly onTransitionEnd = $hook({
+		on: "react:transition:end",
+		handler: () => {
+			if (
+				this.options.scrollRestoration === "top" &&
+				typeof window !== "undefined"
+			) {
+				window.scrollTo(0, 0);
+			}
+		},
+	});
 }
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/providers/ReactServerProvider.ts

@@ -41,8 +41,8 @@ const envSchema = t.object({
 declare module "@alepha/core" {
 	interface Env extends Partial<Static<typeof envSchema>> {}
 	interface State {
-		"ReactServerProvider.template"?: string;
-		"ReactServerProvider.ssr"?: boolean;
+		"react.server.template"?: string;
+		"react.server.ssr"?: boolean;
 	}
 }
 
@@ -60,14 +60,14 @@ export class ReactServerProvider {
 	);
 
 	public readonly onConfigure = $hook({
-		name: "configure",
+		on: "configure",
 		handler: async () => {
 			const pages = this.alepha.getDescriptorValues($page);
 
 			const ssrEnabled =
 				pages.length > 0 && this.env.REACT_SSR_ENABLED !== false;
 
-			this.alepha.state("ReactServerProvider.ssr", ssrEnabled);
+			this.alepha.state("react.server.ssr", ssrEnabled);
 
 			for (const { key, instance, value } of pages) {
 				const name = value[OPTIONS].name ?? key;
@@ -127,7 +127,7 @@ export class ReactServerProvider {
 
 	public get template() {
 		return (
-			this.alepha.state("ReactServerProvider.template") ??
+			this.alepha.state("react.server.template") ??
 			"<!DOCTYPE html><html lang='en'><head></head><body></body></html>"
 		);
 	}