@alepha/react 0.14.3 → 0.14.4

package/package.json

@@ -2,7 +2,7 @@
   "name": "@alepha/react",
   "description": "React components and hooks for building Alepha applications.",
   "author": "Nicolas Foures",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "type": "module",
   "engines": {
     "node": ">=22.0.0"
@@ -25,19 +25,19 @@
     "@testing-library/react": "^16.3.1",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "alepha": "0.14.3",
+    "alepha": "0.14.4",
     "jsdom": "^27.4.0",
     "react": "^19.2.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },
   "peerDependencies": {
-    "alepha": "0.14.3",
+    "alepha": "0.14.4",
     "react": "^19"
   },
   "scripts": {
     "lint": "alepha lint",
-    "check": "alepha typecheck",
+    "typecheck": "alepha typecheck",
     "test": "vitest run",
     "build": "node scripts/build.ts"
   },

package/src/core/__tests__/Router.spec.tsx

@@ -74,7 +74,7 @@ test("Router - NestedView", async ({ expect }) => {
             name: t.text(),
           }),
         },
-        resolve: ({ params }) => params,
+        loader: ({ params }) => params,
         component: (props) => `Hello, ${props.name}!`,
       },
     ],
@@ -125,18 +125,18 @@ test("Router - All routes", async ({ expect }) => {
           {
             path: ":id",
             schema: { params: t.object({ id: t.text() }) },
-            resolve: ({ params }) => {
+            loader: ({ params }) => {
               if (params.id === "boom") throw new Error("boom");
               return params;
             },
             children: [
               {
-                resolve: ({ params }) => params,
+                loader: ({ params }) => params,
                 component: ({ id }) => `hey ${id}`,
               },
               {
                 path: "profile",
-                resolve: ({ params }) => params,
+                loader: ({ params }) => params,
                 component: ({ id }) => `profile of ${id}`,
               },
             ],

package/src/head/{__tests__/expandSeo.spec.ts → helpers/SeoExpander.spec.ts}

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { describe, it } from "vitest";
-import { SeoExpander } from "../helpers/SeoExpander.ts";
+import { SeoExpander } from "./SeoExpander.ts";
 
 describe("SeoExpander", () => {
   it("should expand basic SEO configuration", ({ expect }) => {

package/src/head/index.ts

@@ -1,15 +1,10 @@
 import { AlephaReact } from "@alepha/react";
-import type {
-  PageConfigSchema,
-  TPropsDefault,
-  TPropsParentDefault,
-} from "@alepha/react/router";
 import { $module } from "alepha";
 import { $head } from "./primitives/$head.ts";
-import type { Head } from "./interfaces/Head.ts";
-import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
+import { BrowserHeadProvider } from "./providers/BrowserHeadProvider.ts";
 import { HeadProvider } from "./providers/HeadProvider.ts";
 import { SeoExpander } from "./helpers/SeoExpander.ts";
+import { ServerHeadProvider } from "./providers/ServerHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -18,26 +13,7 @@ export * from "./hooks/useHead.ts";
 export * from "./interfaces/Head.ts";
 export * from "./helpers/SeoExpander.ts";
 export * from "./providers/ServerHeadProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-// Augment PagePrimitiveOptions in router module
-declare module "@alepha/react/router" {
-  interface PagePrimitiveOptions<
-    TConfig extends PageConfigSchema = PageConfigSchema,
-    TProps extends object = TPropsDefault,
-    TPropsParent extends object = TPropsParentDefault,
-  > {
-    head?: Head | ((props: TProps, previous?: Head) => Head);
-  }
-}
-
-// Augment ReactRouterState in router module
-declare module "@alepha/react/router" {
-  interface ReactRouterState {
-    head: Head;
-  }
-}
+export * from "./providers/BrowserHeadProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -55,5 +31,11 @@ declare module "@alepha/react/router" {
 export const AlephaReactHead = $module({
   name: "alepha.react.head",
   primitives: [$head],
-  services: [AlephaReact, ServerHeadProvider, HeadProvider, SeoExpander],
+  services: [
+    AlephaReact,
+    BrowserHeadProvider,
+    HeadProvider,
+    SeoExpander,
+    ServerHeadProvider,
+  ],
 });

package/src/head/providers/BrowserHeadProvider.browser.spec.ts

@@ -1,7 +1,5 @@
-import { $page } from "@alepha/react/router";
 import { Alepha } from "alepha";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { AlephaReactHead } from "../index.browser.ts";
+import { beforeEach, describe, expect, it } from "vitest";
 import type { Head } from "../interfaces/Head.ts";
 import { BrowserHeadProvider } from "./BrowserHeadProvider.ts";
 
@@ -195,77 +193,4 @@ describe("BrowserHeadProvider", () => {
       expect(authorMeta?.getAttribute("content")).toBe("Test Author");
     });
   });
-
-  describe("$page integration", () => {
-    class TestApp {
-      simplePage = $page({
-        path: "/",
-        head: {
-          title: "Simple Page",
-          bodyAttributes: { class: "simple-page" },
-        },
-        component: () => "Simple content",
-      });
-
-      complexPage = $page({
-        path: "/complex",
-        head: {
-          title: "Complex Page",
-          htmlAttributes: {
-            lang: "en",
-            "data-theme": "dark",
-          },
-          bodyAttributes: {
-            class: "complex-page",
-            style: "background: black;",
-          },
-          meta: [
-            { name: "description", content: "Complex test page" },
-            {
-              name: "viewport",
-              content: "width=device-width, initial-scale=1",
-            },
-          ],
-        },
-        component: () => "Complex content",
-      });
-    }
-
-    afterEach(() => {
-      document.body.querySelector("#root")?.remove();
-    });
-
-    it("should render simple page head configuration", async () => {
-      const alepha = Alepha.create().with(AlephaReactHead).with(TestApp);
-      await alepha.start();
-
-      expect(document.title).toBe("Simple Page");
-      expect(document.body.getAttribute("class")).toBe("simple-page");
-    });
-
-    it("should get current head state and match page configuration", async () => {
-      const alepha = Alepha.create().with(AlephaReactHead);
-      const app = alepha.inject(TestApp);
-      await alepha.start();
-
-      // Apply complex page head
-      const headConfig = app.complexPage.options.head as Head;
-      provider.renderHead(document, headConfig);
-
-      // Get current head state
-      const currentHead = provider.getHead(document);
-
-      expect(currentHead.title).toBe(headConfig.title);
-      expect(currentHead.htmlAttributes?.lang).toBe(
-        headConfig.htmlAttributes?.lang,
-      );
-      expect(currentHead.bodyAttributes?.class).toBe(
-        headConfig.bodyAttributes?.class,
-      );
-      expect(currentHead.meta).toContainEqual({
-        name: "description",
-        content: "Complex test page",
-      });
-    });
-  });
 });

package/src/head/providers/BrowserHeadProvider.ts

@@ -1,33 +1,39 @@
-import { $hook, $inject } from "alepha";
+import { $inject, Alepha } from "alepha";
 import type { Head, HeadMeta } from "../interfaces/Head.ts";
 import { HeadProvider } from "./HeadProvider.ts";
 
+/**
+ * Browser-side head provider that manages document head elements.
+ *
+ * Used by ReactBrowserProvider and ReactBrowserRouterProvider to update
+ * document title, meta tags, and other head elements during client-side
+ * navigation.
+ */
 export class BrowserHeadProvider {
+  protected readonly alepha = $inject(Alepha);
   protected readonly headProvider = $inject(HeadProvider);
 
   protected get document(): Document {
     return window.document;
   }
 
-  protected readonly onBrowserRender = $hook({
-    on: "react:browser:render",
-    handler: async ({ state }) => {
-      this.headProvider.fillHead(state);
-      if (state.head) {
-        this.renderHead(this.document, state.head);
-      }
-    },
-  });
+  /**
+   * Fill head state from route configurations and render to document.
+   * Combines fillHead from HeadProvider with renderHead to the DOM.
+   *
+   * Only runs in browser environment - no-op on server.
+   */
+  public fillAndRenderHead(state: { head: Head; layers: Array<any> }): void {
+    // Skip on server-side
+    if (!this.alepha.isBrowser()) {
+      return;
+    }
 
-  protected readonly onTransitionEnd = $hook({
-    on: "react:transition:end",
-    handler: async ({ state }) => {
-      this.headProvider.fillHead(state);
-      if (state.head) {
-        this.renderHead(this.document, state.head);
-      }
-    },
-  });
+    this.headProvider.fillHead(state as any);
+    if (state.head) {
+      this.renderHead(this.document, state.head);
+    }
+  }
 
   public getHead(document: Document): Head {
     return {

package/src/head/providers/HeadProvider.ts

@@ -1,14 +1,54 @@
-import type { PageRoute, ReactRouterState } from "@alepha/react/router";
 import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
 import { SeoExpander } from "../helpers/SeoExpander.ts";
 import type { Head } from "../interfaces/Head.ts";
 
+/**
+ * Provides methods to fill and merge head information into the application state.
+ *
+ * Used both on server and client side to manage document head.
+ *
+ * @see {@link SeoExpander}
+ * @see {@link ServerHeadProvider}
+ * @see {@link BrowserHeadProvider}
+ */
 export class HeadProvider {
+  protected readonly log = $logger();
   protected readonly seoExpander = $inject(SeoExpander);
 
   public global?: Array<Head | (() => Head)> = [];
 
-  public fillHead(state: ReactRouterState) {
+  /**
+   * Track if we've warned about page-level htmlAttributes to avoid spam.
+   */
+  protected warnedAboutHtmlAttributes = false;
+
+  /**
+   * Resolve global head configuration (from $head primitives only).
+   *
+   * This is used to get htmlAttributes early, before page loaders run.
+   * Only htmlAttributes from global $head are allowed; page-level htmlAttributes
+   * are ignored for early streaming optimization.
+   *
+   * @returns Merged global head with htmlAttributes
+   */
+  public resolveGlobalHead(): Head {
+    const head: Head = {};
+
+    for (const h of this.global ?? []) {
+      const resolved = typeof h === "function" ? h() : h;
+      if (resolved.htmlAttributes) {
+        head.htmlAttributes = {
+          ...head.htmlAttributes,
+          ...resolved.htmlAttributes,
+        };
+      }
+    }
+
+    return head;
+  }
+
+  public fillHead(state: HeadState) {
     state.head = {
       ...state.head,
     };
@@ -25,7 +65,7 @@ export class HeadProvider {
     }
   }
 
-  protected mergeHead(state: ReactRouterState, head: Head): void {
+  protected mergeHead(state: HeadState, head: Head): void {
     // Expand SEO fields into meta tags
     const { meta, link } = this.seoExpander.expand(head);
     state.head = {
@@ -38,8 +78,8 @@ export class HeadProvider {
   }
 
   protected fillHeadByPage(
-    page: PageRoute,
-    state: ReactRouterState,
+    page: HeadRoute,
+    state: HeadState,
     props: Record<string, any>,
   ): void {
     if (!page.head) {
@@ -70,11 +110,14 @@ export class HeadProvider {
       state.head.titleSeparator = head.titleSeparator;
     }
 
-    if (head.htmlAttributes) {
-      state.head.htmlAttributes = {
-        ...state.head.htmlAttributes,
-        ...head.htmlAttributes,
-      };
+    // htmlAttributes from pages are ignored for early streaming optimization.
+    // Only global $head can set htmlAttributes.
+    if (head.htmlAttributes && !this.warnedAboutHtmlAttributes) {
+      this.warnedAboutHtmlAttributes = true;
+      this.log.warn(
+        "Page-level htmlAttributes are ignored. Use global $head() for htmlAttributes instead, " +
+          "as they are sent before page loaders run for early streaming optimization.",
+      );
     }
 
     if (head.bodyAttributes) {
@@ -97,3 +140,26 @@ export class HeadProvider {
     }
   }
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Minimal route interface for head processing.
+ * Avoids circular dependency with @alepha/react/router.
+ */
+interface HeadRoute {
+  head?: Head | ((props: Record<string, any>, previous?: Head) => Head);
+}
+
+/**
+ * Minimal state interface for head processing.
+ * Avoids circular dependency with @alepha/react/router.
+ */
+interface HeadState {
+  head: Head;
+  layers: Array<{
+    route?: HeadRoute;
+    props?: Record<string, any>;
+    error?: Error;
+  }>;
+}

package/src/head/providers/ServerHeadProvider.ts

@@ -1,147 +1,31 @@
-import { $hook, $inject } from "alepha";
-import { ServerTimingProvider } from "alepha/server";
-import type { HeadMeta, SimpleHead } from "../interfaces/Head.ts";
+import { $inject } from "alepha";
+import type { Head, SimpleHead } from "../interfaces/Head.ts";
 import { HeadProvider } from "./HeadProvider.ts";
 
+/**
+ * Server-side head provider that fills head content from route configurations.
+ *
+ * Used by ReactServerProvider to collect title, meta tags, and other head
+ * elements which are then rendered by ReactServerTemplateProvider.
+ */
 export class ServerHeadProvider {
   protected readonly headProvider = $inject(HeadProvider);
-  protected readonly serverTimingProvider = $inject(ServerTimingProvider);
 
-  protected readonly onServerRenderEnd = $hook({
-    on: "react:server:render:end",
-    handler: async (ev) => {
-      this.serverTimingProvider.beginTiming("renderHead");
-      this.headProvider.fillHead(ev.state);
-      if (ev.state.head) {
-        ev.html = this.renderHead(ev.html, ev.state.head);
-      }
-      this.serverTimingProvider.endTiming("renderHead");
-    },
-  });
-
-  public renderHead(template: string, head: SimpleHead): string {
-    let result = template;
-
-    // Inject htmlAttributes
-    const htmlAttributes = head.htmlAttributes;
-    if (htmlAttributes) {
-      result = result.replace(
-        /<html([^>]*)>/i,
-        (_, existingAttrs) =>
-          `<html${this.mergeAttributes(existingAttrs, htmlAttributes)}>`,
-      );
-    }
-
-    // Inject bodyAttributes
-    const bodyAttributes = head.bodyAttributes;
-    if (bodyAttributes) {
-      result = result.replace(
-        /<body([^>]*)>/i,
-        (_, existingAttrs) =>
-          `<body${this.mergeAttributes(existingAttrs, bodyAttributes)}>`,
-      );
-    }
-
-    // Build head content
-    let headContent = "";
-    const title = head.title;
-    if (title) {
-      if (template.includes("<title>")) {
-        result = result.replace(
-          /<title>(.*?)<\/title>/i,
-          () => `<title>${this.escapeHtml(title)}</title>`,
-        );
-      } else {
-        headContent += `<title>${this.escapeHtml(title)}</title>\n`;
-      }
-    }
-
-    if (head.meta) {
-      for (const meta of head.meta) {
-        headContent += this.renderMetaTag(meta);
-      }
-    }
-
-    if (head.link) {
-      for (const link of head.link) {
-        headContent += `<link rel="${this.escapeHtml(link.rel)}" href="${this.escapeHtml(link.href)}">\n`;
-      }
-    }
-
-    if (head.script) {
-      for (const script of head.script) {
-        headContent += this.renderScriptTag(script);
-      }
-    }
-
-    // Inject into <head>...</head>
-    result = result.replace(
-      /<head([^>]*)>(.*?)<\/head>/is,
-      (_, existingAttrs, existingHead) =>
-        `<head${existingAttrs}>${existingHead}${headContent}</head>`,
-    );
-
-    return result.trim();
-  }
-
-  protected mergeAttributes(
-    existing: string,
-    attrs: Record<string, string>,
-  ): string {
-    const existingAttrs = this.parseAttributes(existing);
-    const merged = { ...existingAttrs, ...attrs };
-    return Object.entries(merged)
-      .map(([k, v]) => ` ${k}="${this.escapeHtml(v)}"`)
-      .join("");
-  }
-
-  protected parseAttributes(attrStr: string): Record<string, string> {
-    attrStr = attrStr.replaceAll("'", '"');
-
-    const attrs: Record<string, string> = {};
-    const attrRegex = /([^\s=]+)(?:="([^"]*)")?/g;
-    let match: RegExpExecArray | null = attrRegex.exec(attrStr);
-
-    while (match) {
-      attrs[match[1]] = match[2] ?? "";
-      match = attrRegex.exec(attrStr);
-    }
-
-    return attrs;
-  }
-
-  protected escapeHtml(str: string): string {
-    return str
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;")
-      .replace(/'/g, "&#039;");
-  }
-
-  protected renderMetaTag(meta: HeadMeta): string {
-    // OpenGraph tags use property attribute
-    if (meta.property) {
-      return `<meta property="${this.escapeHtml(meta.property)}" content="${this.escapeHtml(meta.content)}">\n`;
-    }
-    // Standard meta tags use name attribute
-    if (meta.name) {
-      return `<meta name="${this.escapeHtml(meta.name)}" content="${this.escapeHtml(meta.content)}">\n`;
-    }
-    return "";
+  /**
+   * Resolve global head configuration (htmlAttributes only).
+   *
+   * Used for early streaming optimization - htmlAttributes can be sent
+   * before page loaders run since they come from global $head only.
+   */
+  public resolveGlobalHead(): Head {
+    return this.headProvider.resolveGlobalHead();
   }
 
-  protected renderScriptTag(script: Record<string, string | boolean>): string {
-    const attrs = Object.entries(script)
-      .filter(([, value]) => value !== false)
-      .map(([key, value]) => {
-        // Boolean attributes - render without value if true
-        if (value === true) {
-          return key;
-        }
-        return `${key}="${this.escapeHtml(String(value))}"`;
-      })
-      .join(" ");
-    return `<script ${attrs}></script>\n`;
+  /**
+   * Fill head state from route configurations.
+   * Delegates to HeadProvider to merge head data from all route layers.
+   */
+  public fillHead(state: { head: SimpleHead; layers: Array<any> }): void {
+    this.headProvider.fillHead(state as any);
   }
 }

package/src/router/__tests__/page-head-browser.browser.spec.ts

@@ -0,0 +1,91 @@
+import { AlephaReactHead, BrowserHeadProvider, type Head } from "@alepha/react/head";
+import { Alepha } from "alepha";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { $page } from "../index.browser.ts";
+
+describe("$page head integration (browser)", () => {
+  let provider: BrowserHeadProvider;
+
+  class TestApp {
+    simplePage = $page({
+      path: "/",
+      head: {
+        title: "Simple Page",
+        bodyAttributes: { class: "simple-page" },
+      },
+      component: () => "Simple content",
+    });
+
+    complexPage = $page({
+      path: "/complex",
+      head: {
+        title: "Complex Page",
+        htmlAttributes: {
+          lang: "en",
+          "data-theme": "dark",
+        },
+        bodyAttributes: {
+          class: "complex-page",
+          style: "background: black;",
+        },
+        meta: [
+          { name: "description", content: "Complex test page" },
+          {
+            name: "viewport",
+            content: "width=device-width, initial-scale=1",
+          },
+        ],
+      },
+      component: () => "Complex content",
+    });
+  }
+
+  beforeEach(() => {
+    // Reset document state
+    document.title = "";
+    document.head.innerHTML = "";
+    document.body.removeAttribute("class");
+    document.body.removeAttribute("style");
+    document.documentElement.removeAttribute("lang");
+    document.documentElement.removeAttribute("class");
+    document.documentElement.removeAttribute("data-theme");
+  });
+
+  afterEach(() => {
+    document.body.querySelector("#root")?.remove();
+  });
+
+  it("should render simple page head configuration", async () => {
+    const alepha = Alepha.create().with(AlephaReactHead).with(TestApp);
+    await alepha.start();
+
+    expect(document.title).toBe("Simple Page");
+    expect(document.body.getAttribute("class")).toBe("simple-page");
+  });
+
+  it("should get current head state and match page configuration", async () => {
+    const alepha = Alepha.create().with(AlephaReactHead);
+    provider = alepha.inject(BrowserHeadProvider);
+    const app = alepha.inject(TestApp);
+    await alepha.start();
+
+    // Apply complex page head
+    const headConfig = app.complexPage.options.head as Head;
+    provider.renderHead(document, headConfig);
+
+    // Get current head state
+    const currentHead = provider.getHead(document);
+
+    expect(currentHead.title).toBe(headConfig.title);
+    expect(currentHead.htmlAttributes?.lang).toBe(
+      headConfig.htmlAttributes?.lang,
+    );
+    expect(currentHead.bodyAttributes?.class).toBe(
+      headConfig.bodyAttributes?.class,
+    );
+    expect(currentHead.meta).toContainEqual({
+      name: "description",
+      content: "Complex test page",
+    });
+  });
+});