@alepha/react 0.9.2 → 0.9.4

package/src/index.browser.ts

@@ -2,17 +2,17 @@ import { $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";
 import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
-import { ReactBrowserRenderer } from "./providers/ReactBrowserRenderer.ts";
+import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
+import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./index.shared.ts";
-export * from "./providers/BrowserRouterProvider.ts";
-export * from "./providers/PageDescriptorProvider.ts";
 export * from "./providers/ReactBrowserProvider.ts";
+export * from "./providers/ReactBrowserRouterProvider.ts";
+export * from "./providers/ReactPageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -20,17 +20,17 @@ export const AlephaReact = $module({
 	name: "alepha.react",
 	descriptors: [$page],
 	services: [
-		PageDescriptorProvider,
-		ReactBrowserRenderer,
-		BrowserRouterProvider,
+		ReactPageProvider,
+		ReactBrowserRouterProvider,
 		ReactBrowserProvider,
+		ReactRouter,
 	],
 	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerLinks)
-			.with(PageDescriptorProvider)
+			.with(ReactPageProvider)
 			.with(ReactBrowserProvider)
-			.with(BrowserRouterProvider)
-			.with(ReactBrowserRenderer),
+			.with(ReactBrowserRouterProvider)
+			.with(ReactRouter),
 });

package/src/index.shared.ts

@@ -1,15 +1,13 @@
 export { default as ClientOnly } from "./components/ClientOnly.tsx";
 export { default as ErrorBoundary } from "./components/ErrorBoundary.tsx";
-export * from "./components/ErrorViewer.tsx";
-export { default as Link } from "./components/Link.tsx";
+export { default as ErrorViewer } from "./components/ErrorViewer.tsx";
+export { default as Link, type LinkProps } from "./components/Link.tsx";
 export { default as NestedView } from "./components/NestedView.tsx";
 export { default as NotFound } from "./components/NotFound.tsx";
 export * from "./contexts/AlephaContext.ts";
-export * from "./contexts/RouterContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./descriptors/$page.ts";
-export * from "./errors/RedirectionError.ts";
-export * from "./hooks/RouterHookApi.ts";
+export * from "./errors/Redirection.ts";
 export * from "./hooks/useActive.ts";
 export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
@@ -20,3 +18,4 @@ export * from "./hooks/useRouterEvents.ts";
 export * from "./hooks/useRouterState.ts";
 export * from "./hooks/useSchema.ts";
 export * from "./hooks/useStore.ts";
+export * from "./services/ReactRouter.ts";

package/src/index.ts

@@ -3,65 +3,55 @@ 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 type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
 import {
-	PageDescriptorProvider,
-	type PageReactContext,
-	type PageRequest,
-	type RouterState,
-} from "./providers/PageDescriptorProvider.ts";
-import {
-	ReactBrowserProvider,
-	type ReactHydrationState,
-} from "./providers/ReactBrowserProvider.ts";
+	ReactPageProvider,
+	type ReactRouterState,
+} from "./providers/ReactPageProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
+import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./index.shared.ts";
-export * from "./providers/PageDescriptorProvider.ts";
 export * from "./providers/ReactBrowserProvider.ts";
+export * from "./providers/ReactPageProvider.ts";
 export * from "./providers/ReactServerProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 declare module "@alepha/core" {
+	interface State {
+		"react.router.state"?: ReactRouterState;
+	}
+
 	interface Hooks {
-		"react:router:createLayers": {
-			request: ServerRequest;
-			context: PageRequest;
-			layers: PageRequest[];
-		};
 		"react:server:render:begin": {
 			request?: ServerRequest;
-			context: PageRequest;
+			state: ReactRouterState;
 		};
 		"react:server:render:end": {
 			request?: ServerRequest;
-			context: PageRequest;
-			state: RouterState;
+			state: ReactRouterState;
 			html: string;
 		};
+		// -----------------------------------------------------------------------------------------------------------------
 		"react:browser:render": {
-			state: RouterState;
-			context: PageReactContext;
+			state: ReactRouterState;
 			hydration?: ReactHydrationState;
 		};
 		"react:transition:begin": {
-			state: RouterState;
-			context: PageReactContext;
+			state: ReactRouterState;
 		};
 		"react:transition:success": {
-			state: RouterState;
-			context: PageReactContext;
+			state: ReactRouterState;
 		};
 		"react:transition:error": {
+			state: ReactRouterState;
 			error: Error;
-			state: RouterState;
-			context: PageReactContext;
 		};
 		"react:transition:end": {
-			state: RouterState;
-			context: PageReactContext;
+			state: ReactRouterState;
 		};
 	}
 }
