@alepha/react 0.8.0 → 0.9.0

package/src/descriptors/$page.ts

@@ -1,9 +1,9 @@
 import {
-	__descriptor,
 	type Async,
+	createDescriptor,
+	Descriptor,
 	KIND,
 	NotImplementedError,
-	OPTIONS,
 	type Static,
 	type TSchema,
 } from "@alepha/core";
@@ -13,16 +13,23 @@ import type { FC, ReactNode } from "react";
 import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
 import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
 
-const KEY = "PAGE";
-
-export interface PageConfigSchema {
-	query?: TSchema;
-	params?: TSchema;
-}
-
-export type TPropsDefault = any;
+/**
+ * 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> => {
+	return createDescriptor(
+		PageDescriptor<TConfig, TProps, TPropsParent>,
+		options,
+	);
+};
 
-export type TPropsParentDefault = {};
+// ---------------------------------------------------------------------------------------------------------------------
 
 export interface PageDescriptorOptions<
 	TConfig extends PageConfigSchema = PageConfigSchema,
@@ -96,11 +103,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 }>
-		| (() => Array<{ [OPTIONS]: PageDescriptorOptions }>);
+	children?: Array<PageDescriptor> | (() => Array<PageDescriptor>);
 
-	parent?: { [OPTIONS]: PageDescriptorOptions<PageConfigSchema, TPropsParent> };
+	parent?: PageDescriptor<PageConfigSchema, TPropsParent>;
 
 	can?: () => boolean;
 
@@ -128,63 +133,39 @@ export interface PageDescriptorOptions<
 	cache?: ServerRouteCache;
 }
 
-export interface PageDescriptor<
+export class PageDescriptor<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TProps extends object = TPropsDefault,
 	TPropsParent extends object = TPropsParentDefault,
-> {
-	[KIND]: typeof KEY;
-	[OPTIONS]: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
+> extends Descriptor<PageDescriptorOptions<TConfig, TProps, TPropsParent>> {
+	public get name(): string {
+		return this.options.name ?? this.config.propertyKey;
+	}
 
 	/**
 	 * For testing or build purposes, this will render the page (with or without the HTML layout) and return the HTML and context.
 	 * Only valid for server-side rendering, it will throw an error if called on the client-side.
 	 */
-	render: (
+	public async render(
 		options?: PageDescriptorRenderOptions,
-	) => Promise<PageDescriptorRenderResult>;
+	): Promise<PageDescriptorRenderResult> {
+		throw new NotImplementedError("");
+	}
 }
 
