@alepha/react 0.6.3 → 0.6.5

package/src/components/NestedView.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import { useContext, useState } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { useRouterEvents } from "../hooks/useRouterEvents.ts";
+
+export interface NestedViewProps {
+	children?: ReactNode;
+}
+
+/**
+ * Nested view component
+ *
+ * @param props
+ * @constructor
+ */
+const NestedView = (props: NestedViewProps) => {
+	const app = useContext(RouterContext);
+	const layer = useContext(RouterLayerContext);
+	const index = layer?.index ?? 0;
+
+	const [view, setView] = useState<ReactNode | undefined>(
+		app?.state.layers[index]?.element,
+	);
+
+	useRouterEvents(
+		{
+			onEnd: ({ state }) => {
+				setView(state.layers[index]?.element);
+			},
+		},
+		[app],
+	);
+
+	return view ?? props.children ?? null;
+};
+
+export default NestedView;

package/src/contexts/RouterContext.ts

@@ -0,0 +1,16 @@
+import type { Alepha } from "@alepha/core";
+import { createContext } from "react";
+import type {
+	PageReactContext,
+	RouterState,
+} from "../providers/PageDescriptorProvider.ts";
+
+export interface RouterContextValue {
+	alepha: Alepha;
+	state: RouterState;
+	context: PageReactContext;
+}
+
+export const RouterContext = createContext<RouterContextValue | undefined>(
+	undefined,
+);

package/src/contexts/RouterLayerContext.ts

@@ -0,0 +1,10 @@
+import { createContext } from "react";
+
+export interface RouterLayerContextValue {
+	index: number;
+	path: string;
+}
+
+export const RouterLayerContext = createContext<
+	RouterLayerContextValue | undefined
+>(undefined);

package/src/descriptors/$page.ts

@@ -0,0 +1,142 @@
+import { type Async, OPTIONS, type Static, type TSchema } from "@alepha/core";
+import { KIND, NotImplementedError, __descriptor } from "@alepha/core";
+import type { FC } from "react";
+import type { RouterHookApi } from "../hooks/RouterHookApi.ts";
+
+const KEY = "PAGE";
+
+export interface PageConfigSchema {
+	query?: TSchema;
+	params?: TSchema;
+}
+
+export type TPropsDefault = any;
+
+export type TPropsParentDefault = object;
+
+export interface PageDescriptorOptions<
+	TConfig extends PageConfigSchema = PageConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+> {
+	name?: string;
+
+	path?: string;
+
+	schema?: TConfig;
+
+	resolve?: (config: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
+
+	component?: FC<TProps & TPropsParent>;
+
+	lazy?: () => Promise<{ default: FC<TProps & TPropsParent> }>;
+
+	children?: Array<{ [OPTIONS]: PageDescriptorOptions }>;
+
+	parent?: { [OPTIONS]: PageDescriptorOptions<any, TPropsParent> };
+
+	can?: () => boolean;
+
+	head?: Head | ((props: TProps, previous?: Head) => Head);
+
+	errorHandler?: FC<{ error: Error; url: string }>;
+}
+
+export interface PageDescriptor<
+	TConfig extends PageConfigSchema = PageConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+> {
+	[KIND]: typeof KEY;
+	[OPTIONS]: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
+
+	render: (options?: {
+		params?: Record<string, string>;
+		query?: Record<string, string>;
+	}) => Promise<string>;
+	go: () => void;
+	createAnchorProps: (routerHook: RouterHookApi) => {
+		href: string;
+		onClick: () => void;
+	};
+	can: () => boolean;
+}
+
+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);
+		},
+		go: () => {
+			throw new NotImplementedError(KEY);
+		},
+		createAnchorProps: () => {
+			throw new NotImplementedError(KEY);
+		},
+		can: () => {
+			if (options.can) {
+				return options.can();
+			}
+			return true;
+		},
+	};
+};
+
+$page[KIND] = KEY;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface Head {
+	title?: string;
+	titleSeparator?: string;
+	htmlAttributes?: Record<string, string>;
+	bodyAttributes?: Record<string, string>;
+	meta?: Array<{ name: string; content: string }>;
+}
+
+export interface PageRequestConfig<
+	TConfig extends PageConfigSchema = PageConfigSchema,
+> {
+	params: TConfig["params"] extends TSchema
+		? Static<TConfig["params"]>
+		: Record<string, string>;
+
+	query: TConfig["query"] extends TSchema
+		? Static<TConfig["query"]>
+		: Record<string, string>;
+}
+
+export type PageResolve<
+	TConfig extends PageConfigSchema = PageConfigSchema,
+	TPropsParent extends object = TPropsParentDefault,
+> = PageRequestConfig<TConfig> & TPropsParent & PageResolveContext;
+
+export interface PageResolveContext {
+	url: URL;
+	head: Head;
+}