@@ -81,12 +71,13 @@ declare module "@alepha/core" {
 export const AlephaReact = $module({
 	name: "alepha.react",
 	descriptors: [$page],
-	services: [ReactServerProvider, PageDescriptorProvider, ReactBrowserProvider],
+	services: [ReactServerProvider, ReactPageProvider, ReactRouter],
 	register: (alepha) =>
 		alepha
 			.with(AlephaServer)
 			.with(AlephaServerCache)
 			.with(AlephaServerLinks)
 			.with(ReactServerProvider)
-			.with(PageDescriptorProvider),
+			.with(ReactPageProvider)
+			.with(ReactRouter),
 });

package/src/providers/ReactBrowserProvider.ts

@@ -1,74 +1,124 @@
-import { $hook, $inject, $logger, Alepha } from "@alepha/core";
-import type { ApiLinksResponse } from "@alepha/server";
+import {
+	$env,
+	$hook,
+	$inject,
+	Alepha,
+	type State,
+	type Static,
+	t,
+} from "@alepha/core";
+import { DateTimeProvider } from "@alepha/datetime";
+import { $logger } from "@alepha/logger";
 import { LinkProvider } from "@alepha/server-links";
-import type { Root } from "react-dom/client";
-import { BrowserRouterProvider } from "./BrowserRouterProvider.ts";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+import { ReactBrowserRouterProvider } from "./ReactBrowserRouterProvider.ts";
 import type {
 	PreviousLayerData,
-	RouterRenderResult,
-	RouterState,
+	ReactRouterState,
 	TransitionOptions,
-} from "./PageDescriptorProvider.ts";
+} from "./ReactPageProvider.ts";
+
+const envSchema = t.object({
+	REACT_ROOT_ID: t.string({ default: "root" }),
+});
+
+declare module "@alepha/core" {
+	interface Env extends Partial<Static<typeof envSchema>> {}
+}
+
+export interface ReactBrowserRendererOptions {
+	scrollRestoration?: "top" | "manual";
+}
 
 export class ReactBrowserProvider {
+	protected readonly env = $env(envSchema);
 	protected readonly log = $logger();
 	protected readonly client = $inject(LinkProvider);
 	protected readonly alepha = $inject(Alepha);
-	protected readonly router = $inject(BrowserRouterProvider);
-	protected root!: Root;
+	protected readonly router = $inject(ReactBrowserRouterProvider);
+	protected readonly dateTimeProvider = $inject(DateTimeProvider);
+	protected root?: Root;
+
+	public options: ReactBrowserRendererOptions = {
+		scrollRestoration: "top",
+	};
+
+	protected getRootElement() {
+		const root = this.document.getElementById(this.env.REACT_ROOT_ID);
+		if (root) {
+			return root;
+		}
+
+		const div = this.document.createElement("div");
+		div.id = this.env.REACT_ROOT_ID;
+
+		this.document.body.prepend(div);
+
+		return div;
+	}
 
 	public transitioning?: {
 		to: string;
+		from?: string;
 	};
 
-	public state: RouterState = {
-		layers: [],
-		pathname: "",
-		search: "",
-	};
+	public get state(): ReactRouterState {
+		return this.alepha.state("react.router.state")!;
+	}
 
+	/**
+	 * Accessor for Document DOM API.
+	 */
 	public get document() {
 		return window.document;
 	}
 
+	/**
+	 * Accessor for History DOM API.
+	 */
 	public get history() {
 		return window.history;
 	}
 
+	/**
+	 * Accessor for Location DOM API.
+	 */
 	public get location() {
 		return window.location;
 	}
 
-	public get url(): string {
-		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}`;
-			}
+	public get base() {
+		const base = import.meta.env?.BASE_URL;
+		if (!base || base === "/") {
+			return "";
 		}
 
-		return url;
+		return base;
 	}
 
-	public pushState(url: string, replace?: boolean) {
-		let path = url;
-
-		if (import.meta?.env?.BASE_URL) {
-			path = (import.meta.env?.BASE_URL + path).replaceAll("//", "/");
+	public get url(): string {
+		const url = this.location.pathname + this.location.search;
+		if (this.base) {
+			return url.replace(this.base, "");
 		}
+		return url;
+	}
+
+	public pushState(path: string, replace?: boolean) {
+		const url = this.base + path;
 
 		if (replace) {
-			this.history.replaceState({}, "", path);
+			this.history.replaceState({}, "", url);
 		} else {
-			this.history.pushState({}, "", path);
+			this.history.pushState({}, "", url);
 		}
 	}
 
 	public async invalidate(props?: Record<string, any>) {
 		const previous: PreviousLayerData[] = [];
 
+		this.log.trace("Invalidating layers");
+
 		if (props) {
 			const [key] = Object.keys(props);
 			const value = props[key];
@@ -92,48 +142,57 @@ export class ReactBrowserProvider {
 	}
 
 	public async go(url: string, options: RouterGoOptions = {}): Promise<void> {
-		const result = await this.render({
+		this.log.trace(`Going to ${url}`, {
 			url,
+			options,
 		});
 
-		// when redirecting in browser
-		if (result.context.url.pathname !== url) {
-			// TODO: check if losing search params is acceptable?
-			this.pushState(result.context.url.pathname);
-			return;
-		}
+		await this.render({
+			url,
+			previous: options.force ? [] : this.state.layers,
+		});
 
-		if (options.replace) {
-			this.pushState(url);
+		// when redirecting in browser
+		if (this.state.url.pathname + this.state.url.search !== url) {
+			this.pushState(this.state.url.pathname + this.state.url.search);
 			return;
 		}
 
-		this.pushState(url);
+		this.pushState(url, options.replace);
 	}
 
 	protected async render(
 		options: { url?: string; previous?: PreviousLayerData[] } = {},
-	): Promise<RouterRenderResult> {
+	): Promise<void> {
 		const previous = options.previous ?? this.state.layers;
 		const url = options.url ?? this.url;
+		const start = this.dateTimeProvider.now();
 
-		this.transitioning = { to: url };
+		this.transitioning = {
+			to: url,
+			from: this.state?.url.pathname,
+		};
 
-		const result = await this.router.transition(
+		this.log.debug("Transitioning...", {
+			to: url,
+		});
+
+		const redirect = await this.router.transition(
 			new URL(`http://localhost${url}`),
-			{
-				previous,
-				state: this.state,
-			},
+			previous,
 		);
 
