@alepha/react 0.14.0 → 0.14.2

package/src/{core → router}/hooks/useRouter.ts

@@ -1,5 +1,5 @@
 import { ReactRouter } from "../services/ReactRouter.ts";
-import { useInject } from "./useInject.ts";
+import { useInject } from "@alepha/react";
 
 /**
  * Use this hook to access the React Router instance.

package/src/{core → router}/hooks/useRouterState.ts

@@ -1,6 +1,6 @@
 import { AlephaError } from "alepha";
 import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
-import { useStore } from "./useStore.ts";
+import { useStore } from "@alepha/react";
 
 export const useRouterState = (): ReactRouterState => {
   const [state] = useStore("alepha.react.router.state");

package/src/{core → router}/index.browser.ts

@@ -1,27 +1,27 @@
 import { $module } from "alepha";
-import { AlephaDateTime } from "alepha/datetime";
-import { AlephaServer } from "alepha/server";
-import { AlephaServerLinks } from "alepha/server/links";
 import { $page } from "./primitives/$page.ts";
-import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
+import { ReactRouter } from "./services/ReactRouter.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";
+import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
+import { AlephaDateTime } from "alepha/datetime";
+import { AlephaServer } from "alepha/server";
+import { AlephaServerLinks } from "alepha/server/links";
+import { AlephaReact } from "@alepha/react";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./index.shared.ts";
-export * from "./index.shared-router.ts";
-export * from "./providers/ReactBrowserProvider.ts";
-export * from "./providers/ReactBrowserRouterProvider.ts";
-export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/ReactBrowserProvider.ts"
+export * from "./providers/ReactBrowserRouterProvider.ts"
+export * from "./providers/ReactBrowserRendererProvider.ts"
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export const AlephaReact = $module({
-  name: "alepha.react",
+export const AlephaReactRouter = $module({
+  name: "alepha.react.router",
   primitives: [$page],
   services: [
     ReactPageProvider,
@@ -33,6 +33,7 @@ export const AlephaReact = $module({
   ],
   register: (alepha) =>
     alepha
+      .with(AlephaReact)
       .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerLinks)
@@ -42,3 +43,4 @@ export const AlephaReact = $module({
       .with(ReactBrowserRendererProvider)
       .with(ReactRouter),
 });
+

package/src/{core/index.shared-router.ts → router/index.shared.ts}

@@ -1,9 +1,11 @@
-export { default as ClientOnly } from "./components/ClientOnly.tsx";
-export { default as ErrorBoundary } from "./components/ErrorBoundary.tsx";
 export { default as ErrorViewer } from "./components/ErrorViewer.tsx";
+export type * from "./components/ErrorViewer.tsx";
 export { default as Link, type LinkProps } from "./components/Link.tsx";
+export type *  from "./components/Link.tsx";
 export { default as NestedView } from "./components/NestedView.tsx";
+export type *  from "./components/NestedView.tsx";
 export { default as NotFound } from "./components/NotFound.tsx";
+export type * from "./components/NotFound.tsx";
 export * from "./contexts/RouterLayerContext.ts";
 export * from "./primitives/$page.ts";
 export * from "./errors/Redirection.ts";
@@ -11,5 +13,6 @@ export * from "./hooks/useActive.ts";
 export * from "./hooks/useQueryParams.ts";
 export * from "./hooks/useRouter.ts";
 export * from "./hooks/useRouterState.ts";
-export * from "./hooks/useSchema.ts";
 export * from "./services/ReactRouter.ts";
+export * from "./services/ReactPageService.ts"
+export * from "./providers/ReactPageProvider.ts";

package/src/router/index.ts

@@ -0,0 +1,125 @@
+import { AlephaReact } from "@alepha/react";
+import { $module } from "alepha";
+import { $page, type PageAnimation } from "./primitives/$page.ts";
+import { ReactRouter } from "./services/ReactRouter.ts";
+import { ReactPageProvider, type ReactRouterState } from "./providers/ReactPageProvider.ts";
+import { AlephaServer, type ServerRequest } from "alepha/server";
+import type { ReactNode } from "react";
+import type { ReactHydrationState } from "./providers/ReactBrowserProvider.ts";
+import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
+import { ReactPageServerService } from "./services/ReactPageServerService.ts";
+import { AlephaServerCache } from "alepha/server/cache";
+import { AlephaServerLinks } from "alepha/server/links";
+import { ReactPageService } from "./services/ReactPageService.ts";
+import { AlephaDateTime } from "alepha/datetime";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./index.shared.ts";
+export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/ReactBrowserProvider.ts";
+export * from "./providers/ReactServerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  interface State {
+    "alepha.react.router.state"?: ReactRouterState;
+  }
+
+  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;
+    };
+    // -----------------------------------------------------------------------------------------------------------------
+    // 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;
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Provides declarative routing with the `$page` primitive for building type-safe React routes.
+ *
+ * This module enables:
+ * - URL pattern matching with parameters (e.g., `/users/:id`)
+ * - Nested routing with parent-child relationships
+ * - Type-safe URL parameter and query string validation
+ * - Server-side data fetching with the `resolve` function
+ * - Lazy loading and code splitting
+ * - Page animations and error handling
+ *
+ * @see {@link $page}
+ * @module alepha.react.router
+ */
+export const AlephaReactRouter = $module({
+  name: "alepha.react.router",
+  primitives: [$page],
+  services: [
+    ReactPageProvider,
+    ReactPageService,
+    ReactRouter, ReactServerProvider, ReactPageServerService],
+  register: (alepha) =>
+    alepha
+      .with(AlephaReact)
+      .with(AlephaDateTime)
+      .with(AlephaServer)
+      .with(AlephaServerCache)
+      .with(AlephaServerLinks)
+      .with({
+        provide: ReactPageService,
+        use: ReactPageServerService,
+      })
+      .with(ReactServerProvider)
+      .with(ReactPageProvider)
+      .with(ReactRouter),
+});