package/src/errors/RedirectionError.ts

@@ -0,0 +1,7 @@
+import type { HrefLike } from "../hooks/RouterHookApi.ts";
+
+export class RedirectionError extends Error {
+	constructor(public readonly page: HrefLike) {
+		super("Redirection");
+	}
+}

package/src/hooks/RouterHookApi.ts

@@ -0,0 +1,156 @@
+import type {
+	AnchorProps,
+	RouterState,
+} from "../providers/PageDescriptorProvider.ts";
+import type {
+	ReactBrowserProvider,
+	RouterGoOptions,
+} from "../providers/ReactBrowserProvider.ts";
+
+export class RouterHookApi {
+	constructor(
+		private readonly state: RouterState,
+		private readonly layer: {
+			path: string;
+		},
+		private readonly browser?: ReactBrowserProvider,
+	) {}
+
+	/**
+	 *
+	 */
+	public get current(): RouterState {
+		return this.state;
+	}
+
+	/**
+	 *
+	 */
+	public get pathname(): string {
+		return this.state.pathname;
+	}
+
+	/**
+	 *
+	 */
+	public get query(): Record<string, string> {
+		const query: Record<string, string> = {};
+
+		for (const [key, value] of new URLSearchParams(
+			this.state.search,
+		).entries()) {
+			query[key] = String(value);
+		}
+
+		return query;
+	}
+
+	/**
+	 *
+	 */
+	public async back() {
+		this.browser?.history.back();
+	}
+
+	/**
+	 *
+	 */
+	public async forward() {
+		this.browser?.history.forward();
+	}
+
+	/**
+	 *
+	 * @param props
+	 */
+	public async invalidate(props?: Record<string, any>) {
+		await this.browser?.invalidate(props);
+	}
+
+	/**
+	 * Create a valid href for the given pathname.
+	 *
+	 * @param pathname
+	 * @param layer
+	 */
+	public createHref(pathname: HrefLike, layer: { path: string } = this.layer) {
+		if (typeof pathname === "object") {
+			pathname = pathname.options.path ?? "";
+		}
+
+		return pathname.startsWith("/")
+			? pathname
+			: `${layer.path}/${pathname}`.replace(/\/\/+/g, "/");
+	}
+
+	/**
+	 *
+	 * @param path
+	 * @param options
+	 */
+	public async go(
+		path: HrefLike,
+		options: RouterGoOptions = {},
+	): Promise<void> {
+		return await this.browser?.go(this.createHref(path, this.layer), options);
+	}
+
+	/**
+	 *
+	 * @param path
+	 */
+	public createAnchorProps(path: string): AnchorProps {
+		const href = this.createHref(path, this.layer);
+		return {
+			href,
+			onClick: (ev: any) => {
+				ev.stopPropagation();
+				ev.preventDefault();
+
+				this.go(path).catch(console.error);
+			},
+		};
+	}
+
+	/**
+	 * Set query params.
+	 *
+	 * @param record
+	 * @param options
+	 */
+	public setQueryParams(
+		record: Record<string, any>,
+		options: {
+			/**
+			 * If true, this will merge current query params with the new ones.
+			 */
+			merge?: boolean;
+
+			/**
+			 * If true, this will add a new entry to the history stack.
+			 */
+			push?: boolean;
+		} = {},
+	) {
+		const search = new URLSearchParams(
+			options.merge
+				? {
+						...this.query,
+						...record,
+					}
+				: {
+						...record,
+					},
+		).toString();
+
+		const state = search ? `${this.pathname}?${search}` : this.pathname;
+
+		if (options.push) {
+			window.history.pushState({}, "", state);
+		} else {
+			window.history.replaceState({}, "", state);
+		}
+	}
+}
+
+export type HrefLike = string | { options: { path?: string; name?: string } };