-/**
- * 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;
+$page[KIND] = PageDescriptor;
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface PageConfigSchema {
+	query?: TSchema;
+	params?: TSchema;
+}
+
+export type TPropsDefault = any;
+
+export type TPropsParentDefault = {};
+
 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/useInject.ts

@@ -8,5 +8,5 @@ export const useInject = <T extends object>(clazz: Service<T>): T => {
 		throw new Error("useRouter must be used within a <RouterProvider>");
 	}
 
-	return useMemo(() => ctx.alepha.get(clazz), []);
+	return useMemo(() => ctx.alepha.inject(clazz), []);
 };

package/src/hooks/useRouter.ts

@@ -13,17 +13,18 @@ export const useRouter = (): RouterHookApi => {
 	}
 
 	const pages = useMemo(() => {
-		return ctx.alepha.get(PageDescriptorProvider).getPages();
+		return ctx.alepha.inject(PageDescriptorProvider).getPages();
 	}, []);
 
 	return useMemo(
 		() =>
 			new RouterHookApi(
 				pages,
+				ctx.context,
 				ctx.state,
 				layer,
 				ctx.alepha.isBrowser()
-					? ctx.alepha.get(ReactBrowserProvider)
+					? ctx.alepha.inject(ReactBrowserProvider)
 					: undefined,
 			),
 		[layer],

package/src/index.browser.ts

@@ -1,4 +1,4 @@
-import { __bind, type Alepha, type Module } from "@alepha/core";
+import { $module } from "@alepha/core";
 import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
@@ -16,16 +16,21 @@ export * from "./providers/ReactBrowserProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class AlephaReact implements Module {
-	public readonly name = "alepha.react";
-	public readonly $services = (alepha: Alepha) =>
+export const AlephaReact = $module({
+	name: "alepha.react",
+	descriptors: [$page],
+	services: [
+		PageDescriptorProvider,
+		ReactBrowserRenderer,
+		BrowserRouterProvider,
+		ReactBrowserProvider,
+	],
+	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerLinks)
 			.with(PageDescriptorProvider)
 			.with(ReactBrowserProvider)
 			.with(BrowserRouterProvider)
-			.with(ReactBrowserRenderer);
-}
-
-__bind($page, AlephaReact);
+			.with(ReactBrowserRenderer),
+});

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,4 +1,4 @@
-import { __bind, type Alepha, type Module } from "@alepha/core";
+import { $module } from "@alepha/core";
 import { AlephaServer, type ServerRequest } from "@alepha/server";
 import { AlephaServerCache } from "@alepha/server-cache";
 import { AlephaServerLinks } from "@alepha/server-links";
@@ -9,7 +9,10 @@ import {
 	type PageRequest,
 	type RouterState,
 } from "./providers/PageDescriptorProvider.ts";
-import type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
+import {
+	ReactBrowserProvider,
+	type ReactHydrationState,
+} from "./providers/ReactBrowserProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -66,23 +69,24 @@ 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.
  *
  * @see {@link $page}
  * @module alepha.react
  */
-export class AlephaReact implements Module {
-	public readonly name = "alepha.react";
-	public readonly $services = (alepha: Alepha) =>
+export const AlephaReact = $module({
+	name: "alepha.react",
+	descriptors: [$page],
+	services: [ReactServerProvider, PageDescriptorProvider, ReactBrowserProvider],
+	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerCache)
 			.with(AlephaServerLinks)
 			.with(ReactServerProvider)
-			.with(PageDescriptorProvider);
-}
-
-__bind($page, AlephaReact);
+			.with(PageDescriptorProvider),
+});

package/src/providers/PageDescriptorProvider.ts

@@ -1,5 +1,12 @@
-import type { Static } from "@alepha/core";
-import { $hook, $inject, $logger, Alepha, OPTIONS, t } from "@alepha/core";
+import {
+	$env,
+	$hook,
+	$inject,
+	$logger,
+	Alepha,
+	type Static,
+	t,
+} from "@alepha/core";
 import type { ApiLinksResponse } from "@alepha/server";
 import { createElement, type ReactNode, StrictMode } from "react";
 import ClientOnly from "../components/ClientOnly.tsx";
@@ -8,7 +15,11 @@ import NestedView from "../components/NestedView.tsx";
 import NotFoundPage from "../components/NotFound.tsx";
 import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import { $page, type PageDescriptorOptions } from "../descriptors/$page.ts";