-		if (result.redirect) {
-			return await this.render({ url: result.redirect });
+		if (redirect) {
+			this.log.info("Redirecting to", {
+				redirect,
+			});
+			return await this.render({ url: redirect });
 		}
 
-		this.transitioning = undefined;
+		const ms = this.dateTimeProvider.now().diff(start);
+		this.log.info(`Transition OK [${ms}ms]`, this.transitioning);
 
-		return result;
+		this.transitioning = undefined;
 	}
 
 	/**
@@ -151,33 +210,57 @@ export class ReactBrowserProvider {
 
 	// -------------------------------------------------------------------------------------------------------------------
 
+	protected readonly onTransitionEnd = $hook({
+		on: "react:transition:end",
+		handler: () => {
+			if (
+				this.options.scrollRestoration === "top" &&
+				typeof window !== "undefined"
+			) {
+				this.log.trace("Restoring scroll position to top");
+				window.scrollTo(0, 0);
+			}
+		},
+	});
+
 	public readonly ready = $hook({
 		on: "ready",
 		handler: async () => {
 			const hydration = this.getHydrationState();
 			const previous = hydration?.layers ?? [];
 
-			if (hydration?.links) {
-				for (const link of hydration.links.links) {
-					this.client.pushLink(link);
+			if (hydration) {
+				// 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);
+					}
 				}
 			}
 
-			const { context } = await this.render({ previous });
+			await this.render({ previous });
 
-			await this.alepha.emit("react:browser:render", {
-				state: this.state,
-				context,
-				hydration,
-			});
+			const element = this.router.root(this.state);
+			if (hydration?.layers) {
+				this.root = hydrateRoot(this.getRootElement(), element);
+				this.log.info("Hydrated root element");
+			} else {
+				this.root ??= createRoot(this.getRootElement());
+				this.root.render(element);
+				this.log.info("Created root element");
+			}
 
 			window.addEventListener("popstate", () => {
-				// when you update silently queryparams or hash, skip rendering
+				// when you update silently queryParams or hash, skip rendering
 				// if you want to force a rendering, use #go()
-				if (this.state.pathname === this.url) {
+				if (this.base + this.state.url.pathname === this.location.pathname) {
 					return;
 				}
 
+				this.log.debug("Popstate event triggered - rendering new state", {
+					url: this.location.pathname + this.location.search,
+				});
+
 				this.render();
 			});
 		},
@@ -190,9 +273,16 @@ export interface RouterGoOptions {
 	replace?: boolean;
 	match?: TransitionOptions;
 	params?: Record<string, string>;
+	query?: Record<string, string>;
+
+	/**
+	 * Recreate the whole page, ignoring the current state.
+	 */
+	force?: boolean;
 }
 
