@alepha/react 0.7.7 → 0.8.1

package/README.md

@@ -1 +1,153 @@
-# 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.
+
+**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>
+    ),
+  });
+}
+```
+
+## API Reference
+
+### Descriptors
+
+#### $page()
+
+Main descriptor for defining a React route in the application.

package/dist/index.browser.js

@@ -1,8 +1,9 @@
 import { $hook, $inject, $logger, Alepha, KIND, NotImplementedError, OPTIONS, __bind, __descriptor, t } from "@alepha/core";
+import { AlephaServer } from "@alepha/server";
+import { AlephaServerLinks, LinkProvider } from "@alepha/server-links";
 import { RouterProvider } from "@alepha/router";
 import React, { StrictMode, createContext, createElement, useContext, useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { LinkProvider } from "@alepha/server-links";
 import { createRoot, hydrateRoot } from "react-dom/client";
 
 //#region src/descriptors/$page.ts
@@ -12,11 +13,6 @@ const KEY = "PAGE";
 */
 const $page = (options) => {
 	__descriptor(KEY);
-	if (options.children) for (const child of options.children) child[OPTIONS].parent = { [OPTIONS]: options };
-	if (options.parent) {
-		options.parent[OPTIONS].children ??= [];
-		options.parent[OPTIONS].children.push({ [OPTIONS]: options });
-	}
 	return {
 		[KIND]: KEY,
 		[OPTIONS]: options,
@@ -315,7 +311,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;
@@ -389,19 +385,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, "/") : "/";
@@ -416,6 +411,7 @@ var PageDescriptorProvider = class {
 				if (prev === curr) {
 					it.props = previous[i].props;
 					it.error = previous[i].error;
+					it.cache = true;
 					context = {
 						...context,
 						...it.props
@@ -424,6 +420,7 @@ var PageDescriptorProvider = class {
 				}
 				forceRefresh = true;
 			}
+			if (!route$1.resolve) continue;
 			try {
 				const props = await route$1.resolve?.({
 					...request,
@@ -470,7 +467,7 @@ var PageDescriptorProvider = class {
 					element: this.renderView(i + 1, path, element$1, it.route),
 					index: i + 1,
 					path,
-					route
+					route: it.route
 				});
 				break;
 			}
@@ -486,7 +483,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 {
@@ -542,14 +540,20 @@ var PageDescriptorProvider = class {
 		} }, element);
 	}
 	configure = $hook({
-		name: "configure",
+		on: "configure",
 		handler: () => {
 			let hasNotFoundHandler = false;
 			const pages = this.alepha.getDescriptorValues($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() : [];
+					if (children.includes(it)) return true;
+				}
+			};
 			for (const { value, key } of pages) value[OPTIONS].name ??= key;
 			for (const { value } of pages) {
-				if (value[OPTIONS].parent) continue;
 				if (value[OPTIONS].path === "/*") hasNotFoundHandler = true;
+				if (hasParent(value)) continue;
 				this.add(this.map(pages, value));
 			}
 			if (!hasNotFoundHandler && pages.length > 0) this.add({
@@ -564,7 +568,7 @@ var PageDescriptorProvider = class {
 		}
 	});
 	map(pages, target) {
-		const children = target[OPTIONS].children ?? [];
+		const children = target[OPTIONS].children ? Array.isArray(target[OPTIONS].children) ? target[OPTIONS].children : target[OPTIONS].children() : [];
 		return {
 			...target[OPTIONS],
 			parent: void 0,
@@ -613,7 +617,7 @@ var BrowserRouterProvider = class extends RouterProvider {
 		this.pageDescriptorProvider.add(entry);
 	}
 	configure = $hook({
-		name: "configure",
+		on: "configure",
 		handler: async () => {
 			for (const page of this.pageDescriptorProvider.getPages()) if (page.component || page.lazy) this.push({
 				path: page.match,
@@ -719,8 +723,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 = [];
@@ -746,14 +764,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;
@@ -778,7 +796,7 @@ var ReactBrowserProvider = class {
 		}
 	}
 	ready = $hook({
-		name: "ready",
+		on: "ready",
 		handler: async () => {
 			const hydration = this.getHydrationState();
 			const previous = hydration?.layers ?? [];
@@ -790,6 +808,7 @@ var ReactBrowserProvider = class {
 				hydration
 			});
 			window.addEventListener("popstate", () => {
+				if (this.state.pathname === location.pathname) return;
 				this.render();
 			});
 		}
@@ -805,6 +824,7 @@ var ReactBrowserRenderer = class {
 	env = $inject(envSchema);
 	log = $logger();
 	root;
+	options = { scrollRestoration: "top" };
 	getRootElement() {
 		const root = this.browserProvider.document.getElementById(this.env.REACT_ROOT_ID);
 		if (root) return root;
@@ -814,7 +834,7 @@ var ReactBrowserRenderer = class {
 		return div;
 	}
 	ready = $hook({
-		name: "react:browser:render",
+		on: "react:browser:render",
 		handler: async ({ state, context, hydration }) => {
 			const element = this.browserRouterProvider.root(state, context);
 			if (hydration?.layers) {
@@ -827,17 +847,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,7 +950,7 @@ const useRouter = () => {
 	const pages = useMemo(() => {
 		return ctx.alepha.get(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.get(ReactBrowserProvider) : void 0), [layer]);
 };
 
 //#endregion
@@ -1036,10 +1071,10 @@ const useRouterState = () => {
 //#region src/index.browser.ts
 var AlephaReact = class {
 	name = "alepha.react";
-	$services = (alepha) => alepha.with(PageDescriptorProvider).with(ReactBrowserProvider).with(BrowserRouterProvider).with(ReactBrowserRenderer);
+	$services = (alepha) => alepha.with(AlephaServer).with(AlephaServerLinks).with(PageDescriptorProvider).with(ReactBrowserProvider).with(BrowserRouterProvider).with(ReactBrowserRenderer);
 };
 __bind($page, AlephaReact);
 
 //#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, PageDescriptorProvider, ReactBrowserProvider, RedirectionError, RouterContext, RouterHookApi, RouterLayerContext, isPageRoute, useActive, useAlepha, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState };
 //# sourceMappingURL=index.browser.js.map