package/src/hooks/useActive.ts

@@ -0,0 +1,57 @@
+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 { useRouter } from "./useRouter.ts";
+import { useRouterEvents } from "./useRouterEvents.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");
+	}
+
+	let name: string | undefined;
+	if (typeof path === "object" && path.options.name) {
+		name = path.options.name;
+	}
+
+	const [current, setCurrent] = useState(ctx.state.pathname);
+	const href = useMemo(() => router.createHref(path, layer), [path, layer]);
+	const [isPending, setPending] = useState(false);
+	const isActive = current === href;
+
+	useRouterEvents({
+		onEnd: ({ state }) => setCurrent(state.pathname),
+	});
+
+	return {
+		name,
+		isPending,
+		isActive,
+		anchorProps: {
+			href,
+			onClick: (ev: any) => {
+				ev.stopPropagation();
+				ev.preventDefault();
+				if (isActive) return;
+				if (isPending) return;
+
+				setPending(true);
+				router.go(href).then(() => {
+					setPending(false);
+				});
+			},
+		},
+	};
+};
+
+export interface UseActiveHook {
+	isActive: boolean;
+	anchorProps: AnchorProps;
+	isPending: boolean;
+	name?: string;
+}

package/src/hooks/useClient.ts

@@ -0,0 +1,6 @@
+import { HttpClient } from "@alepha/server";
+import { useInject } from "./useInject.ts";
+
+export const useClient = (): HttpClient => {
+	return useInject(HttpClient);
+};

package/src/hooks/useInject.ts

@@ -0,0 +1,14 @@
+import type { Class } from "@alepha/core";
+import { useContext } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+
+export const useInject = <T extends object>(clazz: Class<T>): T => {
+	const ctx = useContext(RouterContext);
+	if (!ctx) {
+		throw new Error("useRouter must be used within a <RouterProvider>");
+	}
+
+	return ctx.alepha.get(clazz, {
+		skipRegistration: true,
+	});
+};

package/src/hooks/useQueryParams.ts