-export interface ReactHydrationState {
+export type ReactHydrationState = {
 	layers?: Array<PreviousLayerData>;
-	links?: ApiLinksResponse;
-}
+} & {
+	[key: string]: any;
+};

package/src/providers/ReactBrowserRouterProvider.ts

@@ -0,0 +1,132 @@
+import { $hook, $inject, Alepha } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { type Route, RouterProvider } from "@alepha/router";
+import { createElement, type ReactNode } from "react";
+import NotFoundPage from "../components/NotFound.tsx";
+import {
+	isPageRoute,
+	type PageRoute,
+	type PageRouteEntry,
+	type PreviousLayerData,
+	ReactPageProvider,
+	type ReactRouterState,
+} from "./ReactPageProvider.ts";
+
+export interface BrowserRoute extends Route {
+	page: PageRoute;
+}
+
+export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
+	protected readonly log = $logger();
+	protected readonly alepha = $inject(Alepha);
+	protected readonly pageApi = $inject(ReactPageProvider);
+
+	public add(entry: PageRouteEntry) {
+		this.pageApi.add(entry);
+	}
+
+	protected readonly configure = $hook({
+		on: "configure",
+		handler: async () => {
+			for (const page of this.pageApi.getPages()) {
+				// mount only if a view is provided
+				if (page.component || page.lazy) {
+					this.push({
+						path: page.match,
+						page,
+					});
+				}
+			}
+		},
+	});
+
+	public async transition(
+		url: URL,
+		previous: PreviousLayerData[] = [],
+	): Promise<string | void> {
+		const { pathname, search } = url;
+
+		const entry: Partial<ReactRouterState> = {
+			url,
+			query: {},
+			params: {},
+			layers: [],
+			onError: () => null,
+		};
+
+		const state = entry as ReactRouterState;
+
+		await this.alepha.emit("react:transition:begin", { state });
+
+		try {
+			const { route, params } = this.match(pathname);
+
+			const query: Record<string, string> = {};
+			if (search) {
+				for (const [key, value] of new URLSearchParams(search).entries()) {
+					query[key] = String(value);
+				}
+			}
+
+			state.query = query;
+			state.params = params ?? {};
+
+			if (isPageRoute(route)) {
+				const { redirect } = await this.pageApi.createLayers(
+					route.page,
+					state,
+					previous,
+				);
+				if (redirect) {
+					return redirect;
+				}
+			}
+
+			if (state.layers.length === 0) {
+				state.layers.push({
+					name: "not-found",
+					element: createElement(NotFoundPage),
+					index: 0,
+					path: "/",
+				});
+			}
+
+			await this.alepha.emit("react:transition:success", { state });
+		} catch (e) {
+			this.log.error("Transition has failed", e);
+			state.layers = [
+				{
+					name: "error",
+					element: this.pageApi.renderError(e as Error),
+					index: 0,
+					path: "/",
+				},
+			];
+
+			await this.alepha.emit("react:transition:error", {
+				error: e as Error,
+				state,
+			});
+		}
+
+		// [feature]: local hook for leaving a page
+		if (previous) {
+			for (let i = 0; i < previous.length; i++) {
+				const layer = previous[i];
+				if (state.layers[i]?.name !== layer.name) {
+					this.pageApi.page(layer.name)?.onLeave?.();
+				}
+			}
+		}
+
+		await this.alepha.emit("react:transition:end", {
+			state,
+		});
+
+		this.alepha.state("react.router.state", state);
+	}
+
+	public root(state: ReactRouterState): ReactNode {
+		return this.pageApi.root(state);
+	}
+}