@alepha/react 0.9.5 → 0.10.0

package/README.md

@@ -34,14 +34,96 @@ run(alepha);
 
 ### Descriptors
 
-Descriptors are functions that define and configure various aspects of your application. They follow the convention of starting with `$` and return configured descriptor instances.
+Descriptors are functions that define and configure various aspects of your application. They follow the convention of starting with ` $ ` and return configured descriptor instances.
 
-For more details, see the [Descriptors documentation](https://feunard.github.io/alepha/docs/descriptors).
+For more details, see the [Descriptors documentation](/docs/descriptors).
 
 #### $page()
 
 Main descriptor for defining a React route in the application.
 
+The $page descriptor is the core building block for creating type-safe, SSR-enabled React routes.
+It provides a declarative way to define pages with powerful features:
+
+**Routing & Navigation**
+- URL pattern matching with parameters (e.g., `/users/:id`)
+- Nested routing with parent-child relationships
+- Type-safe URL parameter and query string validation
+
+**Data Loading**
+- Server-side data fetching with the `resolve` function
+- Automatic serialization and hydration for SSR
+- Access to request context, URL params, and parent data
+
+**Component Loading**
+- Direct component rendering or lazy loading for code splitting
+- Client-only rendering when browser APIs are needed
+- Automatic fallback handling during hydration
+
+**Performance Optimization**
+- Static generation for pre-rendered pages at build time
+- Server-side caching with configurable TTL and providers
+- Code splitting through lazy component loading
+
+**Error Handling**
+- Custom error handlers with support for redirects
+- Hierarchical error handling (child → parent)
+- HTTP status code handling (404, 401, etc.)
+
+**Page Animations**
+- CSS-based enter/exit animations
+- Dynamic animations based on page state
+- Custom timing and easing functions
+
+**Lifecycle Management**
+- Server response hooks for headers and status codes
+- Page leave handlers for cleanup (browser only)
+- Permission-based access control
+
+```typescript
+const userProfile = $page({
+  path: "/users/:id",
+  schema: {
+    params: t.object({ id: t.int() }),
+    query: t.object({ tab: t.optional(t.string()) })
+  },
+  resolve: async ({ params }) => {
+    const user = await userApi.getUser(params.id);
+    return { user };
+  },
+  lazy: () => import("./UserProfile.tsx")
+});
+```
+
+```typescript
+const projectSection = $page({
+  path: "/projects/:id",
+  children: () => [projectBoard, projectSettings],
+  resolve: async ({ params }) => {
+    const project = await projectApi.get(params.id);
+    return { project };
+  },
+  errorHandler: (error) => {
+    if (HttpError.is(error, 404)) {
+      return <ProjectNotFound />;
+    }
+  }
+});
+```
+
+```typescript
+const blogPost = $page({
+  path: "/blog/:slug",
+  static: {
+    entries: posts.map(p => ({ params: { slug: p.slug } }))
+  },
+  resolve: async ({ params }) => {
+    const post = await loadPost(params.slug);
+    return { post };
+  }
+});
+```
+
 ### Hooks
 
 Hooks provide a way to tap into various lifecycle events and extend functionality. They follow the convention of starting with `use` and return configured hook instances.
@@ -56,7 +138,7 @@ 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
+- alepha.events.emit() for event handling
 etc...
 
 #### useClient()

package/dist/index.browser.js

@@ -1,4 +1,4 @@
-import { $env, $hook, $inject, $module, Alepha, AlephaError, Descriptor, KIND, TypeGuard, createDescriptor, t } from "@alepha/core";
+import { $env, $hook, $inject, $module, Alepha, AlephaError, Descriptor, KIND, createDescriptor, t } from "@alepha/core";
 import { AlephaServer, HttpClient } from "@alepha/server";
 import { AlephaServerLinks, LinkProvider } from "@alepha/server-links";
 import { DateTimeProvider } from "@alepha/datetime";
@@ -11,6 +11,91 @@ import { createRoot, hydrateRoot } from "react-dom/client";
 //#region src/descriptors/$page.ts
 /**
 * Main descriptor for defining a React route in the application.
+*
+* The $page descriptor is the core building block for creating type-safe, SSR-enabled React routes.
+* It provides a declarative way to define pages with powerful features:
+*
+* **Routing & Navigation**
+* - URL pattern matching with parameters (e.g., `/users/:id`)
+* - Nested routing with parent-child relationships
+* - Type-safe URL parameter and query string validation
+*
+* **Data Loading**
+* - Server-side data fetching with the `resolve` function
+* - Automatic serialization and hydration for SSR
+* - Access to request context, URL params, and parent data
+*
+* **Component Loading**
+* - Direct component rendering or lazy loading for code splitting
+* - Client-only rendering when browser APIs are needed
+* - Automatic fallback handling during hydration
+*
+* **Performance Optimization**
+* - Static generation for pre-rendered pages at build time
+* - Server-side caching with configurable TTL and providers
+* - Code splitting through lazy component loading
+*
+* **Error Handling**
+* - Custom error handlers with support for redirects
+* - Hierarchical error handling (child → parent)
+* - HTTP status code handling (404, 401, etc.)
+*
+* **Page Animations**
+* - CSS-based enter/exit animations
+* - Dynamic animations based on page state
+* - Custom timing and easing functions
+*
+* **Lifecycle Management**
+* - Server response hooks for headers and status codes
+* - Page leave handlers for cleanup (browser only)
+* - Permission-based access control
+*
+* @example Simple page with data fetching
+* ```typescript
+* const userProfile = $page({
+*   path: "/users/:id",
+*   schema: {
+*     params: t.object({ id: t.int() }),
+*     query: t.object({ tab: t.optional(t.string()) })
+*   },
+*   resolve: async ({ params }) => {
+*     const user = await userApi.getUser(params.id);
+*     return { user };
+*   },
+*   lazy: () => import("./UserProfile.tsx")
+* });
+* ```
+*
+* @example Nested routing with error handling
+* ```typescript
+* const projectSection = $page({
+*   path: "/projects/:id",
+*   children: () => [projectBoard, projectSettings],
+*   resolve: async ({ params }) => {
+*     const project = await projectApi.get(params.id);
+*     return { project };
+*   },
+*   errorHandler: (error) => {
+*     if (HttpError.is(error, 404)) {
+*       return <ProjectNotFound />;
+*     }
+*   }
+* });
+* ```
+*
+* @example Static generation with caching
+* ```typescript
+* const blogPost = $page({
+*   path: "/blog/:slug",
+*   static: {
+*     entries: posts.map(p => ({ params: { slug: p.slug } }))
+*   },
+*   resolve: async ({ params }) => {
+*     const post = await loadPost(params.slug);
+*     return { post };
+*   }
+* });
+* ```
 */
 const $page = (options) => {
 	return createDescriptor(PageDescriptor, options);
@@ -269,7 +354,7 @@ const AlephaContext = createContext(void 0);
 *
 * - alepha.state() for state management
 * - alepha.inject() for dependency injection
-* - alepha.emit() for event handling
+* - alepha.events.emit() for event handling
 * etc...
 */
 const useAlepha = () => {
@@ -296,10 +381,10 @@ const useRouterEvents = (opts = {}, deps = []) => {
 		const onEnd = opts.onEnd;
 		const onError = opts.onError;
 		const onSuccess = opts.onSuccess;
-		if (onBegin) subs.push(alepha.on("react:transition:begin", cb(onBegin)));
-		if (onEnd) subs.push(alepha.on("react:transition:end", cb(onEnd)));
-		if (onError) subs.push(alepha.on("react:transition:error", cb(onError)));
-		if (onSuccess) subs.push(alepha.on("react:transition:success", cb(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)));
 		return () => {
 			for (const sub of subs) sub();
 		};
@@ -314,17 +399,17 @@ const useRouterEvents = (opts = {}, deps = []) => {
 const useStore = (key, defaultValue) => {
 	const alepha = useAlepha();
 	useMemo(() => {
-		if (defaultValue != null && alepha.state(key) == null) alepha.state(key, defaultValue);
+		if (defaultValue != null && alepha.state.get(key) == null) alepha.state.set(key, defaultValue);
 	}, [defaultValue]);
-	const [state, setState] = useState(alepha.state(key));
+	const [state, setState] = useState(alepha.state.get(key));
 	useEffect(() => {
 		if (!alepha.isBrowser()) return;
-		return alepha.on("state:mutate", (ev) => {
+		return alepha.events.on("state:mutate", (ev) => {
 			if (ev.key === key) setState(ev.value);
 		});
 	}, []);
 	return [state, (value) => {
-		alepha.state(key, value);
+		alepha.state.set(key, value);
 	}];
 };
 
@@ -533,8 +618,8 @@ var ReactPageProvider = class {
 		return root;
 	}
 	convertStringObjectToObject = (schema, value) => {
-		if (TypeGuard.IsObject(schema) && typeof value === "object") {
-			for (const key in schema.properties) if (TypeGuard.IsObject(schema.properties[key]) && typeof value[key] === "string") try {
+		if (t.schema.isObject(schema) && typeof value === "object") {
+			for (const key in schema.properties) if (t.schema.isObject(schema.properties[key]) && typeof value[key] === "string") try {
 				value[key] = this.alepha.parse(schema.properties[key], decodeURIComponent(value[key]));
 			} catch (e) {}
 		}
@@ -831,8 +916,8 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			meta
 		};
 		const state = entry;
-		await this.alepha.emit("react:transition:begin", {
-			previous: this.alepha.state("react.router.state"),
+		await this.alepha.events.emit("react:transition:begin", {
+			previous: this.alepha.state.get("react.router.state"),
 			state
 		});
 		try {
@@ -851,7 +936,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 				index: 0,
 				path: "/"
 			});
-			await this.alepha.emit("react:transition:success", { state });
+			await this.alepha.events.emit("react:transition:success", { state });
 		} catch (e) {
 			this.log.error("Transition has failed", e);
 			state.layers = [{
@@ -860,7 +945,7 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 				index: 0,
 				path: "/"
 			}];
-			await this.alepha.emit("react:transition:error", {
+			await this.alepha.events.emit("react:transition:error", {
 				error: e,
 				state
 			});
@@ -869,8 +954,8 @@ var ReactBrowserRouterProvider = class extends RouterProvider {
 			const layer = previous[i];
 			if (state.layers[i]?.name !== layer.name) this.pageApi.page(layer.name)?.onLeave?.();
 		}
-		this.alepha.state("react.router.state", state);
-		await this.alepha.emit("react:transition:end", { state });
+		this.alepha.state.set("react.router.state", state);
+		await this.alepha.events.emit("react:transition:end", { state });
 	}
 	root(state) {
 		return this.pageApi.root(state);
@@ -898,7 +983,7 @@ var ReactBrowserProvider = class {
 	}
 	transitioning;
 	get state() {
-		return this.alepha.state("react.router.state");
+		return this.alepha.state.get("react.router.state");
 	}
 	/**
 	* Accessor for Document DOM API.
@@ -1014,11 +1099,11 @@ var ReactBrowserProvider = class {
 			const hydration = this.getHydrationState();
 			const previous = hydration?.layers ?? [];
 			if (hydration) {
-				for (const [key, value] of Object.entries(hydration)) if (key !== "layers") this.alepha.state(key, value);
+				for (const [key, value] of Object.entries(hydration)) if (key !== "layers") this.alepha.state.set(key, value);
 			}
 			await this.render({ previous });
 			const element = this.router.root(this.state);
-			await this.alepha.emit("react:browser:render", {
+			await this.alepha.events.emit("react:browser:render", {
 				element,
 				root: this.getRootElement(),
 				hydration,
@@ -1059,7 +1144,7 @@ var ReactRouter = class {
 	alepha = $inject(Alepha);
 	pageApi = $inject(ReactPageProvider);
 	get state() {
-		return this.alepha.state("react.router.state");
+		return this.alepha.state.get("react.router.state");
 	}
 	get pages() {
 		return this.pageApi.getPages();
@@ -1245,7 +1330,7 @@ const useQueryParams = (schema, options = {}) => {
 	const key = options.key ?? "q";
 	const router = useRouter();
 	const querystring = router.query[key];
-	const [queryParams, setQueryParams] = useState(decode(alepha, schema, router.query[key]));
+	const [queryParams = {}, setQueryParams] = useState(decode(alepha, schema, router.query[key]));
 	useEffect(() => {
 		setQueryParams(decode(alepha, schema, querystring));
 	}, [querystring]);
@@ -1265,8 +1350,8 @@ const encode = (alepha, schema, data) => {
 const decode = (alepha, schema, data) => {
 	try {
 		return alepha.parse(schema, JSON.parse(atob(decodeURIComponent(data))));
-	} catch (_error) {
-		return {};
+	} catch {
+		return;
 	}
 };