@alepha/react 0.11.3 → 0.11.4

package/README.md

@@ -147,6 +147,29 @@ Hook to get a virtual client for the specified scope.
 
 It's the React-hook version of `$client()`, from `AlephaServerLinks` module.
 
+#### useEvents()
+
+Allow subscribing to multiple Alepha events. See {@link Hooks} for available events.
+
+useEvents is fully typed to ensure correct event callback signatures.
+
+```tsx
+useEvents(
+  {
+    "react:transition:begin": (ev) => {
+      console.log("Transition began to:", ev.to);
+    },
+    "react:transition:error": {
+      priority: "first",
+      callback: (ev) => {
+        console.error("Transition error:", ev.error);
+      },
+    },
+  },
+  [],
+);
+```
+
 #### useInject()
 
 Hook to inject a service instance.
@@ -170,10 +193,6 @@ class App {
 const router = useRouter<App>();
 router.go("home"); // typesafe
 
-#### useRouterEvents()
-
-Subscribe to various router events.
-
 #### useStore()
 
 Hook to access and mutate the Alepha state.

package/dist/index.browser.js

@@ -1,13 +1,24 @@
 import { $env, $hook, $inject, $module, Alepha, AlephaError, Descriptor, KIND, createDescriptor, t } from "@alepha/core";
+import { AlephaDateTime, DateTimeProvider } from "@alepha/datetime";
 import { AlephaServer, HttpClient } from "@alepha/server";
 import { AlephaServerLinks, LinkProvider } from "@alepha/server-links";
-import { DateTimeProvider } from "@alepha/datetime";
 import { $logger } from "@alepha/logger";
 import { RouterProvider } from "@alepha/router";
-import React, { StrictMode, createContext, createElement, memo, use, useContext, useEffect, useMemo, useRef, useState } from "react";
+import React, { StrictMode, createContext, createElement, memo, use, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createRoot, hydrateRoot } from "react-dom/client";
 
+//#region src/services/ReactPageService.ts
+var ReactPageService = class {
+	fetch(pathname, options = {}) {
+		throw new AlephaError("Fetch is not available for this environment.");
+	}
+	render(name, options = {}) {
+		throw new AlephaError("Render is not available for this environment.");
+	}
+};
+
+//#endregion
 //#region src/descriptors/$page.ts
 /**
 * Main descriptor for defining a React route in the application.
@@ -101,6 +112,7 @@ const $page = (options) => {
 	return createDescriptor(PageDescriptor, options);
 };
 var PageDescriptor = class extends Descriptor {
+	reactPageService = $inject(ReactPageService);
 	onInit() {
 		if (this.options.static) this.options.cache ??= { store: {
 			provider: "memory",
@@ -111,14 +123,16 @@ var PageDescriptor = class extends Descriptor {
 		return this.options.name ?? this.config.propertyKey;
 	}
 	/**
-	* For testing or build purposes, this will render the page (with or without the HTML layout) and return the HTML and context.
+	* For testing or build purposes.
+	*
+	* This will render the page (HTML layout included or not) and return the HTML + context.
 	* Only valid for server-side rendering, it will throw an error if called on the client-side.
 	*/
 	async render(options) {
-		throw new AlephaError("render() method is not implemented in this environment");
+		return this.reactPageService.render(this.name, options);
 	}
 	async fetch(options) {
-		throw new AlephaError("fetch() method is not implemented in this environment");
+		return this.reactPageService.fetch(this.options.path || "", options);
 	}
 	match(url) {
 		return false;
@@ -365,29 +379,38 @@ const useAlepha = () => {
 };
 
 //#endregion
-//#region src/hooks/useRouterEvents.ts
+//#region src/hooks/useEvents.ts
 /**
-* Subscribe to various router events.
+* Allow subscribing to multiple Alepha events. See {@link Hooks} for available events.
+*
+* useEvents is fully typed to ensure correct event callback signatures.
+*
+* @example
+* ```tsx
+* useEvents(
+*   {
+*     "react:transition:begin": (ev) => {
+*       console.log("Transition began to:", ev.to);
+*     },
+*     "react:transition:error": {
+*       priority: "first",
+*       callback: (ev) => {
+*         console.error("Transition error:", ev.error);
+*       },
+*     },
+*   },
+*   [],
+* );
+* ```
 */
-const useRouterEvents = (opts = {}, deps = []) => {
+const useEvents = (opts, deps) => {
 	const alepha = useAlepha();
 	useEffect(() => {
 		if (!alepha.isBrowser()) return;
-		const cb = (callback) => {
-			if (typeof callback === "function") return { callback };
-			return callback;
-		};
 		const subs = [];
-		const onBegin = opts.onBegin;
-		const onEnd = opts.onEnd;
-		const onError = opts.onError;
-		const onSuccess = opts.onSuccess;
-		if (onBegin) subs.push(alepha.events.on("react:transition:begin", cb(onBegin)));
-		if (onEnd) subs.push(alepha.events.on("react:transition:end", cb(onEnd)));
-		if (onError) subs.push(alepha.events.on("react:transition:error", cb(onError)));
-		if (onSuccess) subs.push(alepha.events.on("react:transition:success", cb(onSuccess)));
+		for (const [name, hook] of Object.entries(opts)) subs.push(alepha.events.on(name, hook));
 		return () => {
-			for (const sub of subs) sub();
+			for (const clear of subs) clear();
 		};
 	}, deps);
 };
@@ -483,8 +506,8 @@ const NestedView = (props) => {
 	const [animation, setAnimation] = useState("");
 	const animationExitDuration = useRef(0);
 	const animationExitNow = useRef(0);
-	useRouterEvents({
-		onBegin: async ({ previous, state: state$1 }) => {
+	useEvents({
+		"react:transition:begin": async ({ previous, state: state$1 }) => {
 			const layer = previous.layers[index];
 			if (`${state$1.url.pathname}/`.startsWith(`${layer?.path}/`)) return;
 			const animationExit = parseAnimation(layer.route?.animation, state$1, "exit");
@@ -499,7 +522,7 @@ const NestedView = (props) => {
 				setAnimation("");
 			}
 		},
-		onEnd: async ({ state: state$1 }) => {
+		"react:transition:end": async ({ state: state$1 }) => {
 			const layer = state$1.layers[index];
 			if (animationExitNow.current) {
 				const duration = animationExitDuration.current;
@@ -586,9 +609,34 @@ var ReactPageProvider = class {
 	getPages() {
 		return this.pages;
 	}
+	getConcretePages() {
+		const pages = [];
+		for (const page of this.pages) {
+			if (page.children && page.children.length > 0) continue;
+			const fullPath = this.pathname(page.name);
+			if (fullPath.includes(":") || fullPath.includes("*")) {
+				if (typeof page.static === "object") {
+					const entries = page.static.entries;
+					if (entries && entries.length > 0) for (const entry of entries) {
+						const params = entry.params;
+						const path = this.compile(page.path ?? "", params);
+						if (!path.includes(":") && !path.includes("*")) pages.push({
+							...page,
+							name: params[Object.keys(params)[0]],
+							path,
+							...entry
+						});
+					}
+				}
+				continue;
+			}
+			pages.push(page);
+		}
+		return pages;
+	}
 	page(name) {
 		for (const page of this.pages) if (page.name === name) return page;
-		throw new Error(`Page ${name} not found`);
+		throw new AlephaError(`Page '${name}' not found`);
 	}
 	pathname(name, options = {}) {
 		const page = this.page(name);
@@ -901,6 +949,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			onError: () => null,
 			meta
 		};
+		await this.alepha.events.emit("react:action:begin", { type: "transition" });
 		await this.alepha.events.emit("react:transition:begin", {
 			previous: this.alepha.state.get("react.router.state"),
 			state
@@ -921,6 +970,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 				index: 0,
 				path: "/"
 			});
+			await this.alepha.events.emit("react:action:success", { type: "transition" });
 			await this.alepha.events.emit("react:transition:success", { state });
 		} catch (e) {
 			this.log.error("Transition has failed", e);
@@ -930,6 +980,10 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 				index: 0,
 				path: "/"
 			}];
+			await this.alepha.events.emit("react:action:error", {
+				type: "transition",
+				error: e
+			});
 			await this.alepha.events.emit("react:transition:error", {
 				error: e,
 				state
@@ -940,6 +994,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			if (state.layers[i]?.name !== layer.name) this.pageApi.page(layer.name)?.onLeave?.();
 		}
 		this.alepha.state.set("react.router.state", state);
+		await this.alepha.events.emit("react:action:end", { type: "transition" });
 		await this.alepha.events.emit("react:transition:end", { state });
 	}
 	root(state) {
@@ -1135,9 +1190,18 @@ var ReactRouter = class {
 	get pages() {
 		return this.pageApi.getPages();
 	}
+	get concretePages() {
+		return this.pageApi.getConcretePages();
+	}
 	get browser() {
 		if (this.alepha.isBrowser()) return this.alepha.inject(ReactBrowserProvider);
 	}
+	isActive(href, options = {}) {
+		const current = this.state.url.pathname;
+		let isActive = current === href || current === `${href}/` || `${current}/` === href;
+		if (options.startWith && !isActive) isActive = current.startsWith(href);
+		return isActive;
+	}
 	path(name, config = {}) {
 		return this.pageApi.pathname(name, {
 			params: {
@@ -1271,19 +1335,245 @@ const Link = (props) => {
 };
 var Link_default = Link;
 
+//#endregion
+//#region src/hooks/useAction.ts
+/**
+* Hook for handling async actions with automatic error handling and event emission.
+*
+* By default, prevents concurrent executions - if an action is running and you call it again,
+* the second call will be ignored. Use `debounce` option to delay execution instead.
+*
+* Emits lifecycle events:
+* - `react:action:begin` - When action starts
+* - `react:action:success` - When action completes successfully
+* - `react:action:error` - When action throws an error
+* - `react:action:end` - Always emitted at the end
+*
+* @example Basic usage
+* ```tsx
+* const action = useAction({
+*   handler: async (data) => {
+*     await api.save(data);
+*   }
+* }, []);
+*
+* <button onClick={() => action.run(data)} disabled={action.loading}>
+*   Save
+* </button>
+* ```
+*
+* @example With debounce (search input)
+* ```tsx
+* const search = useAction({
+*   handler: async (query: string) => {
+*     await api.search(query);
+*   },
+*   debounce: 300 // Wait 300ms after last call
+* }, []);
+*
+* <input onChange={(e) => search.run(e.target.value)} />
+* ```
+*
+* @example Run on component mount
+* ```tsx
+* const fetchData = useAction({
+*   handler: async () => {
+*     const data = await api.getData();
+*     return data;
+*   },
+*   runOnInit: true // Runs once when component mounts
+* }, []);
+* ```
+*
+* @example Run periodically (polling)
+* ```tsx
+* const pollStatus = useAction({
+*   handler: async () => {
+*     const status = await api.getStatus();
+*     return status;
+*   },
+*   runEvery: 5000 // Run every 5 seconds
+* }, []);
+*
+* // Or with duration tuple
+* const pollStatus = useAction({
+*   handler: async () => {
+*     const status = await api.getStatus();
+*     return status;
+*   },
+*   runEvery: [30, 'seconds'] // Run every 30 seconds
+* }, []);
+* ```
+*
+* @example With AbortController
+* ```tsx
+* const fetch = useAction({
+*   handler: async (url, { signal }) => {
+*     const response = await fetch(url, { signal });
+*     return response.json();
+*   }
+* }, []);
+* // Automatically cancelled on unmount or when new request starts
+* ```
+*
+* @example With error handling
+* ```tsx
+* const deleteAction = useAction({
+*   handler: async (id: string) => {
+*     await api.delete(id);
+*   },
+*   onError: (error) => {
+*     if (error.code === 'NOT_FOUND') {
+*       // Custom error handling
+*     }
+*   }
+* }, []);
+*
+* {deleteAction.error && <div>Error: {deleteAction.error.message}</div>}
+* ```
+*
+* @example Global error handling
+* ```tsx
+* // In your root app setup
+* alepha.events.on("react:action:error", ({ error }) => {
+*   toast.danger(error.message);
+*   Sentry.captureException(error);
+* });
+* ```
+*/
+function useAction(options, deps) {
+	const alepha = useAlepha();
+	const dateTimeProvider = useInject(DateTimeProvider);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState();
+	const isExecutingRef = useRef(false);
+	const debounceTimerRef = useRef(void 0);
+	const abortControllerRef = useRef(void 0);
+	const isMountedRef = useRef(true);
+	const intervalRef = useRef(void 0);
+	useEffect(() => {
+		return () => {
+			isMountedRef.current = false;
+			if (debounceTimerRef.current) {
+				dateTimeProvider.clearTimeout(debounceTimerRef.current);
+				debounceTimerRef.current = void 0;
+			}
+			if (intervalRef.current) {
+				dateTimeProvider.clearInterval(intervalRef.current);
+				intervalRef.current = void 0;
+			}
+			if (abortControllerRef.current) {
+				abortControllerRef.current.abort();
+				abortControllerRef.current = void 0;
+			}
+		};
+	}, []);
+	const executeAction = useCallback(async (...args) => {
+		if (isExecutingRef.current) return;
+		if (abortControllerRef.current) abortControllerRef.current.abort();
+		const abortController = new AbortController();
+		abortControllerRef.current = abortController;
+		isExecutingRef.current = true;
+		setLoading(true);
+		setError(void 0);
+		await alepha.events.emit("react:action:begin", {
+			type: "custom",
+			id: options.id
+		});
+		try {
+			const result = await options.handler(...args, { signal: abortController.signal });
+			if (!isMountedRef.current || abortController.signal.aborted) return;
+			await alepha.events.emit("react:action:success", {
+				type: "custom",
+				id: options.id
+			});
+			if (options.onSuccess) await options.onSuccess(result);
+			return result;
+		} catch (err) {
+			if (err instanceof Error && err.name === "AbortError") return;
+			if (!isMountedRef.current) return;
+			const error$1 = err;
+			setError(error$1);
+			await alepha.events.emit("react:action:error", {
+				type: "custom",
+				id: options.id,
+				error: error$1
+			});
+			if (options.onError) await options.onError(error$1);
+			else throw error$1;
+		} finally {
+			isExecutingRef.current = false;
+			setLoading(false);
+			await alepha.events.emit("react:action:end", {
+				type: "custom",
+				id: options.id
+			});
+			if (abortControllerRef.current === abortController) abortControllerRef.current = void 0;
+		}
+	}, [
+		...deps,
+		options.id,
+		options.onError,
+		options.onSuccess
+	]);
+	const handler = useCallback(async (...args) => {
+		if (options.debounce) {
+			if (debounceTimerRef.current) dateTimeProvider.clearTimeout(debounceTimerRef.current);
+			return new Promise((resolve) => {
+				debounceTimerRef.current = dateTimeProvider.createTimeout(async () => {
+					resolve(await executeAction(...args));
+				}, options.debounce ?? 0);
+			});
+		}
+		return executeAction(...args);
+	}, [executeAction, options.debounce]);
+	const cancel = useCallback(() => {
+		if (debounceTimerRef.current) {
+			dateTimeProvider.clearTimeout(debounceTimerRef.current);
+			debounceTimerRef.current = void 0;
+		}
+		if (abortControllerRef.current) {
+			abortControllerRef.current.abort();
+			abortControllerRef.current = void 0;
+		}
+		if (isMountedRef.current) {
+			isExecutingRef.current = false;
+			setLoading(false);
+		}
+	}, []);
+	useEffect(() => {
+		if (options.runOnInit) handler(...[]);
+	}, []);
+	useEffect(() => {
+		if (!options.runEvery) return;
+		intervalRef.current = dateTimeProvider.createInterval(() => handler(...[]), options.runEvery, true);
+		return () => {
+			if (intervalRef.current) {
+				dateTimeProvider.clearInterval(intervalRef.current);
+				intervalRef.current = void 0;
+			}
+		};
+	}, [handler, options.runEvery]);
+	return {
+		run: handler,
+		loading,
+		error,
+		cancel
+	};
+}
+
 //#endregion
 //#region src/hooks/useActive.ts
 const useActive = (args) => {
 	const router = useRouter();
 	const [isPending, setPending] = useState(false);
-	const current = useRouterState().url.pathname;
+	useRouterState().url.pathname;
 	const options = typeof args === "string" ? { href: args } : {
 		...args,
 		href: args.href
 	};
 	const href = options.href;
-	let isActive = current === href || current === `${href}/` || `${current}/` === href;
-	if (options.startWith && !isActive) isActive = current.startsWith(href);
+	const isActive = router.isActive(href, options);
 	return {
 		isPending,
 		isActive,
@@ -1395,11 +1685,12 @@ const AlephaReact = $module({
 		ReactBrowserRouterProvider,
 		ReactBrowserProvider,
 		ReactRouter,
-		ReactBrowserRendererProvider
+		ReactBrowserRendererProvider,
+		ReactPageService
 	],
-	register: (alepha) => alepha.with(AlephaServer).with(AlephaServerLinks).with(ReactPageProvider).with(ReactBrowserProvider).with(ReactBrowserRouterProvider).with(ReactBrowserRendererProvider).with(ReactRouter)
+	register: (alepha) => alepha.with(AlephaDateTime).with(AlephaServer).with(AlephaServerLinks).with(ReactPageProvider).with(ReactBrowserProvider).with(ReactBrowserRouterProvider).with(ReactBrowserRendererProvider).with(ReactRouter)
 });
 
 //#endregion
-export { $page, AlephaContext, AlephaReact, ClientOnly_default as ClientOnly, ErrorBoundary_default as ErrorBoundary, ErrorViewer_default as ErrorViewer, Link_default as Link, NestedView_default as NestedView, NotFoundPage as NotFound, PageDescriptor, ReactBrowserProvider, ReactBrowserRouterProvider, ReactPageProvider, ReactRouter, Redirection, RouterLayerContext, isPageRoute, ssrSchemaLoading, useActive, useAlepha, useClient, useInject, useQueryParams, useRouter, useRouterEvents, useRouterState, useSchema, useStore };
+export { $page, AlephaContext, AlephaReact, ClientOnly_default as ClientOnly, ErrorBoundary_default as ErrorBoundary, ErrorViewer_default as ErrorViewer, Link_default as Link, NestedView_default as NestedView, NotFoundPage as NotFound, PageDescriptor, ReactBrowserProvider, ReactBrowserRouterProvider, ReactPageProvider, ReactRouter, Redirection, RouterLayerContext, isPageRoute, ssrSchemaLoading, useAction, useActive, useAlepha, useClient, useEvents, useInject, useQueryParams, useRouter, useRouterState, useSchema, useStore };
 //# sourceMappingURL=index.browser.js.map