package/src/{core → router}/primitives/$page.ts

@@ -10,10 +10,10 @@ import {
 import type { ServerRequest } from "alepha/server";
 import type { ServerRouteCache } from "alepha/server/cache";
 import type { FC, ReactNode } from "react";
-import type { ClientOnlyProps } from "../components/ClientOnly.tsx";
 import type { Redirection } from "../errors/Redirection.ts";
 import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { ReactPageService } from "../services/ReactPageService.ts";
+import type { ClientOnlyProps } from "@alepha/react";
 
 /**
  * Main primitive for defining a React route in the application.

package/src/{core → router}/providers/ReactBrowserProvider.ts

@@ -18,6 +18,9 @@ import type {
   ReactRouterState,
   TransitionOptions,
 } from "./ReactPageProvider.ts";
+import type { RouterGoOptions } from "../services/ReactRouter.ts";
+
+export type { RouterGoOptions } from "../services/ReactRouter.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -297,19 +300,6 @@ export class ReactBrowserProvider {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface RouterGoOptions {
-  replace?: boolean;
-  match?: TransitionOptions;
-  params?: Record<string, string>;
-  query?: Record<string, string>;
-  meta?: Record<string, any>;
-
-  /**
-   * Recreate the whole page, ignoring the current state.
-   */
-  force?: boolean;
-}
-
 export type ReactHydrationState = {
   layers?: Array<PreviousLayerData>;
 } & {

package/src/{core → router}/providers/ReactBrowserRendererProvider.ts

@@ -2,6 +2,9 @@ import { $hook } from "alepha";
 import { $logger } from "alepha/logger";
 import { createRoot, hydrateRoot, type Root } from "react-dom/client";
 
+/**
+ * Browser specific React renderer (react-dom/client interface)
+ */
 export class ReactBrowserRendererProvider {
   protected readonly log = $logger();
   protected root?: Root;

package/src/{core → router}/providers/ReactBrowserRouterProvider.ts

@@ -16,6 +16,9 @@ export interface BrowserRoute extends Route {
   page: PageRoute;
 }
 
+/**
+ * Implementation of AlephaRouter for React in browser environment.
+ */
 export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
   protected readonly log = $logger();
   protected readonly alepha = $inject(Alepha);

package/src/{core → router}/providers/ReactPageProvider.ts

@@ -10,19 +10,18 @@ import {
 } from "alepha";
 import { $logger } from "alepha/logger";
 import { createElement, type ReactNode, StrictMode } from "react";
-import ClientOnly from "../components/ClientOnly.tsx";
+import { AlephaContext, ClientOnly } from "@alepha/react";
 import ErrorViewer from "../components/ErrorViewer.tsx";
 import NestedView from "../components/NestedView.tsx";
 import NotFoundPage from "../components/NotFound.tsx";
-import { AlephaContext } from "../contexts/AlephaContext.ts";
 import { RouterLayerContext } from "../contexts/RouterLayerContext.ts";
+import { Redirection } from "../errors/Redirection.ts";
 import {
   $page,
   type ErrorHandler,
   type PagePrimitive,
   type PagePrimitiveOptions,
 } from "../primitives/$page.ts";
-import { Redirection } from "../errors/Redirection.ts";
 
 const envSchema = t.object({
   REACT_STRICT_MODE: t.boolean({ default: true }),
@@ -32,6 +31,9 @@ declare module "alepha" {
   export interface Env extends Partial<Static<typeof envSchema>> {}
 }
 
+/**
+ * Handle page routes for React applications. (Browser and Server)
+ */
 export class ReactPageProvider {
   protected readonly log = $logger();
   protected readonly env = $env(envSchema);

package/src/{core → router}/providers/ReactServerProvider.ts

@@ -1,38 +1,15 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import {
-  $atom,
-  $env,
-  $hook,
-  $inject,
-  $use,
-  Alepha,
-  AlephaError,
-  type Static,
-  t,
-} from "alepha";
+import { $atom, $env, $hook, $inject, $use, Alepha, AlephaError, type Static, t, } from "alepha";
 import { $logger } from "alepha/logger";
-import {
-  type ServerHandler,
-  ServerProvider,
-  ServerRouterProvider,
-  ServerTimingProvider,
-} from "alepha/server";
+import { type ServerHandler, ServerRouterProvider, ServerTimingProvider, } from "alepha/server";
 import { ServerLinksProvider } from "alepha/server/links";
 import { ServerStaticProvider } from "alepha/server/static";
 import { renderToString } from "react-dom/server";
-import {
-  $page,
-  type PagePrimitiveRenderOptions,
-  type PagePrimitiveRenderResult,
-} from "../primitives/$page.ts";
 import { Redirection } from "../errors/Redirection.ts";
+import { $page, type PagePrimitiveRenderOptions, type PagePrimitiveRenderResult, } from "../primitives/$page.ts";
 import type { ReactHydrationState } from "./ReactBrowserProvider.ts";
-import {
-  type PageRoute,
-  ReactPageProvider,
-  type ReactRouterState,
-} from "./ReactPageProvider.ts";
+import { type PageRoute, ReactPageProvider, type ReactRouterState, } from "./ReactPageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -84,12 +61,16 @@ declare module "alepha" {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+/**
+ * React server provider responsible for SSR and static file serving.
+ *
+ * Use `react-dom/server` under the hood.
+ */
 export class ReactServerProvider {
   protected readonly log = $logger();
   protected readonly alepha = $inject(Alepha);
   protected readonly env = $env(envSchema);
   protected readonly pageApi = $inject(ReactPageProvider);
-  protected readonly serverProvider = $inject(ServerProvider);
   protected readonly serverStaticProvider = $inject(ServerStaticProvider);
   protected readonly serverRouterProvider = $inject(ServerRouterProvider);
   protected readonly serverTimingProvider = $inject(ServerTimingProvider);

package/src/{core → router}/services/ReactPageServerService.ts

@@ -7,6 +7,9 @@ import type {
 import { ReactServerProvider } from "../providers/ReactServerProvider.ts";
 import { ReactPageService } from "./ReactPageService.ts";
 
+/**
+ * $page methods for server-side.
+ */
 export class ReactPageServerService extends ReactPageService {
   protected readonly reactServerProvider = $inject(ReactServerProvider);
   protected readonly serverProvider = $inject(ServerProvider);

package/src/{core → router}/services/ReactPageService.ts

@@ -1,10 +1,10 @@
 import { AlephaError } from "alepha";
-import type {
-  PagePrimitiveRenderOptions,
-  PagePrimitiveRenderResult,
-} from "../primitives/$page.ts";
+import type { PagePrimitiveRenderOptions, PagePrimitiveRenderResult, } from "../../router/primitives/$page.ts";
 
-export class ReactPageService {
+/**
+ * $page methods interface.
+ */
+export abstract class ReactPageService {
   public fetch(
     pathname: string,
     options: PagePrimitiveRenderOptions = {},

package/src/{core → router}/services/ReactRouter.ts

@@ -1,15 +1,28 @@
 import { $inject, Alepha } from "alepha";
-import type { PagePrimitive } from "../primitives/$page.ts";
-import {
-  ReactBrowserProvider,
-  type RouterGoOptions,
-} from "../providers/ReactBrowserProvider.ts";
+import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
 import {
   type AnchorProps,
   ReactPageProvider,
   type ReactRouterState,
 } from "../providers/ReactPageProvider.ts";
+import type { PagePrimitive } from "../primitives/$page.ts";
+
+export interface RouterGoOptions {
+  replace?: boolean;
+  params?: Record<string, string>;
+  query?: Record<string, string>;
+  meta?: Record<string, any>;
+  /**
+   * Recreate the whole page, ignoring the current state.
+   */
+  force?: boolean;
+}
 
+/**
+ * Friendly browser router API.
+ *
+ * Can be safely used server-side, but most methods will be no-op.
+ */
 export class ReactRouter<T extends object> {
   protected readonly alepha = $inject(Alepha);
   protected readonly pageApi = $inject(ReactPageProvider);
@@ -59,6 +72,14 @@ export class ReactRouter<T extends object> {
     } = {},
   ) {
     const page = this.pageApi.page(name as string);
+    if (!page.lazy && !page.component) {
+      return {
+        ...page,
+        label: page.label ?? page.name,
+        children: undefined,
+      }
+    }
+
     return {
       ...page,
       label: page.label ?? page.name,