@@ -0,0 +1,59 @@
+import type { Alepha, Static, TObject } from "@alepha/core";
+import { useContext, useEffect, useState } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+import { useRouter } from "./useRouter.ts";
+
+export interface UseQueryParamsHookOptions {
+	format?: "base64" | "querystring";
+	key?: string;
+	push?: boolean;
+}
+
+export const useQueryParams = <T extends TObject>(
+	schema: T,
+	options: UseQueryParamsHookOptions = {},
+): [Static<T>, (data: Static<T>) => void] => {
+	const ctx = useContext(RouterContext);
+	if (!ctx) {
+		throw new Error("useQueryParams must be used within a RouterProvider");
+	}
+
+	const key = options.key ?? "q";
+	const router = useRouter();
+	const querystring = router.query[key];
+
+	const [queryParams, setQueryParams] = useState(
+		decode(ctx.alepha, schema, router.query[key]),
+	);
+
+	useEffect(() => {
+		setQueryParams(decode(ctx.alepha, schema, querystring));
+	}, [querystring]);
+
+	return [
+		queryParams,
+		(queryParams: Static<T>) => {
+			setQueryParams(queryParams);
+			router.setQueryParams(
+				{ [key]: encode(ctx.alepha, schema, queryParams) },
+				{
+					merge: true,
+				},
+			);
+		},
+	];
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const encode = (alepha: Alepha, schema: TObject, data: any) => {
+	return btoa(JSON.stringify(alepha.parse(schema, data)));
+};
+
+const decode = (alepha: Alepha, schema: TObject, data: any) => {
+	try {
+		return alepha.parse(schema, JSON.parse(atob(decodeURIComponent(data))));
+	} catch (error) {
+		return {};
+	}
+};

package/src/hooks/useRouter.ts

@@ -0,0 +1,25 @@
+import { useContext, useMemo } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
+import { RouterHookApi } from "./RouterHookApi.ts";
+
+export const useRouter = (): RouterHookApi => {
+	const ctx = useContext(RouterContext);
+	const layer = useContext(RouterLayerContext);
+	if (!ctx || !layer) {
+		throw new Error("useRouter must be used within a RouterProvider");
+	}
+
+	return useMemo(
+		() =>
+			new RouterHookApi(
+				ctx.state,
+				layer,
+				ctx.alepha.isBrowser()
+					? ctx.alepha.get(ReactBrowserProvider)
+					: undefined,
+			),
+		[layer],
+	);
+};

package/src/hooks/useRouterEvents.ts

@@ -0,0 +1,58 @@
+import { useContext, useEffect } from "react";
+import { RouterContext } from "../contexts/RouterContext.ts";
+import type { RouterState } from "../providers/PageDescriptorProvider.ts";
+
+export const useRouterEvents = (
+	opts: {
+		onBegin?: (ev: { state: RouterState }) => void;
+		onEnd?: (ev: { state: RouterState }) => void;
+		onError?: (ev: { state: RouterState; error: Error }) => void;
+	} = {},
+	deps: any[] = [],
+) => {
+	const ctx = useContext(RouterContext);
+	if (!ctx) {
+		throw new Error("useRouter must be used within a RouterProvider");
+	}
+
+	useEffect(() => {
+		if (!ctx.alepha.isBrowser()) {
+			return;
+		}
+
+		const subs: Function[] = [];
+		const onBegin = opts.onBegin;
+		const onEnd = opts.onEnd;
+		const onError = opts.onError;
+
+		if (onBegin) {
+			subs.push(
+				ctx.alepha.on("react:transition:begin", {
+					callback: onBegin,
+				}),
+			);
+		}
+
+		if (onEnd) {
+			subs.push(
+				ctx.alepha.on("react:transition:end", {
+					callback: onEnd,
+				}),
+			);
+		}
+
+		if (onError) {
+			subs.push(
+				ctx.alepha.on("react:transition:error", {
+					callback: onError,
+				}),
+			);
+		}
+
+		return () => {
+			for (const sub of subs) {
+				sub();
+			}
+		};
+	}, deps);
+};

package/src/hooks/useRouterState.ts

@@ -0,0 +1,21 @@
+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 ctx = useContext(RouterContext);
+	const layer = useContext(RouterLayerContext);
+	if (!ctx || !layer) {
+		throw new Error("useRouter must be used within a RouterProvider");
+	}
+
+	const [state, setState] = useState(ctx.state);
+
+	useRouterEvents({
+		onEnd: ({ state }) => setState({ ...state }),
+	});
+
+	return state;
+};

package/src/index.browser.ts

@@ -0,0 +1,21 @@
+import { $inject, Alepha, __bind } from "@alepha/core";
+import { $page } from "./descriptors/$page.ts";
+import { BrowserRouterProvider } from "./providers/BrowserRouterProvider.ts";
+import { PageDescriptorProvider } from "./providers/PageDescriptorProvider.ts";
+import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
+
+export * from "./index.shared";
+export * from "./providers/ReactBrowserProvider.ts";
+
+export class ReactModule {
+	protected readonly alepha = $inject(Alepha);
+
+	constructor() {
+		this.alepha //
+			.with(PageDescriptorProvider)
+			.with(ReactBrowserProvider)
+			.with(BrowserRouterProvider);
+	}
+}
+
+__bind($page, ReactModule);

package/src/index.shared.ts

@@ -0,0 +1,15 @@
+export { default as NestedView } from "./components/NestedView.tsx";
+export { default as Link } from "./components/Link.tsx";
+
+export * from "./contexts/RouterContext.ts";
+export * from "./contexts/RouterLayerContext.ts";
+export * from "./descriptors/$page.ts";
+export * from "./hooks/RouterHookApi.ts";
+export * from "./hooks/useInject.ts";
+export * from "./hooks/useClient.ts";
+export * from "./hooks/useQueryParams.ts";
+export * from "./hooks/useRouter.ts";
+export * from "./hooks/useRouterEvents.ts";
+export * from "./hooks/useRouterState.ts";
+export * from "./hooks/useActive.ts";
+export * from "./errors/RedirectionError.ts";