@alepha/react 0.8.0 → 0.9.0

package/README.md

@@ -1 +1,32 @@
-# alepha/react
+# Alepha React
+
+Build server-side rendered (SSR) or single-page React applications.
+
+## Installation
+
+This package is part of the Alepha framework and can be installed via the all-in-one package:
+
+```bash
+npm install alepha
+```
+
+Alternatively, you can install it individually:
+
+```bash
+npm install @alepha/core @alepha/react
+```
+## Module
+
+Provides full-stack React development with declarative routing, server-side rendering, and client-side hydration.
+
+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.
+
+## API Reference
+
+### Descriptors
+
+#### $page()
+
+Main descriptor for defining a React route in the application.

package/dist/index.browser.js

@@ -1,4 +1,4 @@
-import { $hook, $inject, $logger, Alepha, KIND, NotImplementedError, OPTIONS, __bind, __descriptor, t } from "@alepha/core";
+import { $env, $hook, $inject, $logger, $module, Alepha, Descriptor, KIND, NotImplementedError, createDescriptor, t } from "@alepha/core";
 import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks, LinkProvider } from "@alepha/server-links";
 import { RouterProvider } from "@alepha/router";
@@ -7,21 +7,25 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { createRoot, hydrateRoot } from "react-dom/client";
 
 //#region src/descriptors/$page.ts
