@alepha/react 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Feunard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @alepha/server
+
+## Installation
+
+```bash
+npm install @alepha/server
+```
+
+## Usage
+
+```ts
+import { Alepha, route } from "@alepha/server";
+
+class App {
+  index = route({
+    handler: () => "Hello, World!",
+  });
+}
+
+Alepha
+  .create({
+    SERVER_PORT: 3000,
+    SERVER_OPENAPI_ENABLED: true,
+    SERVER_SECURITY_ENABLED: true,
+  })
+  .with(App)
+  .start();
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@alepha/react",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "browser": "./dist/index.browser.mjs",
+  "dependencies": {
+    "@alepha/cache": "0.5.0",
+    "@alepha/core": "0.5.0",
+    "@alepha/security": "0.5.0",
+    "@alepha/server": "0.5.0",
+    "openid-client": "^6.4.1",
+    "path-to-regexp": "^8.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.20",
+    "@types/react-dom": "^18.3.5",
+    "pkgroll": "^2.12.1",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist"
+  },
+  "exports": {
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    },
+    "import": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "browser": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.browser.mjs"
+    }
+  }
+}

package/src/components/NestedView.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { useContext, useEffect, useState } from "react";
+import { RouterContext } from "../contexts/RouterContext";
+import { RouterLayerContext } from "../contexts/RouterLayerContext";
+
+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,
+	);
+
+	useEffect(() => {
+		if (app?.alepha.isBrowser()) {
+			return app?.router.on("end", ({ layers }) => {
+				setView(layers[index]?.element);
+			});
+		}
+	}, [app]);
+
+	return view ?? props.children ?? null;
+};
+
+export default NestedView;

package/src/contexts/RouterContext.ts

@@ -0,0 +1,15 @@
+import type { Alepha } from "@alepha/core";
+import { createContext } from "react";
+import type { Session } from "../providers/ReactSessionProvider";
+import type { Router, RouterState } from "../services/Router";
+
+export interface RouterContextValue {
+	router: Router;
+	alepha: Alepha;
+	state: RouterState;
+	session?: Session;
+}
+
+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,90 @@
+import type { Async, Static, TSchema } from "@alepha/core";
+import { KIND, NotImplementedError, __descriptor } from "@alepha/core";
+import type { UserAccountToken } from "@alepha/security";
+import type { FC } from "react";
+import type { RouterHookApi } from "../hooks/RouterHookApi";
+
+export const pageDescriptorKey = "PAGE";
+
+export interface PageDescriptorConfigSchema {
+	query?: TSchema;
+	params?: TSchema;
+}
+export type TPropsDefault = any;
+export type TPropsParentDefault = object;
+
+export interface PageDescriptorOptions<
+	TConfig extends PageDescriptorConfigSchema = PageDescriptorConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+> {
+	parent?: { options: PageDescriptorOptions<any, TPropsParent> };
+	name?: string;
+	path?: string;
+	schema?: TConfig;
+	abstract?: boolean;
+	resolve?: (
+		config: PageDescriptorConfigValue<TConfig> &
+			TPropsParent & { user?: UserAccountToken },
+	) => Async<TProps>;
+	component?: FC<TProps & TPropsParent>;
+	lazy?: () => Promise<{ default: FC<TProps & TPropsParent> }>;
+	children?: () => Array<{ options: PageDescriptorOptions }>;
+	notFoundHandler?: FC<{ error: Error }>;
+	errorHandler?: FC<{ error: Error; url: string }>;
+}
+
+export interface PageDescriptorConfigValue<
+	TConfig extends PageDescriptorConfigSchema = PageDescriptorConfigSchema,
+> {
+	query: TConfig["query"] extends TSchema
+		? Static<TConfig["query"]>
+		: Record<string, string>;
+	params: TConfig["params"] extends TSchema
+		? Static<TConfig["params"]>
+		: Record<string, string>;
+	pathname: string;
+}
+
+export interface PageDescriptor<
+	TConfig extends PageDescriptorConfigSchema = PageDescriptorConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+> {
+	[KIND]: typeof pageDescriptorKey;
+	render: (options?: {
+		params?: Record<string, string>;
+		query?: Record<string, string>;
+	}) => Promise<string>;
+	go: () => void;
+	createAnchorProps: (routerHook: RouterHookApi) => {
+		href: string;
+		onClick: () => void;
+	};
+	options: PageDescriptorOptions<TConfig, TProps, TPropsParent>;
+}
+
+export const $page = <
+	TConfig extends PageDescriptorConfigSchema = PageDescriptorConfigSchema,
+	TProps extends object = TPropsDefault,
+	TPropsParent extends object = TPropsParentDefault,
+>(
+	options: PageDescriptorOptions<TConfig, TProps, TPropsParent>,
+): PageDescriptor<TConfig, TProps, TPropsParent> => {
+	__descriptor(pageDescriptorKey);
+	return {
+		[KIND]: pageDescriptorKey,
+		options,
+		render: () => {
+			throw new NotImplementedError(pageDescriptorKey);
+		},
+		go: () => {
+			throw new NotImplementedError(pageDescriptorKey);
+		},
+		createAnchorProps: () => {
+			throw new NotImplementedError(pageDescriptorKey);
+		},
+	};
+};
+
+$page[KIND] = pageDescriptorKey;

package/src/hooks/RouterHookApi.ts

@@ -0,0 +1,154 @@
+import {} from "react";
+import type {
+	ReactBrowserProvider,
+	RouterGoOptions,
+} from "../providers/ReactBrowserProvider";
+import type { AnchorProps, RouterState } from "../services/Router";
+
+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, useEffect, useMemo, useState } from "react";
+import { RouterContext } from "../contexts/RouterContext";
+import { RouterLayerContext } from "../contexts/RouterLayerContext";
+import type { AnchorProps } from "../services/Router";
+import type { HrefLike } from "./RouterHookApi";
+import { useRouter } from "./useRouter";
+
+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;
+
+	useEffect(
+		() => ctx.router.on("end", ({ pathname }) => setCurrent(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";
+
+export const useClient = (): HttpClient => {
+	return useInject(HttpClient);
+};

package/src/hooks/useInject.ts

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

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";
+import { useRouter } from "./useRouter";
+
+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,28 @@
+import { useContext, useMemo } from "react";
+import { RouterContext } from "../contexts/RouterContext";
+import { RouterLayerContext } from "../contexts/RouterLayerContext";
+import { ReactBrowserProvider } from "../providers/ReactBrowserProvider";
+import { RouterHookApi } from "./RouterHookApi";
+
+/**
+ *
+ */
+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,
+			),
+		[ctx.router, layer],
+	);
+};

package/src/hooks/useRouterEvents.ts

@@ -0,0 +1,43 @@
+import { useContext, useEffect } from "react";
+import { RouterContext } from "../contexts/RouterContext";
+import { RouterLayerContext } from "../contexts/RouterLayerContext";
+import type { RouterState } from "../services/Router";
+
+export const useRouterEvents = (
+	opts: {
+		onBegin?: () => void;
+		onEnd?: (it: RouterState) => void;
+		onError?: (it: Error) => void;
+	} = {},
+) => {
+	const ctx = useContext(RouterContext);
+	const layer = useContext(RouterLayerContext);
+	if (!ctx || !layer) {
+		throw new Error("useRouter must be used within a RouterProvider");
+	}
+
+	useEffect(() => {
+		const subs: Function[] = [];
+		const onBegin = opts.onBegin;
+		const onEnd = opts.onEnd;
+		const onError = opts.onError;
+
+		if (onBegin) {
+			subs.push(ctx.router.on("begin", onBegin));
+		}
+
+		if (onEnd) {
+			subs.push(ctx.router.on("end", onEnd));
+		}
+
+		if (onError) {
+			subs.push(ctx.router.on("error", onError));
+		}
+
+		return () => {
+			for (const sub of subs) {
+				sub();
+			}
+		};
+	}, []);
+};

package/src/hooks/useRouterState.ts

@@ -0,0 +1,23 @@
+import { useContext, useEffect, useState } from "react";
+import { RouterContext } from "../contexts/RouterContext";
+import { RouterLayerContext } from "../contexts/RouterLayerContext";
+import type { RouterState } from "../services/Router";
+
+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);
+	useEffect(
+		() =>
+			ctx.router.on("end", (it) => {
+				setState({ ...it });
+			}),
+		[],
+	);
+
+	return state;
+};

package/src/index.browser.ts

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

package/src/index.shared.ts

@@ -0,0 +1,17 @@
+export { default as NestedView } from "./components/NestedView";
+
+export * from "./contexts/RouterContext";
+export * from "./contexts/RouterLayerContext";
+
+export * from "./descriptors/$page";
+
+export * from "./hooks/useActive";
+export * from "./hooks/useClient";
+export * from "./hooks/useInject";
+export * from "./hooks/useQueryParams";
+export * from "./hooks/RouterHookApi";
+export * from "./hooks/useRouter";
+export * from "./hooks/useRouterEvents";
+export * from "./hooks/useRouterState";
+
+export * from "./services/Router";