@alepha/react 0.9.3 → 0.9.4

package/src/components/NestedView.tsx

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import { useContext, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { Redirection } from "../errors/Redirection.ts";
+import { useAlepha } from "../hooks/useAlepha.ts";
 import { useRouterEvents } from "../hooks/useRouterEvents.ts";
 import ErrorBoundary from "./ErrorBoundary.tsx";
 
@@ -31,38 +32,39 @@ export interface NestedViewProps {
  * ```
  */
 const NestedView = (props: NestedViewProps) => {
-	const app = useContext(RouterContext);
 	const layer = useContext(RouterLayerContext);
 	const index = layer?.index ?? 0;
+	const alepha = useAlepha();
+	const state = alepha.state("react.router.state");
+	if (!state) {
+		throw new Error("<NestedView/> must be used inside a RouterLayerContext.");
+	}
 
 	const [view, setView] = useState<ReactNode | undefined>(
-		app?.state.layers[index]?.element,
+		state.layers[index]?.element,
 	);
 
 	useRouterEvents(
 		{
-			onEnd: ({ state, context }) => {
-				if (app) {
-					app.context = context;
-				}
+			onEnd: ({ state }) => {
 				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;
 
 	return (
 		<ErrorBoundary
 			fallback={(error) => {
-				return app.context.onError?.(error, app.context) as ReactNode;
+				const result = state.onError(error, state); // TODO: onError is not refreshed
+				if (result instanceof Redirection) {
+					return "Redirection inside ErrorBoundary is not allowed.";
+				}
+				return result as ReactNode;
 			}}
 		>
 			{element}

package/src/components/NotFound.tsx

@@ -16,7 +16,7 @@ export default function NotFoundPage(props: { style?: CSSProperties }) {
 			}}
 		>
 			<h1 style={{ fontSize: "1rem", marginBottom: "0.5rem" }}>
-				This page does not exist
+				404 - This page does not exist
 			</h1>
 		</div>
 	);

package/src/descriptors/$page.ts

@@ -11,7 +11,7 @@ import type { ServerRouteCache } from "@alepha/server-cache";
 import type { FC, ReactNode } from "react";
 import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
 import type { Redirection } from "../errors/Redirection.ts";
-import type { PageReactContext } from "../providers/PageDescriptorProvider.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 
 /**
  * Main descriptor for defining a React route in the application.
@@ -183,7 +183,7 @@ export interface PageDescriptorOptions<
 
 export type ErrorHandler = (
 	error: Error,
-	context: PageReactContext,
+	state: ReactRouterState,
 ) => ReactNode | Redirection | undefined;
 
 export class PageDescriptor<
@@ -213,6 +213,16 @@ export class PageDescriptor<
 	): Promise<PageDescriptorRenderResult> {
 		throw new Error("render method is not implemented in this environment");
 	}
+
+	public match(url: string): boolean {
+		// TODO: Implement a way to match the URL against the pathname
+		return false;
+	}
+
+	public pathname(config: any) {
+		// TODO: Implement a way to generate the pathname based on the config
+		return this.options.path || "";
+	}
 }
 
 $page[KIND] = PageDescriptor;
@@ -237,7 +247,7 @@ export interface PageDescriptorRenderOptions {
 
 export interface PageDescriptorRenderResult {
 	html: string;
-	context: PageReactContext;
+	state: ReactRouterState;
 }
 
 export interface PageRequestConfig<
@@ -255,4 +265,6 @@ export interface PageRequestConfig<
 export type PageResolve<
 	TConfig extends PageConfigSchema = PageConfigSchema,
 	TPropsParent extends object = TPropsParentDefault,
-> = PageRequestConfig<TConfig> & TPropsParent & PageReactContext;
+> = PageRequestConfig<TConfig> &
+	TPropsParent &
+	Omit<ReactRouterState, "layers" | "onError">;

package/src/errors/Redirection.ts

@@ -1,10 +1,13 @@
-import type { HrefLike } from "../hooks/RouterHookApi.ts";
-
+/**
+ * Used for Redirection during the page loading.
+ *
+ * Depends on the context, it can be thrown or just returned.
+ */
 export class Redirection extends Error {
-	public readonly page: HrefLike;
+	public readonly redirect: string;
 
-	constructor(page: HrefLike) {
+	constructor(redirect: string) {
 		super("Redirection");
-		this.page = page;
+		this.redirect = redirect;
 	}
 }

package/src/hooks/useActive.ts

@@ -1,56 +1,47 @@
-import { useContext, useMemo, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { AnchorProps } from "../providers/PageDescriptorProvider.ts";
-import type { HrefLike } from "./RouterHookApi.ts";
+import { useState } from "react";
+import type { AnchorProps } from "../providers/ReactPageProvider.ts";
 import { useRouter } from "./useRouter.ts";
-import { useRouterEvents } from "./useRouterEvents.ts";
+import { useRouterState } from "./useRouterState.ts";
 
-export const useActive = (path?: HrefLike): UseActiveHook => {
-	const router = useRouter();
-	const ctx = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!ctx || !layer) {
-		throw new Error("useRouter must be used within a RouterProvider");
-	}
-
-	const [current, setCurrent] = useState(ctx.state.pathname);
-	const href = useMemo(
-		() => router.createHref(path ?? "", layer),
-		[path, layer],
-	);
+export interface UseActiveOptions {
+	href: string;
+	startWith?: boolean;
+}
 
+export const useActive = (args: string | UseActiveOptions): UseActiveHook => {
+	const router = useRouter();
 	const [isPending, setPending] = useState(false);
+	const state = useRouterState();
+	const current = state.url.pathname;
 
-	// TODO: loose [default] or strict
-	// TODO: startWith: true (e.g. /p/1 should match /p/1/2)
-	const isActive =
+	const options: UseActiveOptions =
+		typeof args === "string" ? { href: args } : { ...args, href: args.href };
+	const href = options.href;
+
+	let isActive =
 		current === href || current === `${href}/` || `${current}/` === href;
 
-	useRouterEvents(
-		{
-			onEnd: ({ state }) => {
-				path ? setCurrent(state.pathname) : undefined;
-			},
-		},
-		[path],
-	);
+	if (options.startWith && !isActive) {
+		isActive = current.startsWith(href);
+	}
 
 	return {
 		isPending,
 		isActive,
 		anchorProps: {
-			href,
-			onClick: (ev?: any) => {
+			href: router.base(href),
+			onClick: async (ev?: any) => {
 				ev?.stopPropagation();
 				ev?.preventDefault();
 				if (isActive) return;
 				if (isPending) return;
 
 				setPending(true);
-				router.go(href).then(() => {
+				try {
+					await router.go(href);
+				} finally {
 					setPending(false);
-				});
+				}
 			},
 		},
 	};

package/src/hooks/useAlepha.ts

@@ -1,11 +1,25 @@
-import type { Alepha } from "@alepha/core";
+import { type Alepha, AlephaError } from "@alepha/core";
 import { useContext } from "react";
 import { AlephaContext } from "../contexts/AlephaContext.ts";
 
+/**
+ * Main Alepha hook.
+ *
+ * It provides access to the Alepha instance within a React component.
+ *
+ * With Alepha, you can access the core functionalities of the framework:
+ *
+ * - alepha.state() for state management
+ * - alepha.inject() for dependency injection
+ * - alepha.emit() for event handling
+ * etc...
+ */
 export const useAlepha = (): Alepha => {
 	const alepha = useContext(AlephaContext);
 	if (!alepha) {
-		throw new Error("useAlepha must be used within an AlephaContext.Provider");
+		throw new AlephaError(
+			"Hook 'useAlepha()' must be used within an AlephaContext.Provider",
+		);
 	}
 
 	return alepha;

package/src/hooks/useClient.ts

@@ -4,11 +4,14 @@ import {
 	LinkProvider,
 } from "@alepha/server-links";
 import { useInject } from "./useInject.ts";
-import { useStore } from "./useStore.ts";
 
+/**
+ * Hook to get a virtual client for the specified scope.
+ *
+ * It's the React-hook version of `$client()`, from `AlephaServerLinks` module.
+ */
 export const useClient = <T extends object>(
-	_scope?: ClientScope,
+	scope?: ClientScope,
 ): HttpVirtualClient<T> => {
-	useStore("user" as any);
-	return useInject(LinkProvider).client<T>();
+	return useInject(LinkProvider).client<T>(scope);
 };

package/src/hooks/useInject.ts

@@ -2,8 +2,11 @@ import type { Service } from "@alepha/core";
 import { useMemo } from "react";
 import { useAlepha } from "./useAlepha.ts";
 
+/**
+ * Hook to inject a service instance.
+ * It's a wrapper of `useAlepha().inject(service)` with a memoization.
+ */
 export const useInject = <T extends object>(service: Service<T>): T => {
 	const alepha = useAlepha();
-
 	return useMemo(() => alepha.inject(service), []);
 };

package/src/hooks/useQueryParams.ts

@@ -3,12 +3,9 @@ import { useEffect, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 import { useRouter } from "./useRouter.ts";
 
-export interface UseQueryParamsHookOptions {
-	format?: "base64" | "querystring";
-	key?: string;
-	push?: boolean;
-}
-
+/**
+ * Not well tested. Use with caution.
+ */
 export const useQueryParams = <T extends TObject>(
 	schema: T,
 	options: UseQueryParamsHookOptions = {},
@@ -40,6 +37,12 @@ export const useQueryParams = <T extends TObject>(
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface UseQueryParamsHookOptions {
+	format?: "base64" | "querystring";
+	key?: string;
+	push?: boolean;
+}
+
 const encode = (alepha: Alepha, schema: TObject, data: any) => {
 	return btoa(JSON.stringify(alepha.parse(schema, data)));
 };

package/src/hooks/useRouter.ts

@@ -1,33 +1,20 @@
-import { useContext, useMemo } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import { PageDescriptorProvider } from "../providers/PageDescriptorProvider.ts";
-import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
-import { RouterHookApi } from "./RouterHookApi.ts";
-import { useAlepha } from "./useAlepha.ts";
+import { ReactRouter } from "../services/ReactRouter.ts";
+import { useInject } from "./useInject.ts";
 
-export const useRouter = <T extends object>(): RouterHookApi<T> => {
-	const alepha = useAlepha();
-	const ctx = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!ctx || !layer) {
-		throw new Error("useRouter must be used within a RouterProvider");
-	}
-
-	const pages = useMemo(() => {
-		return alepha.inject(PageDescriptorProvider).getPages();
-	}, []);
-
-	return useMemo(
-		() =>
-			new RouterHookApi(
-				pages,
-				ctx.context,
-				ctx.state,
-				layer,
-				alepha.inject(PageDescriptorProvider),
-				alepha.isBrowser() ? alepha.inject(ReactBrowserProvider) : undefined,
-			),
-		[layer],
-	);
+/**
+ * Use this hook to access the React Router instance.
+ *
+ * You can add a type parameter to specify the type of your application.
+ * This will allow you to use the router in a typesafe way.
+ *
+ * @example
+ * class App {
+ *   home = $page();
+ * }
+ *
+ * const router = useRouter<App>();
+ * router.go("home"); // typesafe
+ */
+export const useRouter = <T extends object = any>(): ReactRouter<T> => {
+	return useInject(ReactRouter<T>);
 };

package/src/hooks/useRouterEvents.ts

@@ -1,15 +1,15 @@
 import { useEffect } from "react";
-import type {
-	PageReactContext,
-	RouterState,
-} from "../providers/PageDescriptorProvider.ts";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { useAlepha } from "./useAlepha.ts";
 
+/**
+ * Subscribe to various router events.
+ */
 export const useRouterEvents = (
 	opts: {
-		onBegin?: (ev: { state: RouterState }) => void;
-		onEnd?: (ev: { state: RouterState; context: PageReactContext }) => void;
-		onError?: (ev: { state: RouterState; error: Error }) => void;
+		onBegin?: (ev: { state: ReactRouterState }) => void;
+		onEnd?: (ev: { state: ReactRouterState }) => void;
+		onError?: (ev: { state: ReactRouterState; error: Error }) => void;
 	} = {},
 	deps: any[] = [],
 ) => {

package/src/hooks/useRouterState.ts

@@ -1,23 +1,11 @@
-import { useContext, useState } from "react";
-import { RouterContext } from "../contexts/RouterContext.ts";
-import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
-import type { RouterState } from "../providers/PageDescriptorProvider.ts";
-import { useRouterEvents } from "./useRouterEvents.ts";
-
-export const useRouterState = (): RouterState => {
-	const router = useContext(RouterContext);
-	const layer = useContext(RouterLayerContext);
-	if (!router || !layer) {
-		throw new Error(
-			"useRouterState must be used within a RouterContext.Provider",
-		);
+import { AlephaError } from "@alepha/core";
+import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
+import { useStore } from "./useStore.ts";
+
+export const useRouterState = (): ReactRouterState => {
+	const [state] = useStore("react.router.state");
+	if (!state) {
+		throw new AlephaError("Missing react router state");
 	}
-
-	const [state, setState] = useState(router.state);
-
-	useRouterEvents({
-		onEnd: ({ state }) => setState({ ...state }),
-	});
-
 	return state;
 };

package/src/hooks/useSchema.ts

@@ -4,11 +4,7 @@ import {
 	HttpClient,
 	type RequestConfigSchema,
 } from "@alepha/server";
-import {
-	type HttpClientLink,
-	LinkProvider,
-	type VirtualAction,
-} from "@alepha/server-links";
+import { LinkProvider, type VirtualAction } from "@alepha/server-links";
 import { useEffect, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 import { useInject } from "./useInject.ts";
@@ -19,7 +15,6 @@ export const useSchema = <TConfig extends RequestConfigSchema>(
 	const name = action.name;
 	const alepha = useAlepha();
 	const httpClient = useInject(HttpClient);
-	const linkProvider = useInject(LinkProvider);
 	const [schema, setSchema] = useState<UseSchemaReturn<TConfig>>(
 		ssrSchemaLoading(alepha, name) as UseSchemaReturn<TConfig>,
 	);
@@ -34,7 +29,7 @@ export const useSchema = <TConfig extends RequestConfigSchema>(
 		};
 
 		httpClient
-			.fetch(`${linkProvider.URL_LINKS}/${name}/schema`, {}, opts)
+			.fetch(`${LinkProvider.path.apiLinks}/${name}/schema`, {}, opts)
 			.then((it) => setSchema(it.data as UseSchemaReturn<TConfig>));
 	}, [name]);
 
@@ -54,26 +49,26 @@ export const ssrSchemaLoading = (alepha: Alepha, name: string) => {
 	// server-side rendering (SSR) context
 	if (!alepha.isBrowser()) {
 		// get user links
-		const links =
-			alepha.context.get<{ links: HttpClientLink[] }>("links")?.links ?? [];
+		const linkProvider = alepha.inject(LinkProvider);
 
 		// check if user can access the link
-		const can = links.find((it) => it.name === name);
+		const can = linkProvider
+			.getServerLinks()
+			.find((link) => link.name === name);
 
 		// yes!
 		if (can) {
 			// user-links have no schema, so we need to get it from the provider
-			const schema = alepha
-				.inject(LinkProvider)
-				.links?.find((it) => it.name === name)?.schema;
+			const schema = linkProvider.links.find((it) => it.name === name)?.schema;
 
 			// oh, we have a schema!
 			if (schema) {
-				// attach to user link, it will be used in the client during hydration :)
+				// attach to user link, it will be used in the client during hydration
 				can.schema = schema;
 				return schema;
 			}
 		}
+
 		return { loading: true };
 	}
 
@@ -81,7 +76,7 @@ export const ssrSchemaLoading = (alepha: Alepha, name: string) => {
 	// check if we have the schema already loaded
 	const schema = alepha
 		.inject(LinkProvider)
-		.links?.find((it) => it.name === name)?.schema;
+		.links.find((it) => it.name === name)?.schema;
 
 	// yes!
 	if (schema) {

package/src/hooks/useStore.ts

@@ -31,13 +31,6 @@ export const useStore = <Key extends keyof State>(
 		});
 	}, []);
 
-	if (!alepha.isBrowser()) {
-		const value = alepha.context.get(key) as State[Key];
-		if (value !== null) {
-			return [value, (_: State[Key]) => {}] as const;
-		}
-	}
-
 	return [
 		state,
 		(value: State[Key]) => {

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 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/Redirection.ts";
-export * from "./hooks/RouterHookApi.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";