alepha 0.22.0 → 0.23.0

package/src/react/router/providers/ReactPageProvider.ts

@@ -27,6 +27,8 @@ import {
   type PagePrimitive,
   type PagePrimitiveOptions,
 } from "../primitives/$page.ts";
+import { RootComponentsProvider } from "./RootComponentsProvider.ts";
+import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 
 // -------------------------------------------------------------------------------------------------------------------
 
@@ -65,6 +67,8 @@ export class ReactPageProvider {
   protected readonly log = $logger();
   protected readonly options = $state(reactPageOptions);
   protected readonly alepha = $inject(Alepha);
+  protected readonly rootComponentsProvider = $inject(RootComponentsProvider);
+  protected readonly localeProvider = $inject(RouterLocaleProvider);
   protected readonly pages: PageRoute[] = [];
   protected nextIdCursor = 0;
 
@@ -213,6 +217,12 @@ export class ReactPageProvider {
     }
 
     url = this.compile(url, options.params ?? {});
+    url = url.replace(/\/\/+/g, "/") || "/";
+
+    // Apply the active locale prefix (e.g. `/about` → `/fr/about`) to the path
+    // portion only, before any query string is appended. A no-op unless
+    // `routing: "prefix"` is enabled on the i18n module.
+    url = this.localeProvider.withPrefix(url);
 
     if (options.query) {
       const query = new URLSearchParams(options.query);
@@ -221,7 +231,7 @@ export class ReactPageProvider {
       }
     }
 
-    return url.replace(/\/\/+/g, "/") || "/";
+    return url;
   }
 
   public url(
@@ -240,6 +250,7 @@ export class ReactPageProvider {
       AlephaContext.Provider,
       { value: this.alepha },
       createElement(NestedView, {}, state.layers[0]?.element),
+      ...this.rootComponentsProvider.rootComponents,
     );
 
     if (this.options.strictMode) {

package/src/react/router/providers/ReactServerProvider.ts

@@ -32,6 +32,7 @@ import {
   reactPageOptions,
 } from "./ReactPageProvider.ts";
 import { ReactServerTemplateProvider } from "./ReactServerTemplateProvider.ts";
+import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 import { SSRManifestProvider } from "./SSRManifestProvider.ts";
 
 /**
@@ -66,6 +67,7 @@ export class ReactServerProvider {
   protected readonly serverStaticProvider = $inject(ServerStaticProvider);
   protected readonly serverRouterProvider = $inject(ServerRouterProvider);
   protected readonly ssrManifestProvider = $inject(SSRManifestProvider);
+  protected readonly localeProvider = $inject(RouterLocaleProvider);
 
   /**
    * Cached check for ServerLinksProvider - avoids has() lookup per request.
@@ -148,13 +150,39 @@ export class ReactServerProvider {
           ? new PipelineHandler(rawHandler, serverMiddleware)
           : rawHandler;
 
+        // Canonical (default-locale) route, served unprefixed.
         this.serverRouterProvider.createRoute({
           ...page,
           schema: undefined, // schema is handled by the page primitive provider
+          // A page's `static` is page-shaped (`{ entries }`) and handled by the
+          // page prerender pass — it must not leak into the route's boolean
+          // `static` snapshot flag.
+          static: undefined,
           method: "GET",
           path: page.match,
           handler,
         });
+
+        // Locale-prefixed variants (`/fr/about`, …) point at the SAME handler.
+        // The handler reads the active locale back out of the request URL, so
+        // no extra route param is needed and matching stays native.
+        if (this.localeProvider.enabled) {
+          for (const locale of this.localeProvider.prefixedLocales) {
+            const prefixedPath = this.localeProvider.withPrefix(
+              page.match,
+              locale,
+            );
+            this.log.debug(`+ ${prefixedPath} -> ${page.name} (${locale})`);
+            this.serverRouterProvider.createRoute({
+              ...page,
+              schema: undefined,
+              static: undefined,
+              method: "GET",
+              path: prefixedPath,
+              handler,
+            });
+          }
+        }
       }
     }
   }
@@ -315,6 +343,15 @@ export class ReactServerProvider {
 
       this.log.trace("Rendering page", { name: route.name });
 
+      // Locale-prefix mode: the URL is the source of truth for language.
+      // Record the active locale so links built during SSR (`pathname()`)
+      // carry the prefix, and so hreflang alternates can be emitted.
+      if (this.localeProvider.enabled) {
+        this.localeProvider.current = this.localeProvider.detect(
+          url.pathname,
+        ).locale;
+      }
+
       // Initialize router state
       const state: ReactRouterState = {
         url,
@@ -386,7 +423,20 @@ export class ReactServerProvider {
       }
 
       // Resolve global head for early streaming (htmlAttributes only)
-      const globalHead = this.serverHeadProvider.resolveGlobalHead();
+      let globalHead = this.serverHeadProvider.resolveGlobalHead();
+
+      // In locale-prefix mode the language is known from the URL before any
+      // rendering, so stamp the correct `<html lang>` onto the early head
+      // (per-request copy — never mutate the shared global head).
+      if (this.localeProvider.enabled) {
+        globalHead = {
+          ...globalHead,
+          htmlAttributes: {
+            ...globalHead?.htmlAttributes,
+            lang: this.localeProvider.current,
+          },
+        };
+      }
 
       // Create optimized HTML stream with early head
       const htmlStream = this.templateProvider.createEarlyHtmlStream(
@@ -450,6 +500,44 @@ export class ReactServerProvider {
    * @param state - The router state
    * @returns Render result with redirect or React stream
    */
+  /**
+   * Inject SEO `hreflang` alternate links for the current route when
+   * locale-prefix routing is enabled. Each registered locale gets an absolute
+   * alternate URL (the default locale stays unprefixed), plus an `x-default`
+   * pointing at the unprefixed URL — this is what lets crawlers index every
+   * language. Also sets a best-effort `<html lang>` for the non-streaming /
+   * prerender path; the streamed path's `<html lang>` is finalized on the
+   * client (the early HTML head is flushed before the route is known).
+   *
+   * No-op unless `routing: "prefix"` is enabled on the i18n module.
+   */
+  protected injectLocaleHead(state: ReactRouterState): void {
+    if (!this.localeProvider.enabled) {
+      return;
+    }
+
+    const { origin, search } = state.url;
+    const canonical = this.localeProvider.detect(state.url.pathname).pathname;
+
+    const links = this.localeProvider.locales.map((locale) => ({
+      rel: "alternate",
+      hreflang: locale,
+      href: `${origin}${this.localeProvider.withPrefix(canonical, locale)}${search}`,
+    }));
+    links.push({
+      rel: "alternate",
+      hreflang: "x-default",
+      href: `${origin}${canonical}${search}`,
+    });
+
+    state.head ??= {};
+    state.head.link = [...(state.head.link ?? []), ...links];
+    state.head.htmlAttributes = {
+      ...state.head.htmlAttributes,
+      lang: this.localeProvider.current,
+    };
+  }
+
   protected async renderPage(
     route: PageRoute,
     state: ReactRouterState,
@@ -471,6 +559,9 @@ export class ReactServerProvider {
       state.head.link = [...(state.head.link ?? []), ...preloadLinks];
     }
 
+    // Inject SEO hreflang alternates for locale-prefix routing
+    this.injectLocaleHead(state);
+
     // Render React to stream
 
     const element = this.pageApi.root(state);

package/src/react/router/providers/RootComponentsProvider.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+
+/**
+ * Extension point letting any module contribute root-level React nodes that
+ * render on every page (siblings of the page view, inside AlephaContext).
+ *
+ * A module pushes into `rootComponents` from its `register` hook; the array
+ * is rendered by `ReactPageProvider.root()`. SSR-safe (same element feeds
+ * server render + client hydrate).
+ */
+export class RootComponentsProvider {
+  public rootComponents: ReactNode[] = [];
+}

package/src/react/router/providers/RouterLocaleProvider.ts

@@ -0,0 +1,125 @@
+import { $inject, Alepha } from "alepha";
+
+/**
+ * Generic locale path-prefix mechanism for the router.
+ *
+ * This provider knows nothing about i18n — it only deals with URL path
+ * segments. It is configured by the i18n module (`I18nProvider`) when
+ * `routing: "prefix"` is enabled, which keeps the dependency one-directional
+ * (`i18n → router`) and avoids a module cycle.
+ *
+ * The default locale is served WITHOUT a prefix (`/about` = default,
+ * `/fr/about` = French). The active locale is derived from the current
+ * request/navigation and stored under `alepha.react.router.locale`, so every
+ * URL the router builds (`pathname()`) automatically carries the right prefix.
+ */
+export class RouterLocaleProvider {
+  protected readonly alepha = $inject(Alepha);
+
+  /**
+   * Whether locale path-prefixing is active. Off by default — opt-in via the
+   * i18n module.
+   */
+  public enabled = false;
+
+  /**
+   * The default locale, served without a path prefix (e.g. `"en"` → `/about`).
+   */
+  public defaultLocale = "";
+
+  /**
+   * All known locales, including the default one.
+   */
+  public locales: string[] = [];
+
+  /**
+   * Configure the provider. Called by the i18n module before the SSR routes
+   * are registered.
+   */
+  public configure(options: {
+    enabled?: boolean;
+    defaultLocale?: string;
+    locales?: string[];
+  }): void {
+    if (options.enabled !== undefined) {
+      this.enabled = options.enabled;
+    }
+    if (options.defaultLocale !== undefined) {
+      this.defaultLocale = options.defaultLocale;
+    }
+    if (options.locales !== undefined) {
+      this.locales = options.locales;
+    }
+  }
+
+  /**
+   * Locales that carry a URL prefix — every known locale except the default.
+   */
+  public get prefixedLocales(): string[] {
+    return this.locales.filter((locale) => locale !== this.defaultLocale);
+  }
+
+  /**
+   * Splits a leading locale segment off a pathname.
+   *
+   * - `/fr/about` → `{ locale: "fr", pathname: "/about" }` when `fr` is a
+   *   prefixed locale.
+   * - `/about` → `{ locale: defaultLocale, pathname: "/about" }`.
+   *
+   * When prefixing is disabled the pathname is returned untouched.
+   */
+  public detect(pathname: string): { locale: string; pathname: string } {
+    if (this.enabled) {
+      const first = pathname.split("/")[1];
+      if (first && this.prefixedLocales.includes(first)) {
+        const rest = pathname.slice(first.length + 1);
+        return { locale: first, pathname: this.normalize(rest) };
+      }
+    }
+    return { locale: this.defaultLocale, pathname };
+  }
+
+  /**
+   * Prepends the locale prefix to a pathname when needed. The default locale
+   * (and any unknown/disabled case) returns the pathname unchanged.
+   */
+  public withPrefix(pathname: string, locale: string = this.current): string {
+    if (
+      !this.enabled ||
+      !locale ||
+      locale === this.defaultLocale ||
+      !this.prefixedLocales.includes(locale)
+    ) {
+      return pathname;
+    }
+    return `/${locale}${pathname === "/" ? "" : pathname}`;
+  }
+
+  /**
+   * The active locale, derived from the current request/navigation. Falls back
+   * to the default locale when nothing has been detected.
+   */
+  public get current(): string {
+    return (
+      this.alepha.store.get("alepha.react.router.locale") || this.defaultLocale
+    );
+  }
+
+  public set current(locale: string) {
+    this.alepha.store.set("alepha.react.router.locale", locale);
+  }
+
+  /**
+   * Normalizes a stripped pathname so it always starts with a single slash and
+   * carries no trailing slash (except the root `/`).
+   */
+  protected normalize(pathname: string): string {
+    if (!pathname || pathname === "/") {
+      return "/";
+    }
+    const withLeading = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    return withLeading.length > 1 && withLeading.endsWith("/")
+      ? withLeading.slice(0, -1)
+      : withLeading;
+  }
+}

package/src/react/router/providers/__tests__/RootComponentsProvider.spec.ts

@@ -0,0 +1,15 @@
+import { Alepha } from "alepha";
+import { describe, expect, it } from "vitest";
+import { RootComponentsProvider } from "../RootComponentsProvider.ts";
+
+describe("RootComponentsProvider", () => {
+  it("starts empty and accepts pushed nodes", () => {
+    const alepha = Alepha.create();
+    const provider = alepha.inject(RootComponentsProvider);
+    expect(provider.rootComponents).toEqual([]);
+    provider.rootComponents.push("x" as any);
+    expect(alepha.inject(RootComponentsProvider).rootComponents).toHaveLength(
+      1,
+    );
+  });
+});

package/src/react/router/providers/__tests__/rootComponents.ssr.browser.spec.tsx

@@ -0,0 +1,67 @@
+import { Alepha } from "alepha";
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import type { ReactRouterState } from "../ReactPageProvider.ts";
+import { ReactPageProvider } from "../ReactPageProvider.ts";
+import { RootComponentsProvider } from "../RootComponentsProvider.ts";
+
+/**
+ * Walk a React element tree (non-circular, element children only) and collect
+ * all "data-testid" values found in any element's props.
+ */
+function collectTestIds(node: any, seen = new Set<any>()): string[] {
+  if (!node || typeof node !== "object" || seen.has(node)) {
+    return [];
+  }
+  seen.add(node);
+
+  const ids: string[] = [];
+
+  if (node.props?.["data-testid"]) {
+    ids.push(node.props["data-testid"]);
+  }
+
+  // Children may be a single node or an array
+  const children = node.props?.children;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      ids.push(...collectTestIds(child, seen));
+    }
+  } else if (children) {
+    ids.push(...collectTestIds(children, seen));
+  }
+
+  // Also walk positional children (args 2+ on createElement are spread as props.children
+  // but StrictMode wraps with a single child — unwrap one level manually)
+  return ids;
+}
+
+describe("rootComponents in ReactPageProvider.root", () => {
+  it("includes pushed components in the rendered root element tree", () => {
+    const alepha = Alepha.create();
+    alepha
+      .inject(RootComponentsProvider)
+      .rootComponents.push(
+        createElement("div", { "data-testid": "sigil-marker", key: "m" }),
+      );
+
+    const page = alepha.inject(ReactPageProvider);
+
+    const state: ReactRouterState = {
+      layers: [{ element: null } as any],
+      url: new URL("http://localhost/"),
+      onError: () => undefined as any,
+      params: {},
+      query: {},
+      meta: {},
+      head: {} as any,
+    };
+
+    const element: any = page.root(state);
+
+    // StrictMode wraps the root — unwrap one level
+    const inner = element?.props?.children ?? element;
+    const ids = collectTestIds(inner);
+    expect(ids).toContain("sigil-marker");
+  });
+});

package/src/react/sitemap/__tests__/$sitemap.spec.ts

@@ -0,0 +1,131 @@
+import { Alepha, t } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { $page, AlephaReactRouter } from "alepha/react/router";
+import { ServerRouterProvider } from "alepha/server";
+import { describe, it } from "vitest";
+import { AlephaReactSitemap } from "../index.ts";
+import { $sitemap, type SitemapPrimitive } from "../primitives/$sitemap.ts";
+
+describe("$sitemap", () => {
+  class App {
+    sitemap = $sitemap({ hostname: "https://example.com" });
+
+    home = $page({
+      path: "/",
+      static: true,
+      component: () => "home",
+    });
+
+    about = $page({
+      path: "/about",
+      static: true,
+      component: () => "about",
+    });
+
+    notFound = $page({
+      path: "/*",
+      component: () => "404",
+    });
+
+    github404 = $page({
+      path: "/404",
+      static: true,
+      component: () => "404",
+    });
+
+    blog = $page({
+      path: "/blog/:slug",
+      schema: { params: t.object({ slug: t.text() }) },
+      static: { entries: [{ params: { slug: "hello" } }] },
+      component: () => "post",
+    });
+  }
+
+  const start = async () => {
+    const alepha = Alepha.create()
+      .with(AlephaReactRouter)
+      .with(AlephaReactSitemap);
+    alepha.inject(App);
+    const router = alepha.inject(ServerRouterProvider);
+    await alepha.start();
+    return { alepha, router };
+  };
+
+  const sitemapOf = (alepha: Alepha) =>
+    alepha.primitives("sitemap")[0] as SitemapPrimitive;
+
+  const findSitemapRoute = (router: ServerRouterProvider) =>
+    router.getRoutes().find((route) => route.path === "/sitemap.xml");
+
+  it("registers a static GET /sitemap.xml route", async ({ expect }) => {
+    const { router } = await start();
+    const route = findSitemapRoute(router);
+    expect(route).toBeDefined();
+    expect(route?.method).toBe("GET");
+    expect(route?.static).toBe(true);
+  });
+
+  it("prerenders xml built from the app's pages", async ({ expect }) => {
+    const { alepha } = await start();
+    const { path, body } = sitemapOf(alepha).prerender();
+
+    expect(path).toBe("/sitemap.xml");
+    expect(body).toContain('<?xml version="1.0" encoding="UTF-8"?>');
+    expect(body).toContain("<loc>https://example.com/</loc>");
+    expect(body).toContain("<loc>https://example.com/about</loc>");
+  });
+
+  it("serves application/xml at request time", async ({ expect }) => {
+    const { router } = await start();
+    const route = findSitemapRoute(router)!;
+    const headers: Record<string, string> = {};
+    const reply = {
+      headers,
+      setHeader(name: string, value: string) {
+        headers[name.toLowerCase()] = value;
+        return this;
+      },
+    };
+    const body = await route.handler.run({ reply } as any);
+    expect(headers["content-type"]).toBe("application/xml");
+    expect(String(body)).toContain("<urlset");
+  });
+
+  it("expands parameterized pages via static.entries", async ({ expect }) => {
+    const { alepha } = await start();
+    const { body } = sitemapOf(alepha).prerender();
+    expect(body).toContain("<loc>https://example.com/blog/hello</loc>");
+  });
+
+  it("excludes wildcard and 404 routes", async ({ expect }) => {
+    const { alepha } = await start();
+    const { body } = sitemapOf(alepha).prerender();
+    expect(body).not.toContain("/*");
+    expect(body).not.toContain("/404");
+  });
+
+  it("falls back to PUBLIC_URL, then relative, when no hostname is given", async ({
+    expect,
+  }) => {
+    class RelApp {
+      sitemap = $sitemap();
+      home = $page({ path: "/", static: true, component: () => "home" });
+    }
+    const alepha = Alepha.create()
+      .with(AlephaReactRouter)
+      .with(AlephaReactSitemap);
+    alepha.inject(RelApp);
+    await alepha.start();
+
+    const { body } = sitemapOf(alepha).prerender();
+    expect(body).toContain("<loc>/</loc>");
+  });
+
+  it("uses DateTimeProvider for lastmod (travel-able)", async ({ expect }) => {
+    const { alepha } = await start();
+    const dateTime = alepha.inject(DateTimeProvider);
+    const expected = dateTime.now().format("YYYY-MM-DD");
+    const { body } = sitemapOf(alepha).prerender();
+    expect(body).toContain(`<lastmod>${expected}</lastmod>`);
+  });
+});

package/src/react/sitemap/index.browser.ts

@@ -0,0 +1,21 @@
+import { $module } from "alepha";
+import { $sitemap } from "./primitives/$sitemap.browser.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./primitives/$sitemap.browser.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Sitemap generation for React applications (browser entry).
+ *
+ * The sitemap route only exists server-side, so the browser build ships a
+ * no-op {@link $sitemap}. See the server entry for the real implementation.
+ *
+ * @module alepha.react.sitemap
+ */
+export const AlephaReactSitemap = $module({
+  name: "alepha.react.sitemap",
+  primitives: [$sitemap],
+});

package/src/react/sitemap/index.ts

@@ -0,0 +1,25 @@
+import { $module } from "alepha";
+import { AlephaDateTime } from "alepha/datetime";
+import { AlephaServer } from "alepha/server";
+import { $sitemap } from "./primitives/$sitemap.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./primitives/$sitemap.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Sitemap generation for React applications.
+ *
+ * Exposes the {@link $sitemap} primitive, which serves a `sitemap.xml` built
+ * from the app's `$page` primitives — live at request time and prerendered to a
+ * static file at build time.
+ *
+ * @module alepha.react.sitemap
+ */
+export const AlephaReactSitemap = $module({
+  name: "alepha.react.sitemap",
+  imports: [AlephaServer, AlephaDateTime],
+  primitives: [$sitemap],
+});

package/src/react/sitemap/primitives/$sitemap.browser.ts

@@ -0,0 +1,26 @@
+import { createPrimitive, KIND, Primitive } from "alepha";
+import type { SitemapPrimitiveOptions } from "./$sitemap.ts";
+
+export type { SitemapPrimitiveOptions } from "./$sitemap.ts";
+
+/**
+ * Browser variant of {@link $sitemap}.
+ *
+ * The sitemap is a server-only route — there is nothing to register in the
+ * client bundle, so this is a no-op primitive. It exists only to keep
+ * `$sitemap()` valid as an isomorphic router field; the real implementation
+ * lives in `$sitemap.ts` (server entry).
+ */
+export const $sitemap = (
+  options: SitemapPrimitiveOptions = {},
+): SitemapPrimitive => {
+  return createPrimitive(SitemapPrimitive, options);
+};
+
+export class SitemapPrimitive extends Primitive<SitemapPrimitiveOptions> {
+  protected onInit() {
+    // no-op in the browser
+  }
+}
+
+$sitemap[KIND] = SitemapPrimitive;