@alepha/react 0.14.3 → 0.15.0

package/src/router/primitives/$page.spec.tsx

@@ -61,7 +61,7 @@ describe("$page primitive tests", () => {
             sort: t.optional(t.text()),
           }),
         },
-        resolve: ({ params, query }) => ({ params, query }),
+        loader: ({ params, query }) => ({ params, query }),
         component: ({ params, query }) =>
           `User ${params.id} - Tab: ${query.tab}`,
       });
@@ -72,7 +72,7 @@ describe("$page primitive tests", () => {
 
     expect(app.user.options.schema?.params).toBeDefined();
     expect(app.user.options.schema?.query).toBeDefined();
-    expect(app.user.options.resolve).toBeDefined();
+    expect(app.user.options.loader).toBeDefined();
     expect(app.user.options.component).toBeDefined();
 
     const rendered = await app.user.render({
@@ -89,7 +89,7 @@ describe("$page primitive tests", () => {
     class App {
       lazy = $page({
         path: "/lazy",
-        resolve: () => ({ message: "loaded" }),
+        loader: () => ({ message: "loaded" }),
         lazy: async () => ({ default: LazyComponent }),
       });
     }
@@ -141,7 +141,7 @@ describe("$page primitive tests", () => {
             id: t.text(),
           }),
         },
-        resolve: async ({ params }) => {
+        loader: async ({ params }) => {
           await new Promise((resolve) => setTimeout(resolve, 10));
           return { data: `Data for ${params.id}`, timestamp: Date.now() };
         },
@@ -152,8 +152,8 @@ describe("$page primitive tests", () => {
     const app = alepha.inject(App);
     await alepha.start();
 
-    expect(app.async.options.resolve).toBeDefined();
-    expect(typeof app.async.options.resolve).toBe("function");
+    expect(app.async.options.loader).toBeDefined();
+    expect(typeof app.async.options.loader).toBe("function");
 
     const mockContext = {
       params: { id: "test" },
@@ -161,7 +161,7 @@ describe("$page primitive tests", () => {
       pathname: "/async/test",
       search: "",
     };
-    const result = await app.async.options.resolve!(mockContext as any);
+    const result = await app.async.options.loader!(mockContext as any);
     expect(result.data).toBe("Data for test");
     expect(typeof result.timestamp).toBe("number");
 
@@ -173,14 +173,14 @@ describe("$page primitive tests", () => {
     class App {
       parent = $page({
         path: "/parent",
-        resolve: () => ({ parentData: "from parent" }),
+        loader: () => ({ parentData: "from parent" }),
         children: [],
       });
 
       child = $page({
         path: "/child",
         parent: this.parent,
-        resolve: ({ parentData }) => ({
+        loader: ({ parentData }) => ({
           childData: `child with ${parentData}`,
         }),
         component: ({ childData }) => childData,
@@ -261,7 +261,7 @@ describe("$page primitive tests", () => {
     class App {
       errorPage = $page({
         path: "/error",
-        resolve: () => {
+        loader: () => {
           throw new Error("Test error");
         },
         errorHandler: (error) => `Error: ${error.message}`,
@@ -289,7 +289,7 @@ describe("$page primitive tests", () => {
     class App {
       errorPage = $page({
         path: "/error",
-        resolve: () => {
+        loader: () => {
           throw new Error("unauthorized");
         },
         errorHandler: (error) => {
@@ -342,7 +342,7 @@ describe("$page primitive tests", () => {
         static: {
           entries: [{ params: { id: "1" } }, { params: { id: "2" } }],
         },
-        resolve: ({ params }) => ({ id: params.id }),
+        loader: ({ params }) => ({ id: params.id }),
         component: ({ id }) => `Static page ${id}`,
       });
     }
@@ -566,7 +566,7 @@ describe("$page primitive tests", () => {
             limit: t.number({ default: 10 }),
           }),
         },
-        resolve: ({ params, query }) => ({
+        loader: ({ params, query }) => ({
           user: { id: params.userId },
           pagination: { page: query.page, limit: query.limit },
           filters: query.filters,
@@ -582,7 +582,7 @@ describe("$page primitive tests", () => {
 
     expect(app.complex.options.schema?.params).toBeDefined();
     expect(app.complex.options.schema?.query).toBeDefined();
-    expect(app.complex.options.resolve).toBeDefined();
+    expect(app.complex.options.loader).toBeDefined();
 
     const rendered = await app.complex.render({
       params: { userId: "123" },
@@ -608,7 +608,7 @@ describe("$page primitive tests", () => {
 
       child = $page({
         path: "/child",
-        resolve: () => {
+        loader: () => {
           throw new Error("Child error");
         },
         errorHandler: (error) => {
@@ -648,13 +648,13 @@ describe("$page primitive tests", () => {
   test("$page - resolve function receives parent props", async ({ expect }) => {
     class App {
       parent = $page({
-        resolve: () => ({ parentValue: "from parent" }),
+        loader: () => ({ parentValue: "from parent" }),
       });
 
       child = $page({
         path: "/child",
         parent: this.parent,
-        resolve: ({ parentValue }) => ({
+        loader: ({ parentValue }) => ({
           childData: `Child received: ${parentValue}`,
         }),
         component: ({ childData, parentValue }) =>
@@ -665,7 +665,7 @@ describe("$page primitive tests", () => {
     const app = alepha.inject(App);
     await alepha.start();
 
-    expect(app.child.options.resolve).toBeDefined();
+    expect(app.child.options.loader).toBeDefined();
 
     const rendered = await app.child.fetch();
     expect(rendered.html).toBe("Child received: from parent and from parent");

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;
 }