@alepha/react 0.11.3 → 0.11.5

package/src/hooks/useEvents.ts

@@ -0,0 +1,51 @@
+import type { Async, Hook, Hooks } from "@alepha/core";
+import { type DependencyList, useEffect } from "react";
+import { useAlepha } from "./useAlepha.ts";
+
+/**
+ * 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);
+ *       },
+ *     },
+ *   },
+ *   [],
+ * );
+ * ```
+ */
+export const useEvents = (opts: UseEvents, deps: DependencyList) => {
+  const alepha = useAlepha();
+
+  useEffect(() => {
+    if (!alepha.isBrowser()) {
+      return;
+    }
+
+    const subs: Function[] = [];
+    for (const [name, hook] of Object.entries(opts)) {
+      subs.push(alepha.events.on(name as any, hook as any));
+    }
+
+    return () => {
+      for (const clear of subs) {
+        clear();
+      }
+    };
+  }, deps);
+};
+
+type UseEvents = {
+  [T in keyof Hooks]?: Hook<T> | ((payload: Hooks[T]) => Async<void>);
+};

package/src/index.browser.ts

@@ -1,4 +1,5 @@
 import { $module } from "@alepha/core";
+import { AlephaDateTime } from "@alepha/datetime";
 import { AlephaServer } from "@alepha/server";
 import { AlephaServerLinks } from "@alepha/server-links";
 import { $page } from "./descriptors/$page.ts";
@@ -6,6 +7,7 @@ import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
 import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
 import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
 import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -26,9 +28,11 @@ export const AlephaReact = $module({
     ReactBrowserProvider,
     ReactRouter,
     ReactBrowserRendererProvider,
+    ReactPageService,
   ],
   register: (alepha) =>
     alepha
+      .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerLinks)
       .with(ReactPageProvider)

package/src/index.shared.ts

@@ -8,13 +8,14 @@ export * from "./contexts/AlephaContext.ts";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./descriptors/$page.ts";
 export * from "./errors/Redirection.ts";
+export * from "./hooks/useAction.ts";
 export * from "./hooks/useActive.ts";
 export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
+export * from "./hooks/useEvents.ts";
 export * from "./hooks/useInject.ts";
 export * from "./hooks/useQueryParams.ts";
 export * from "./hooks/useRouter.ts";
-export * from "./hooks/useRouterEvents.ts";
 export * from "./hooks/useRouterState.ts";
 export * from "./hooks/useSchema.ts";
 export * from "./hooks/useStore.ts";

package/src/index.ts

@@ -1,4 +1,5 @@
 import { $module } from "@alepha/core";
+import { AlephaDateTime } from "@alepha/datetime";
 import { AlephaServer, type ServerRequest } from "@alepha/server";
 import { AlephaServerCache } from "@alepha/server-cache";
 import { AlephaServerLinks } from "@alepha/server-links";
@@ -10,6 +11,8 @@ import {
   type ReactRouterState,
 } from "./providers/ReactPageProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
