alepha 0.22.0 → 0.24.0

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

@@ -13,6 +13,7 @@ import {
   ReactPageProvider,
   type ReactRouterState,
 } from "./ReactPageProvider.ts";
+import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 
 export interface BrowserRoute extends Route {
   page: PageRoute;
@@ -26,6 +27,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
   protected readonly alepha = $inject(Alepha);
   protected readonly pageApi = $inject(ReactPageProvider);
   protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
+  protected readonly localeProvider = $inject(RouterLocaleProvider);
 
   public add(entry: PageRouteEntry) {
     this.pageApi.add(entry);
@@ -75,7 +77,19 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
     });
 
     try {
-      const { route, params } = this.match(pathname);
+      // In locale-prefix mode the URL is the source of truth for language:
+      // strip a leading `/fr`-style segment and remember it (the i18n module
+      // reacts to this to switch dictionaries), then match on the canonical
+      // path so the single page tree still resolves. `state.url` keeps the
+      // full prefixed URL so generated links carry the prefix forward.
+      let matchPathname = pathname;
+      if (this.localeProvider.enabled) {
+        const detected = this.localeProvider.detect(pathname);
+        this.localeProvider.current = detected.locale;
+        matchPathname = detected.pathname;
+      }
+
+      const { route, params } = this.match(matchPathname);
 
       const query: Record<string, string> = {};
       if (search) {

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

@@ -5,10 +5,11 @@ import {
   $state,
   Alepha,
   AlephaError,
+  coerceObject,
   OPTIONS,
   PipelineHandler,
   type TSchema,
-  t,
+  z,
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -27,17 +28,19 @@ import {
   type PagePrimitive,
   type PagePrimitiveOptions,
 } from "../primitives/$page.ts";
+import { RootComponentsProvider } from "./RootComponentsProvider.ts";
+import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 
 // -------------------------------------------------------------------------------------------------------------------
 
 export const reactPageOptions = $atom({
   name: "alepha.react.page.options",
   description: "Configuration options for the React page provider.",
-  schema: t.object({
+  schema: z.object({
     /**
      * Enable React StrictMode wrapper.
      */
-    strictMode: t.boolean({ default: true }),
+    strictMode: z.boolean().default(true),
     /**
      * RegExp pattern (as string) to detect file-like URLs (e.g. /hello.txt, /wp-login.php).
      * When a request hits the catch-all wildcard route and matches this pattern,
@@ -47,7 +50,7 @@ export const reactPageOptions = $atom({
      *
      * @default "\\.[a-zA-Z0-9]{1,10}$"
      */
-    staticFilePattern: t.string(),
+    staticFilePattern: z.string(),
   }),
   default: {
     strictMode: true,
@@ -65,6 +68,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 +218,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 +232,7 @@ export class ReactPageProvider {
       }
     }
 
-    return url.replace(/\/\/+/g, "/") || "/";
+    return url;
   }
 
   public url(
@@ -240,6 +251,7 @@ export class ReactPageProvider {
       AlephaContext.Provider,
       { value: this.alepha },
       createElement(NestedView, {}, state.layers[0]?.element),
+      ...this.rootComponentsProvider.rootComponents,
     );
 
     if (this.options.strictMode) {
@@ -253,15 +265,16 @@ export class ReactPageProvider {
     schema?: TSchema,
     value?: any,
   ): any => {
-    if (t.schema.isObject(schema) && typeof value === "object") {
+    if (z.schema.isObject(schema) && typeof value === "object") {
       for (const key in schema.properties) {
-        if (
-          t.schema.isObject(schema.properties[key]) &&
-          typeof value[key] === "string"
-        ) {
+        // Peel optional/nullable/default wrappers so a field declared as
+        // `z.object(...).optional()` is still recognised as an object whose
+        // JSON-encoded query value needs parsing.
+        const propSchema = z.schema.unwrap(schema.properties[key]);
+        if (z.schema.isObject(propSchema) && typeof value[key] === "string") {
           try {
             value[key] = this.alepha.codec.decode(
-              schema.properties[key],
+              propSchema,
               decodeURIComponent(value[key]),
             );
           } catch (e) {
@@ -302,7 +315,13 @@ export class ReactPageProvider {
       try {
         this.convertStringObjectToObject(route.schema?.query, state.query);
         config.query = route.schema?.query
-          ? this.alepha.codec.decode(route.schema.query, state.query)
+          ? this.alepha.codec.decode(
+              route.schema.query,
+              // Query params arrive as strings from the URL; coerce declared
+              // scalar fields (number/integer/boolean) to their schema type
+              // before strict validation, mirroring the HTTP server boundary.
+              coerceObject(route.schema.query, state.query),
+            )
           : {};
       } catch (e) {
         it.error = e instanceof Error ? e : new Error(String(e));
@@ -311,7 +330,13 @@ export class ReactPageProvider {
 
       try {
         config.params = route.schema?.params
-          ? this.alepha.codec.decode(route.schema.params, state.params)
+          ? this.alepha.codec.decode(
+              route.schema.params,
+              // URL path params arrive as strings; coerce declared scalar
+              // fields (number/integer/boolean) to their schema type before
+              // strict validation, mirroring `query` above and the HTTP server.
+              coerceObject(route.schema.params, state.params),
+            )
           : {};
       } catch (e) {
         it.error = e instanceof Error ? e : new Error(String(e));

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

@@ -10,7 +10,7 @@ import {
   OPTIONS,
   PipelineHandler,
   type Static,
-  t,
+  z,
 } from "alepha";
 import { $logger } from "alepha/logger";
 import { ServerHeadProvider } from "alepha/react/head";
@@ -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);
@@ -595,13 +686,13 @@ export class ReactServerProvider {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-const envSchema = t.object({
-  REACT_SSR_ENABLED: t.optional(
-    t.boolean({
-      description:
-        "Enable or disable server-side rendering (SSR) for React pages. When set to false, pages are rendered client-side only.",
-    }),
-  ),
+const envSchema = z.object({
+  REACT_SSR_ENABLED: z
+    .boolean()
+    .describe(
+      "Enable or disable server-side rendering (SSR) for React pages. When set to false, pages are rendered client-side only.",
+    )
+    .optional(),
 });
 
 declare module "alepha" {
@@ -622,13 +713,11 @@ export const DEFAULT_STATIC_FILE_PATTERN = "\\.[a-zA-Z0-9]{1,10}$";
 
 export const reactServerOptions = $atom({
   name: "alepha.react.server.options",
-  schema: t.object({
-    publicDir: t.string(),
-    staticServer: t.object({
-      disabled: t.boolean(),
-      path: t.string({
-        description: "URL path where static files will be served.",
-      }),
+  schema: z.object({
+    publicDir: z.string(),
+    staticServer: z.object({
+      disabled: z.boolean(),
+      path: z.string().describe("URL path where static files will be served."),
     }),
   }),
   default: {

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