+import {
+	$page,
+	type PageDescriptor,
+	type PageDescriptorOptions,
+} from "../descriptors/$page.ts";
 import { RedirectionError } from "../errors/RedirectionError.ts";
 
 const envSchema = t.object({
@@ -21,7 +32,7 @@ declare module "@alepha/core" {
 
 export class PageDescriptorProvider {
 	protected readonly log = $logger();
-	protected readonly env = $inject(envSchema);
+	protected readonly env = $env(envSchema);
 	protected readonly alepha = $inject(Alepha);
 	protected readonly pages: PageRoute[] = [];
 
@@ -109,7 +120,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 +129,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 +140,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 +159,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?.({
@@ -233,7 +246,7 @@ export class PageDescriptorProvider {
 					element: this.renderView(i + 1, path, element, it.route),
 					index: i + 1,
 					path,
-					route,
+					route: it.route,
 				});
 				break;
 			}
@@ -253,7 +266,8 @@ export class PageDescriptorProvider {
 				element: this.renderView(i + 1, path, element, it.route),
 				index: i + 1,
 				path,
-				route,
+				route: it.route,
+				cache: it.cache,
 			});
 		}
 
@@ -353,14 +367,14 @@ export class PageDescriptorProvider {
 		on: "configure",
 		handler: () => {
 			let hasNotFoundHandler = false;
-			const pages = this.alepha.getDescriptorValues($page);
+			const pages = this.alepha.descriptors($page);
 
-			const hasParent = (it: { [OPTIONS]: PageDescriptorOptions }) => {
+			const hasParent = (it: PageDescriptor) => {
 				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()
+					const children = page.options.children
+						? Array.isArray(page.options.children)
+							? page.options.children
+							: page.options.children()
 						: [];
 					if (children.includes(it)) {
 						return true;
@@ -368,21 +382,17 @@ export class PageDescriptorProvider {
 				}
 			};
 
-			for (const { value, key } of pages) {
-				value[OPTIONS].name ??= key;
-			}
+			for (const page of pages) {
+				if (page.options.path === "/*") {
+					hasNotFoundHandler = true;
+				}
 
-			for (const { value } of pages) {
 				// skip children, we only want root pages
-				if (hasParent(value)) {
+				if (hasParent(page)) {
 					continue;
 				}
 
-				if (value[OPTIONS].path === "/*") {
-					hasNotFoundHandler = true;
-				}
-
-				this.add(this.map(pages, value));
+				this.add(this.map(pages, page));
 			}
 
 			if (!hasNotFoundHandler && pages.length > 0) {
@@ -401,17 +411,18 @@ export class PageDescriptorProvider {
 	});
 
 	protected map(
-		pages: Array<{ value: { [OPTIONS]: PageDescriptorOptions } }>,
-		target: { [OPTIONS]: PageDescriptorOptions },
+		pages: Array<PageDescriptor>,
+		target: PageDescriptor,
 	): PageRouteEntry {
-		const children = target[OPTIONS].children
-			? Array.isArray(target[OPTIONS].children)
-				? target[OPTIONS].children
-				: target[OPTIONS].children()
+		const children = target.options.children
+			? Array.isArray(target.options.children)
+				? target.options.children
+				: target.options.children()
 			: [];
 
 		return {
-			...target[OPTIONS],
+			...target.options,
+			name: target.name,
 			parent: undefined,
 			children: children.map((it) => this.map(pages, it)),
 		} as PageRoute;
@@ -499,6 +510,7 @@ export interface Layer {
 	index: number;
 	path: string;
 	route?: PageRoute;
+	cache?: boolean;
 }
 
 export type PreviousLayerData = Omit<Layer, "element" | "index" | "path">;
@@ -525,6 +537,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(
@@ -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

@@ -1,4 +1,4 @@
-import { $hook, $inject, $logger, type Static, t } from "@alepha/core";
+import { $env, $hook, $inject, $logger, type Static, t } from "@alepha/core";
 import type { ApiLinksResponse } from "@alepha/server";
 import type { Root } from "react-dom/client";
 import { createRoot, hydrateRoot } from "react-dom/client";
@@ -17,15 +17,23 @@ 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);
 	protected readonly browserRouterProvider = $inject(BrowserRouterProvider);
-	protected readonly env = $inject(envSchema);
+	protected readonly env = $env(envSchema);
 	protected readonly log = $logger();
 
 	protected root!: Root;
 
+	public options: ReactBrowserRendererOptions = {
+		scrollRestoration: "top",
+	};
+
 	protected getRootElement() {
 		const root = this.browserProvider.document.getElementById(
 			this.env.REACT_ROOT_ID,
@@ -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);
+			}
+		},
+	});
 }
 
 // ---------------------------------------------------------------------------------------------------------------------