+import { ReactPageServerService } from "./services/ReactPageServerService.ts";
+import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -27,34 +30,92 @@ declare module "@alepha/core" {
   }
 
   interface Hooks {
+    /**
+     * Fires when the React application is starting to be rendered on the server.
+     */
     "react:server:render:begin": {
       request?: ServerRequest;
       state: ReactRouterState;
     };
+    /**
+     * Fires when the React application has been rendered on the server.
+     */
     "react:server:render:end": {
       request?: ServerRequest;
       state: ReactRouterState;
       html: string;
     };
     // -----------------------------------------------------------------------------------------------------------------
+    /**
+     * Fires when the React application is being rendered on the browser.
+     */
     "react:browser:render": {
       root: HTMLElement;
       element: ReactNode;
       state: ReactRouterState;
       hydration?: ReactHydrationState;
     };
+    // -----------------------------------------------------------------------------------------------------------------
+    // TOP LEVEL: All user actions (forms, transitions, custom actions)
+    /**
+     * Fires when a user action is starting.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:begin": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has succeeded.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:success": {
+      type: string;
+      id?: string;
+    };
+    /**
+     * Fires when a user action has failed.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:error": {
+      type: string;
+      id?: string;
+      error: Error;
+    };
+    /**
+     * Fires when a user action has completed, regardless of success or failure.
+     * Action can be a form submission, a route transition, or a custom action.
+     */
+    "react:action:end": {
+      type: string;
+      id?: string;
+    };
+    // -----------------------------------------------------------------------------------------------------------------
+    // SPECIFIC: Route transitions
+    /**
+     * Fires when a route transition is starting.
+     */
     "react:transition:begin": {
       previous: ReactRouterState;
       state: ReactRouterState;
       animation?: PageAnimation;
     };
+    /**
+     * Fires when a route transition has succeeded.
+     */
     "react:transition:success": {
       state: ReactRouterState;
     };
+    /**
+     * Fires when a route transition has failed.
+     */
     "react:transition:error": {
       state: ReactRouterState;
       error: Error;
     };
+    /**
+     * Fires when a route transition has completed, regardless of success or failure.
+     */
     "react:transition:end": {
       state: ReactRouterState;
     };
@@ -76,12 +137,23 @@ declare module "@alepha/core" {
 export const AlephaReact = $module({
   name: "alepha.react",
   descriptors: [$page],
-  services: [ReactServerProvider, ReactPageProvider, ReactRouter],
+  services: [
+    ReactServerProvider,
+    ReactPageProvider,
+    ReactRouter,
+    ReactPageService,
+    ReactPageServerService,
+  ],
   register: (alepha) =>
     alepha
+      .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerCache)
       .with(AlephaServerLinks)
+      .with({
+        provide: ReactPageService,
+        use: ReactPageServerService,
+      })
       .with(ReactServerProvider)
       .with(ReactPageProvider)
       .with(ReactRouter),

package/src/providers/ReactBrowserRouterProvider.ts

@@ -58,6 +58,10 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 
     const state = entry as ReactRouterState;
 
+    // Emit both action and transition events
+    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,
@@ -96,6 +100,9 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
         });
       }
 
+      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);
@@ -108,6 +115,10 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
         },
       ];
 
+      await this.alepha.events.emit("react:action:error", {
+        type: "transition",
+        error: e as Error,
+      });
       await this.alepha.events.emit("react:transition:error", {
         error: e as Error,
         state,
@@ -126,6 +137,9 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
 
     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,
     });

package/src/providers/ReactPageProvider.ts

@@ -42,6 +42,39 @@ export class ReactPageProvider {
     return this.pages;
   }
 