-const KEY = "PAGE";
 /**
 * Main descriptor for defining a React route in the application.
 */
 const $page = (options) => {
-	__descriptor(KEY);
-	return {
-		[KIND]: KEY,
-		[OPTIONS]: options,
-		render: () => {
-			throw new NotImplementedError(KEY);
-		}
-	};
+	return createDescriptor(PageDescriptor, options);
+};
+var PageDescriptor = class extends Descriptor {
+	get name() {
+		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.
+	*/
+	async render(options) {
+		throw new NotImplementedError("");
+	}
 };
-$page[KIND] = KEY;
+$page[KIND] = PageDescriptor;
 
 //#endregion
 //#region src/components/NotFound.tsx
@@ -311,7 +315,7 @@ const NestedView = (props) => {
 	const index = layer?.index ?? 0;
 	const [view, setView] = useState(app?.state.layers[index]?.element);
 	useRouterEvents({ onEnd: ({ state }) => {
-		setView(state.layers[index]?.element);
+		if (!state.layers[index]?.cache) setView(state.layers[index]?.element);
 	} }, [app]);
 	if (!app) throw new Error("NestedView must be used within a RouterContext.");
 	const element = view ?? props.children ?? null;
@@ -337,7 +341,7 @@ var RedirectionError = class extends Error {
 const envSchema$1 = t.object({ REACT_STRICT_MODE: t.boolean({ default: true }) });
 var PageDescriptorProvider = class {
 	log = $logger();
-	env = $inject(envSchema$1);
+	env = $env(envSchema$1);
 	alepha = $inject(Alepha);
 	pages = [];
 	getPages() {
@@ -385,19 +389,18 @@ var PageDescriptorProvider = class {
 			const route$1 = it.route;
 			const config = {};
 			try {
-				config.query = route$1.schema?.query ? this.alepha.parse(route$1.schema.query, request.query) : request.query;
+				config.query = route$1.schema?.query ? this.alepha.parse(route$1.schema.query, request.query) : {};
 			} catch (e) {
 				it.error = e;
 				break;
 			}
 			try {
-				config.params = route$1.schema?.params ? this.alepha.parse(route$1.schema.params, request.params) : request.params;
+				config.params = route$1.schema?.params ? this.alepha.parse(route$1.schema.params, request.params) : {};
 			} catch (e) {
 				it.error = e;
 				break;
 			}
 			it.config = { ...config };
-			if (!route$1.resolve) continue;
 			const previous = request.previous;
 			if (previous?.[i] && !forceRefresh && previous[i].name === route$1.name) {
 				const url = (str) => str ? str.replace(/\/\/+/g, "/") : "/";
@@ -412,6 +415,7 @@ var PageDescriptorProvider = class {
 				if (prev === curr) {
 					it.props = previous[i].props;
 					it.error = previous[i].error;
+					it.cache = true;
 					context = {
 						...context,
 						...it.props
@@ -420,6 +424,7 @@ var PageDescriptorProvider = class {
 				}
 				forceRefresh = true;
 			}
+			if (!route$1.resolve) continue;
 			try {
 				const props = await route$1.resolve?.({
 					...request,
@@ -466,7 +471,7 @@ var PageDescriptorProvider = class {
 					element: this.renderView(i + 1, path, element$1, it.route),
 					index: i + 1,
 					path,
-					route
+					route: it.route
 				});
 				break;
 			}
@@ -482,7 +487,8 @@ var PageDescriptorProvider = class {
 				element: this.renderView(i + 1, path, element, it.route),
 				index: i + 1,
 				path,
-				route
+				route: it.route,
+				cache: it.cache
 			});
 		}
 		return {
@@ -541,18 +547,17 @@ var PageDescriptorProvider = class {
 		on: "configure",
 		handler: () => {
 			let hasNotFoundHandler = false;
-			const pages = this.alepha.getDescriptorValues($page);
+			const pages = this.alepha.descriptors($page);
 			const hasParent = (it) => {
 				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;
 				}
 			};
-			for (const { value, key } of pages) value[OPTIONS].name ??= key;
-			for (const { value } of pages) {
-				if (hasParent(value)) continue;
-				if (value[OPTIONS].path === "/*") hasNotFoundHandler = true;
-				this.add(this.map(pages, value));
+			for (const page of pages) {
+				if (page.options.path === "/*") hasNotFoundHandler = true;
+				if (hasParent(page)) continue;
+				this.add(this.map(pages, page));
 			}
 			if (!hasNotFoundHandler && pages.length > 0) this.add({
 				path: "/*",
@@ -566,9 +571,10 @@ var PageDescriptorProvider = class {
 		}
 	});
 	map(pages, target) {
-		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: void 0,
 			children: children.map((it) => this.map(pages, it))
 		};
@@ -721,8 +727,22 @@ var ReactBrowserProvider = class {
 	get history() {
 		return window.history;
 	}
+	get location() {
+		return window.location;
+	}
 	get url() {
-		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;
+	}
+	pushState(url, replace) {
+		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);
 	}
 	async invalidate(props) {
 		const previous = [];
@@ -748,14 +768,14 @@ var ReactBrowserProvider = class {
 	async go(url, options = {}) {
 		const result = await this.render({ url });
 		if (result.context.url.pathname !== url) {
-			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);
 	}
 	async render(options = {}) {
 		const previous = options.previous ?? this.state.layers;
@@ -792,6 +812,7 @@ var ReactBrowserProvider = class {
 				hydration
 			});
 			window.addEventListener("popstate", () => {
+				if (this.state.pathname === location.pathname) return;
 				this.render();
 			});
 		}
@@ -804,9 +825,10 @@ const envSchema = t.object({ REACT_ROOT_ID: t.string({ default: "root" }) });
 var ReactBrowserRenderer = class {
 	browserProvider = $inject(ReactBrowserProvider);
 	browserRouterProvider = $inject(BrowserRouterProvider);
-	env = $inject(envSchema);
+	env = $env(envSchema);
 	log = $logger();
 	root;
+	options = { scrollRestoration: "top" };
 	getRootElement() {
 		const root = this.browserProvider.document.getElementById(this.env.REACT_ROOT_ID);
 		if (root) return root;
@@ -829,17 +851,32 @@ var ReactBrowserRenderer = class {
 			}
 		}
 	});
+	onTransitionEnd = $hook({
+		on: "react:transition:end",
+		handler: () => {
+			if (this.options.scrollRestoration === "top" && typeof window !== "undefined") window.scrollTo(0, 0);
+		}
+	});
 };
 
 //#endregion
 //#region src/hooks/RouterHookApi.ts
 var RouterHookApi = class {
-	constructor(pages, state, layer, browser) {
+	constructor(pages, context, state, layer, browser) {
 		this.pages = pages;
+		this.context = context;
 		this.state = state;
 		this.layer = layer;
 		this.browser = browser;
 	}
+	getURL() {
+		if (!this.browser) return this.context.url;
+		return new URL(this.location.href);
+	}
+	get location() {
+		if (!this.browser) throw new Error("Browser is required");
+		return this.browser.location;
+	}
 	get current() {
 		return this.state;
 	}
@@ -915,9 +952,9 @@ const useRouter = () => {
 	const layer = useContext(RouterLayerContext);
 	if (!ctx || !layer) throw new Error("useRouter must be used within a RouterProvider");
 	const pages = useMemo(() => {
-		return ctx.alepha.get(PageDescriptorProvider).getPages();
+		return ctx.alepha.inject(PageDescriptorProvider).getPages();
 	}, []);
-	return useMemo(() => new RouterHookApi(pages, ctx.state, layer, ctx.alepha.isBrowser() ? ctx.alepha.get(ReactBrowserProvider) : void 0), [layer]);
+	return useMemo(() => new RouterHookApi(pages, ctx.context, ctx.state, layer, ctx.alepha.isBrowser() ? ctx.alepha.inject(ReactBrowserProvider) : void 0), [layer]);
 };
 
 //#endregion
@@ -925,11 +962,11 @@ const useRouter = () => {
 const Link = (props) => {
 	React.useContext(RouterContext);
 	const router = useRouter();
-	const to = typeof props.to === "string" ? props.to : props.to[OPTIONS].path;
+	const to = typeof props.to === "string" ? props.to : props.to.options.path;
 	if (!to) return null;
-	const can = typeof props.to === "string" ? void 0 : props.to[OPTIONS].can;
+	const can = typeof props.to === "string" ? void 0 : props.to.options.can;
 	if (can && !can()) return null;
-	const name = typeof props.to === "string" ? void 0 : props.to[OPTIONS].name;
+	const name = typeof props.to === "string" ? void 0 : props.to.options.name;
 	const anchorProps = {
 		...props,
 		to: void 0
@@ -981,7 +1018,7 @@ const useActive = (path) => {
 const useInject = (clazz) => {
 	const ctx = useContext(RouterContext);
 	if (!ctx) throw new Error("useRouter must be used within a <RouterProvider>");
-	return useMemo(() => ctx.alepha.get(clazz), []);
+	return useMemo(() => ctx.alepha.inject(clazz), []);
 };
 
 //#endregion
@@ -1036,12 +1073,18 @@ const useRouterState = () => {
 
 //#endregion
 //#region src/index.browser.ts
-var AlephaReact = class {
-	name = "alepha.react";
-	$services = (alepha) => alepha.with(AlephaServer).with(AlephaServerLinks).with(PageDescriptorProvider).with(ReactBrowserProvider).with(BrowserRouterProvider).with(ReactBrowserRenderer);
-};
-__bind($page, AlephaReact);
+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)
+});
 
 //#endregion
-export { $page, AlephaReact, BrowserRouterProvider, ClientOnly_default as ClientOnly, ErrorBoundary_default as ErrorBoundary, Link_default as Link, NestedView_default as NestedView, PageDescriptorProvider, ReactBrowserProvider, RedirectionError, RouterContext, RouterHookApi, RouterLayerContext, isPageRoute, useActive, useAlepha, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };
+export { $page, AlephaReact, BrowserRouterProvider, ClientOnly_default as ClientOnly, ErrorBoundary_default as ErrorBoundary, Link_default as Link, NestedView_default as NestedView, NotFoundPage as NotFound, PageDescriptor, PageDescriptorProvider, ReactBrowserProvider, RedirectionError, RouterContext, RouterHookApi, RouterLayerContext, isPageRoute, useActive, useAlepha, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };
 //# sourceMappingURL=index.browser.js.map