@alepha/react 0.14.2 → 0.14.4

package/src/router/primitives/$page.ts

@@ -14,6 +14,9 @@ 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";
+import type { Head } from "@alepha/react/head";
+import { PAGE_PRELOAD_KEY } from "../constants/PAGE_PRELOAD_KEY.ts";
+
 
 /**
  * Main primitive for defining a React route in the application.
@@ -27,7 +30,7 @@ import type { ClientOnlyProps } from "@alepha/react";
  * - Type-safe URL parameter and query string validation
  *
  * **Data Loading**
- * - Server-side data fetching with the `resolve` function
+ * - Server-side data fetching with the `loader` function
  * - Automatic serialization and hydration for SSR
  * - Access to request context, URL params, and parent data
  *
@@ -64,7 +67,7 @@ import type { ClientOnlyProps } from "@alepha/react";
  *     params: t.object({ id: t.integer() }),
  *     query: t.object({ tab: t.optional(t.text()) })
  *   },
- *   resolve: async ({ params }) => {
+ *   loader: async ({ params }) => {
  *     const user = await userApi.getUser(params.id);
  *     return { user };
  *   },
@@ -77,7 +80,7 @@ import type { ClientOnlyProps } from "@alepha/react";
  * const projectSection = $page({
  *   path: "/projects/:id",
  *   children: () => [projectBoard, projectSettings],
- *   resolve: async ({ params }) => {
+ *   loader: async ({ params }) => {
  *     const project = await projectApi.get(params.id);
  *     return { project };
  *   },
@@ -96,7 +99,7 @@ import type { ClientOnlyProps } from "@alepha/react";
  *   static: {
  *     entries: posts.map(p => ({ params: { slug: p.slug } }))
  *   },
- *   resolve: async ({ params }) => {
+ *   loader: async ({ params }) => {
  *     const post = await loadPost(params.slug);
  *     return { post };
  *   }
@@ -155,12 +158,12 @@ export interface PagePrimitiveOptions<
    *
    * > In SSR, the returned data will be serialized and sent to the client, then reused during the client-side hydration.
    *
-   * Resolve can be stopped by throwing an error, which will be handled by the `errorHandler` function.
+   * Loader can be stopped by throwing an error, which will be handled by the `errorHandler` function.
    * It's common to throw a `NotFoundError` to display a 404 page.
    *
    * RedirectError can be thrown to redirect the user to another page.
    */
-  resolve?: (context: PageResolve<TConfig, TPropsParent>) => Async<TProps>;
+  loader?: (context: PageLoader<TConfig, TPropsParent>) => Async<TProps>;
 
   /**
    * Default props to pass to the component when rendering the page.
@@ -205,7 +208,7 @@ export interface PagePrimitiveOptions<
   can?: () => boolean;
 
   /**
-   * Catch any error from the `resolve` function or during `rendering`.
+   * Catch any error from the `loader` function or during `rendering`.
    *
    * Expected to return one of the following:
    * - a ReactNode to render an error page
@@ -217,7 +220,7 @@ export interface PagePrimitiveOptions<
    *
    * @example Catch a 404 from API and render a custom not found component:
    * ```ts
-   * resolve: async ({ params, query }) => {
+   * loader: async ({ params, query }) => {
    *    api.fetch("/api/resource", { params, query });
    * },
    * errorHandler: (error, context) => {
@@ -229,7 +232,7 @@ export interface PagePrimitiveOptions<
    *
    * @example Catch an 401 error and redirect the user to the login page:
    * ```ts
-   * resolve: async ({ params, query }) => {
+   * loader: async ({ params, query }) => {
    *   // but the user is not authenticated
    *   api.fetch("/api/resource", { params, query });
    * },
@@ -318,6 +321,39 @@ export interface PagePrimitiveOptions<
    * ```
    */
   animation?: PageAnimation;
+
+  /**
+   * Head configuration for the page (title, meta tags, etc.).
+   *
+   * Can be a static object or a function that receives resolved props.
+   *
+   * @example Static head
+   * ```ts
+   * head: {
+   *   title: "My Page",
+   *   description: "Page description",
+   * }
+   * ```
+   *
+   * @example Dynamic head based on props
+   * ```ts
+   * head: (props) => ({
+   *   title: props.user.name,
+   *   description: `Profile of ${props.user.name}`,
+   * })
+   * ```
+   */
+  head?: Head | ((props: TProps, previous?: Head) => Head);
+
+  /**
+   * Source path for SSR module preloading.
+   *
+   * This is automatically injected by the viteAlephaPreload plugin.
+   * It maps to the source file path used in Vite's SSR manifest.
+   *
+   * @internal
+   */
+  [PAGE_PRELOAD_KEY]?: string;
 }
 
 export type ErrorHandler = (
@@ -422,7 +458,7 @@ export interface PageRequestConfig<
     : Record<string, string>;
 }
 
-export type PageResolve<
+export type PageLoader<
   TConfig extends PageConfigSchema = PageConfigSchema,
   TPropsParent extends object = TPropsParentDefault,
 > = PageRequestConfig<TConfig> &

package/src/router/providers/ReactBrowserProvider.ts