+  public getConcretePages(): PageRoute[] {
+    const pages: PageRoute[] = [];
+    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 as Record<string, string>;
+              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;
+  }
+
   public page(name: string): PageRoute {
     for (const page of this.pages) {
       if (page.name === name) {
@@ -49,7 +82,7 @@ export class ReactPageProvider {
       }
     }
 
-    throw new Error(`Page ${name} not found`);
+    throw new AlephaError(`Page '${name}' not found`);
   }
 
   public pathname(

package/src/providers/ReactServerProvider.ts

@@ -73,7 +73,7 @@ export class ReactServerProvider implements Configurable {
   protected readonly serverRouterProvider = $inject(ServerRouterProvider);
   protected readonly serverTimingProvider = $inject(ServerTimingProvider);
 
-  protected readonly ROOT_DIV_REGEX = new RegExp(
+  public readonly ROOT_DIV_REGEX = new RegExp(
     `<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
     "is",
   );
@@ -94,23 +94,6 @@ export class ReactServerProvider implements Configurable {
 
       this.alepha.state.set("react.server.ssr", ssrEnabled);
 
-      for (const page of pages) {
-        page.render = this.createRenderFunction(page.name);
-        page.fetch = async (options) => {
-          const response = await fetch(
-            `${this.serverProvider.hostname}/${page.pathname(options)}`,
-          );
-          const html = await response.text();
-          if (options?.html) return { html, response };
-          // take only text inside the root div
-          const match = html.match(this.ROOT_DIV_REGEX);
-          if (match) {
-            return { html: match[3], response };
-          }
-          throw new AlephaError("Invalid HTML response");
-        };
-      }
-
       // development mode
       if (this.alepha.isViteDev()) {
         await this.configureVite(ssrEnabled);
@@ -248,66 +231,63 @@ export class ReactServerProvider implements Configurable {
   /**
    * For testing purposes, creates a render function that can be used.
    */
-  protected createRenderFunction(name: string, withIndex = false) {
-    return async (
-      options: PageDescriptorRenderOptions = {},
-    ): Promise<PageDescriptorRenderResult> => {
-      const page = this.pageApi.page(name);
-      const url = new URL(this.pageApi.url(name, options));
-
-      const entry: Partial<ReactRouterState> = {
-        url,
-        params: options.params ?? {},
-        query: options.query ?? {},
-        onError: () => null,
-        layers: [],
-        meta: {},
-      };
-
-      const state = entry as ReactRouterState;
-
-      this.log.trace("Rendering", {
-        url,
-      });
-
-      await this.alepha.events.emit("react:server:render:begin", {
-        state,
-      });
-
-      const { redirect } = await this.pageApi.createLayers(
-        page,
-        state as ReactRouterState,
-      );
+  public async render(
+    name: string,
+    options: PageDescriptorRenderOptions = {},
+  ): Promise<PageDescriptorRenderResult> {
+    const page = this.pageApi.page(name);
+    const url = new URL(this.pageApi.url(name, options));
+    const entry: Partial<ReactRouterState> = {
+      url,
+      params: options.params ?? {},
+      query: options.query ?? {},
+      onError: () => null,
+      layers: [],
+      meta: {},
+    };
+    const state = entry as ReactRouterState;
 
-      if (redirect) {
-        return { state, html: "", redirect };
-      }
+    this.log.trace("Rendering", {
+      url,
+    });
 
-      if (!withIndex && !options.html) {
-        this.alepha.state.set("react.router.state", state);
+    await this.alepha.events.emit("react:server:render:begin", {
+      state,
+    });
 
-        return {
-          state,
-          html: renderToString(this.pageApi.root(state)),
-        };
-      }
+    const { redirect } = await this.pageApi.createLayers(
+      page,
+      state as ReactRouterState,
+    );
 
-      const template = this.template ?? "";
-      const html = this.renderToHtml(template, state, options.hydration);
+    if (redirect) {
+      return { state, html: "", redirect };
+    }
 
-      if (html instanceof Redirection) {
-        return { state, html: "", redirect };
-      }
+    if (!options.html) {
+      this.alepha.state.set("react.router.state", state);
 
-      const result = {
+      return {
         state,
-        html,
+        html: renderToString(this.pageApi.root(state)),
       };
+    }
 
-      await this.alepha.events.emit("react:server:render:end", result);
+    const template = this.template ?? "";
+    const html = this.renderToHtml(template, state, options.hydration);
 
-      return result;
+    if (html instanceof Redirection) {
+      return { state, html: "", redirect };
+    }
+
+    const result = {
+      state,
+      html,
     };
+
+    await this.alepha.events.emit("react:server:render:end", result);
+
+    return result;
   }
 
   protected createHandler(
@@ -318,7 +298,7 @@ export class ReactServerProvider implements Configurable {
       const { url, reply, query, params } = serverRequest;
       const template = await templateLoader();
       if (!template) {
-        throw new AlephaError("Template not found");
+        throw new AlephaError("Missing template for SSR rendering");
       }
 
       this.log.trace("Rendering page", {

package/src/services/ReactPageServerService.ts

@@ -0,0 +1,43 @@
+import { $inject, AlephaError } from "@alepha/core";
+import { ServerProvider } from "@alepha/server";
+import type {
+  PageDescriptorRenderOptions,
+  PageDescriptorRenderResult,
+} from "../descriptors/$page.ts";
+import { ReactServerProvider } from "../providers/ReactServerProvider.ts";
+import { ReactPageService } from "./ReactPageService.ts";
+
+export class ReactPageServerService extends ReactPageService {
+  protected readonly reactServerProvider = $inject(ReactServerProvider);
+  protected readonly serverProvider = $inject(ServerProvider);
+
+  public async render(
+    name: string,
+    options: PageDescriptorRenderOptions = {},
+  ): Promise<PageDescriptorRenderResult> {
+    return this.reactServerProvider.render(name, options);
+  }
+
+  public async fetch(
+    pathname: string,
+    options: PageDescriptorRenderOptions = {},
+  ): Promise<{
+    html: string;
+    response: Response;
+  }> {
+    const response = await fetch(`${this.serverProvider.hostname}/${pathname}`);
+
+    const html = await response.text();
+    if (options?.html) {
+      return { html, response };
+    }
+
+    // take only text inside the root div
+    const match = html.match(this.reactServerProvider.ROOT_DIV_REGEX);
+    if (match) {
+      return { html: match[3], response };
+    }
+
+    throw new AlephaError("Invalid HTML response");
+  }
+}

package/src/services/ReactPageService.ts

@@ -0,0 +1,24 @@
+import { AlephaError } from "@alepha/core";
+import type {
+  PageDescriptorRenderOptions,
+  PageDescriptorRenderResult,
+} from "../descriptors/$page.ts";
+
+export class ReactPageService {
+  public fetch(
+    pathname: string,
+    options: PageDescriptorRenderOptions = {},
+  ): Promise<{
+    html: string;
+    response: Response;
+  }> {
+    throw new AlephaError("Fetch is not available for this environment.");
+  }
+
+  public render(
+    name: string,
+    options: PageDescriptorRenderOptions = {},
+  ): Promise<PageDescriptorRenderResult> {
+    throw new AlephaError("Render is not available for this environment.");
+  }
+}

package/src/services/ReactRouter.ts

@@ -22,6 +22,10 @@ export class ReactRouter<T extends object> {
     return this.pageApi.getPages();
   }
 
+  public get concretePages() {
+    return this.pageApi.getConcretePages();
+  }
+
   public get browser(): ReactBrowserProvider | undefined {
     if (this.alepha.isBrowser()) {
       return this.alepha.inject(ReactBrowserProvider);
@@ -30,6 +34,23 @@ export class ReactRouter<T extends object> {
     return undefined;
   }
 
+  public isActive(
+    href: string,
+    options: {
+      startWith?: boolean;
+    } = {},
+  ): boolean {
+    const current = this.state.url.pathname;
+    let isActive =
+      current === href || current === `${href}/` || `${current}/` === href;
+
+    if (options.startWith && !isActive) {
+      isActive = current.startsWith(href);
+    }
+
+    return isActive;
+  }
+
   public path(
     name: keyof VirtualRouter<T>,
     config: {

package/src/hooks/useRouterEvents.ts

@@ -1,66 +0,0 @@
-import type { Hooks } from "@alepha/core";
-import { useEffect } from "react";
-import { useAlepha } from "./useAlepha.ts";
-
-type Hook<T extends keyof Hooks> =
-  | ((ev: Hooks[T]) => void)
-  | {
-      priority?: "first" | "last";
-      callback: (ev: Hooks[T]) => void;
-    };
-
-/**
- * Subscribe to various router events.
- */
-export const useRouterEvents = (
-  opts: {
-    onBegin?: Hook<"react:transition:begin">;
-    onError?: Hook<"react:transition:error">;
-    onEnd?: Hook<"react:transition:end">;
-    onSuccess?: Hook<"react:transition:success">;
-  } = {},
-  deps: any[] = [],
-) => {
-  const alepha = useAlepha();
-
-  useEffect(() => {
-    if (!alepha.isBrowser()) {
-      return;
-    }
-
-    const cb = <T extends keyof Hooks>(callback: Hook<T>) => {
-      if (typeof callback === "function") {
-        return { callback };
-      }
-      return callback;
-    };
-
-    const subs: Function[] = [];
-    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)));
-    }
-
-    return () => {
-      for (const sub of subs) {
-        sub();
-      }
-    };
-  }, deps);
-};