@alepha/react 0.14.1 → 0.14.3

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/router/providers/ReactServerProvider.spec.tsx

@@ -0,0 +1,316 @@
+import { test } from "vitest";
+
+// Simple mock for testing template functionality without full Alepha setup
+class MockReactServerProvider {
+  protected readonly env = { REACT_ROOT_ID: "root" };
+  protected readonly ROOT_DIV_REGEX = new RegExp(
+    `<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
+    "is",
+  );
+  protected preprocessedTemplate: any = null;
+
+  public preprocessTemplate(template: string) {
+    // Find the body close tag for script injection
+    const bodyCloseMatch = template.match(/<\/body>/i);
+    const bodyCloseIndex = bodyCloseMatch?.index ?? template.length;
+
+    const beforeScript = template.substring(0, bodyCloseIndex);
+    const afterScript = template.substring(bodyCloseIndex);
+
+    // Check if there's an existing root div
+    const rootDivMatch = beforeScript.match(this.ROOT_DIV_REGEX);
+
+    if (rootDivMatch) {
+      // Split around the existing root div content
+      const beforeDiv = beforeScript.substring(0, rootDivMatch.index!);
+      const afterDivStart = rootDivMatch.index! + rootDivMatch[0].length;
+      const afterDiv = beforeScript.substring(afterDivStart);
+
+      const beforeApp = `${beforeDiv}<div${rootDivMatch[1]} id="${this.env.REACT_ROOT_ID}"${rootDivMatch[2]}>`;
+      const afterApp = `</div>${afterDiv}`;
+
+      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    }
+
+    // No existing root div, find body tag to inject new div
+    const bodyMatch = beforeScript.match(/<body([^>]*)>/i);
+    if (bodyMatch) {
+      const beforeBody = beforeScript.substring(
+        0,
+        bodyMatch.index! + bodyMatch[0].length,
+      );
+      const afterBody = beforeScript.substring(
+        bodyMatch.index! + bodyMatch[0].length,
+      );
+
+      const beforeApp = `${beforeBody}<div id="${this.env.REACT_ROOT_ID}">`;
+      const afterApp = `</div>${afterBody}`;
+
+      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    }
+
+    // Fallback: no body tag found, just wrap everything
+    return {
+      beforeApp: `<div id="${this.env.REACT_ROOT_ID}">`,
+      afterApp: `</div>`,
+      beforeScript,
+      afterScript,
+    };
+  }
+
+  public fillTemplate(response: { html: string }, app: string, script: string) {
+    if (!this.preprocessedTemplate) {
+      // Fallback to old logic if preprocessing failed
+      this.preprocessedTemplate = this.preprocessTemplate(response.html);
+    }
+
+    // Pure concatenation - no regex replacements needed
+    response.html =
+      this.preprocessedTemplate.beforeApp +
+      app +
+      this.preprocessedTemplate.afterApp +
+      script +
+      this.preprocessedTemplate.afterScript;
+  }
+}
+
+const setup = (env?: any) => {
+  const provider = new MockReactServerProvider();
+  if (env?.REACT_ROOT_ID) {
+    (provider as any).env.REACT_ROOT_ID = env.REACT_ROOT_ID;
+    (provider as any).ROOT_DIV_REGEX = new RegExp(
+      `<div([^>]*)\\s+id=["']${env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
+      "is",
+    );
+  }
+  return { provider };
+};
+
+test("ReactServerProvider - preprocessTemplate with existing root div", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+  expect(preprocessed.beforeScript).toBe("");
+  expect(preprocessed.afterScript).toBe(`</body>
+</html>`);
+});
+
+test("ReactServerProvider - preprocessTemplate without root div", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <h1>Welcome</h1>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body><div id="root">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+  <h1>Welcome</h1>
+`);
+  expect(preprocessed.beforeScript).toBe("");
+  expect(preprocessed.afterScript).toBe(`</body>
+</html>`);
+});
+
+test("ReactServerProvider - preprocessTemplate with custom root ID", async ({
+  expect,
+}) => {
+  const { provider } = setup({ REACT_ROOT_ID: "app" });
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="app">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="app">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+});
+
+test("ReactServerProvider - preprocessTemplate with root div with attributes", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<body>
+  <div class="container" id="root" data-test="true">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<body>
+  <div class="container" id="root" data-test="true">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+});
+
+test("ReactServerProvider - preprocessTemplate fallback (no body tag)", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<html><div>content</div></html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(`<div id="root">`);
+  expect(preprocessed.afterApp).toBe(`</div>`);
+  expect(preprocessed.beforeScript).toBe(`<html><div>content</div></html>`);
+  expect(preprocessed.afterScript).toBe(``);
+});
+
+test("ReactServerProvider - fillTemplate concatenation", async ({ expect }) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">existing</div>
+</body>
+</html>`;
+
+  // Preprocess the template
+  const preprocessed = provider.preprocessTemplate(template);
+  (provider as any).preprocessedTemplate = preprocessed;
+
+  const response = { html: "" };
+  const app = "<h1>Hello World</h1>";
+  const script = '<script>window.__ssr={"test":true}</script>';
+
+  provider.fillTemplate(response, app, script);
+
+  const expected = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root"><h1>Hello World</h1></div>
+<script>window.__ssr={"test":true}</script></body>
+</html>`;
+
+  expect(response.html).toBe(expected);
+});
+
+test("ReactServerProvider - fillTemplate without preprocessed template (fallback)", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="root">existing</div>
+</body>
+</html>`;
+
+  const response = { html: template };
+  const app = "<h1>Hello World</h1>";
+  const script = '<script>window.__ssr={"test":true}</script>';
+
+  // Don't set preprocessedTemplate to test fallback
+  (provider as any).preprocessedTemplate = null;
+
+  provider.fillTemplate(response, app, script);
+
+  const expected = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="root"><h1>Hello World</h1></div>
+<script>window.__ssr={"test":true}</script></body>
+</html>`;
+
+  expect(response.html).toBe(expected);
+});
+
+test("ReactServerProvider - fillTemplate performance comparison", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Performance Test</title></head>
+<body>
+  <div id="root">existing content</div>
+  <script>console.log('existing');</script>
+</body>
+</html>`;
+
+  const app = "<div><h1>Hello World</h1><p>This is a test</p></div>";
+  const script = '<script>window.__ssr={"data":"value","count":42}</script>';
+
+  // Test with preprocessing (should be faster)
+  const preprocessed = provider.preprocessTemplate(template);
+  (provider as any).preprocessedTemplate = preprocessed;
+
+  const response1 = { html: "" };
+  const start1 = performance.now();
+  provider.fillTemplate(response1, app, script);
+  const time1 = performance.now() - start1;
+
+  // Test fallback without preprocessing (should work but potentially slower)
+  (provider as any).preprocessedTemplate = null;
+  const response2 = { html: template };
+  const start2 = performance.now();
+  provider.fillTemplate(response2, app, script);
+  const time2 = performance.now() - start2;
+
+  // Both should produce the same result
+  expect(response1.html).toBe(response2.html);
+
+  // The result should contain the app content
+  expect(response1.html).toContain("<h1>Hello World</h1>");
+  expect(response1.html).toContain(
+    '<script>window.__ssr={"data":"value","count":42}</script>',
+  );
+});

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, ServerProvider, 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);
@@ -235,9 +216,10 @@ export class ReactServerProvider {
       return;
     }
 
-    this.log.info("SSR (dev) OK");
+    const env = this.alepha.store.get("env") ?? {}
+    const url = `http://localhost:${env.SERVER_PORT ?? "5173"}`;
 
-    const url = `http://${process.env.SERVER_HOST}:${process.env.SERVER_PORT}`;
+    this.log.info("SSR (dev) OK", { url });
 
     await this.registerPages(() =>
       fetch(`${url}/index.html`)

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,