@@ -1,36 +1,14 @@
-import {
-  $atom,
-  $env,
-  $hook,
-  $inject,
-  $use,
-  Alepha,
-  type State,
-  type Static,
-  t,
-} from "alepha";
+import { $atom, $env, $hook, $inject, $use, Alepha, type State, type Static, t, } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { LinkProvider } from "alepha/server/links";
+import { BrowserHeadProvider } from "@alepha/react/head";
 import { ReactBrowserRouterProvider } from "./ReactBrowserRouterProvider.ts";
-import type {
-  PreviousLayerData,
-  ReactRouterState,
-  TransitionOptions,
-} from "./ReactPageProvider.ts";
+import type { PreviousLayerData, ReactRouterState, } from "./ReactPageProvider.ts";
 import type { RouterGoOptions } from "../services/ReactRouter.ts";
 
 export type { RouterGoOptions } from "../services/ReactRouter.ts";
 
-// ---------------------------------------------------------------------------------------------------------------------
-
-const envSchema = t.object({
-  REACT_ROOT_ID: t.text({ default: "root" }),
-});
-
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
 
 /**
  * React browser renderer configuration atom
@@ -38,7 +16,7 @@ declare module "alepha" {
 export const reactBrowserOptions = $atom({
   name: "alepha.react.browser.options",
   schema: t.object({
-    scrollRestoration: t.enum(["top", "manual"]),
+    scrollRestoration: t.enum(["top", "manual"]), // TODO: must be per page?
   }),
   default: {
     scrollRestoration: "top" as const,
@@ -58,23 +36,27 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 export class ReactBrowserProvider {
-  protected readonly env = $env(envSchema);
   protected readonly log = $logger();
   protected readonly client = $inject(LinkProvider);
   protected readonly alepha = $inject(Alepha);
   protected readonly router = $inject(ReactBrowserRouterProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
 
   protected readonly options = $use(reactBrowserOptions);
 
+  public get rootId() {
+    return "root";
+  }
+
   protected getRootElement() {
-    const root = this.document.getElementById(this.env.REACT_ROOT_ID);
+    const root = this.document.getElementById(this.rootId);
     if (root) {
       return root;
     }
 
     const div = this.document.createElement("div");
-    div.id = this.env.REACT_ROOT_ID;
+    div.id = this.rootId;
 
     this.document.body.prepend(div);
 
@@ -281,6 +263,9 @@ export class ReactBrowserProvider {
         state: this.state,
       });
 
+      // Fill and render head from route configurations
+      this.browserHeadProvider.fillAndRenderHead(this.state);
+
       window.addEventListener("popstate", () => {
         // when you update silently queryParams or hash, skip rendering
         // if you want to force a rendering, use #go()

package/src/router/providers/ReactBrowserRouterProvider.ts

@@ -2,6 +2,7 @@ import { $hook, $inject, Alepha } from "alepha";
 import { $logger } from "alepha/logger";
 import { type Route, RouterProvider } from "alepha/router";
 import { createElement, type ReactNode } from "react";
+import { BrowserHeadProvider } from "@alepha/react/head";
 import NotFoundPage from "../components/NotFound.tsx";
 import {
   isPageRoute,
@@ -23,6 +24,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
   protected readonly log = $logger();
   protected readonly alepha = $inject(Alepha);
   protected readonly pageApi = $inject(ReactPageProvider);
+  protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
 
   public add(entry: PageRouteEntry) {
     this.pageApi.add(entry);
@@ -147,6 +149,9 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
     await this.alepha.events.emit("react:transition:end", {
       state,
     });
+
+    // Fill and render head from route configurations
+    this.browserHeadProvider.fillAndRenderHead(state);
   }
 
   public root(state: ReactRouterState): ReactNode {

package/src/router/providers/ReactPageProvider.ts

@@ -22,6 +22,7 @@ import {
   type PagePrimitive,
   type PagePrimitiveOptions,
 } from "../primitives/$page.ts";
+import type { Head } from "@alepha/react/head";
 
 const envSchema = t.object({
   REACT_STRICT_MODE: t.boolean({ default: true }),
@@ -251,15 +252,15 @@ export class ReactPageProvider {
         forceRefresh = true;
       }
 
-      // no resolve, render a basic view by default
-      if (!route.resolve) {
+      // no loader, render a basic view by default
+      if (!route.loader) {
         continue;
       }
 
       try {
         const args = Object.create(state);
         Object.assign(args, config, context);
-        const props = (await route.resolve?.(args)) ?? {};
+        const props = (await route.loader?.(args)) ?? {};
 
         // save props
         it.props = {
@@ -279,7 +280,7 @@ export class ReactPageProvider {
           };
         }
 
-        this.log.error("Page resolver has failed", e);
+        this.log.error("Page loader has failed", e);
 
         it.error = e as Error;
         break;
@@ -696,6 +697,12 @@ export interface ReactRouterState {
    */
   meta: Record<string, any>;
 
+  /**
+   * Head configuration for the current page (title, meta tags, etc.).
+   * Populated by HeadProvider during SSR.
+   */
+  head: Head;
+
   //
   name?: string;
 }

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>',
+  );
+});