alepha 0.21.2 → 0.23.0

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;

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

@@ -0,0 +1,196 @@
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { type ServerRequest, ServerRouterProvider } from "alepha/server";
+
+/**
+ * Expose a `sitemap.xml` generated from the application's `$page` primitives.
+ *
+ * Registers a `GET /sitemap.xml` route that reads every registered page at
+ * request time and emits a standard XML sitemap. Marked `static` by default, so
+ * the build prerenders it to `dist/public/sitemap.xml` for static deployments —
+ * while SSR runtimes also serve it live.
+ *
+ * The hostname comes from `options.hostname`, falling back to `PUBLIC_URL`, then
+ * to `""` (relative URLs).
+ *
+ * @example
+ * ```ts
+ * import { $sitemap } from "alepha/react/sitemap";
+ *
+ * class AppRouter {
+ *   sitemap = $sitemap();
+ * }
+ * ```
+ */
+export const $sitemap = (
+  options: SitemapPrimitiveOptions = {},
+): SitemapPrimitive => {
+  return createPrimitive(SitemapPrimitive, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface SitemapPrimitiveOptions {
+  /**
+   * Absolute base URL used to build `<loc>` entries (e.g. "https://alepha.dev").
+   *
+   * Defaults to `PUBLIC_URL`, then to `""` (relative URLs).
+   */
+  hostname?: string;
+
+  /**
+   * Route path the sitemap is served at.
+   *
+   * @default "/sitemap.xml"
+   */
+  path?: string;
+
+  /**
+   * Prerender the sitemap to a static file at build time.
+   *
+   * @default true
+   */
+  static?: boolean;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class SitemapPrimitive extends Primitive<SitemapPrimitiveOptions> {
+  protected readonly router = $inject(ServerRouterProvider);
+  protected readonly dateTime = $inject(DateTimeProvider);
+
+  protected onInit() {
+    this.router.createRoute({
+      method: "GET",
+      path: this.options.path ?? "/sitemap.xml",
+      static: this.options.static ?? true,
+      silent: true,
+      handler: (request: ServerRequest) => {
+        request.reply.setHeader("content-type", "application/xml");
+        return this.buildSitemap();
+      },
+    });
+  }
+
+  /**
+   * Render the sitemap to its path and body. Used by the build to snapshot the
+   * sitemap to a static file.
+   */
+  public prerender(): { path: string; body: string } {
+    return {
+      path: this.options.path ?? "/sitemap.xml",
+      body: this.buildSitemap(),
+    };
+  }
+
+  /**
+   * Build the sitemap XML from the application's page primitives.
+   */
+  protected buildSitemap(): string {
+    const hostname =
+      this.options.hostname ?? String(this.alepha.env.PUBLIC_URL ?? "");
+    const pages = this.getSitemapPages();
+    return this.generateSitemapFromPages(pages, hostname);
+  }
+
+  /**
+   * Select the pages that should appear in the sitemap.
+   *
+   * Excludes layout pages (with `children`), wildcard paths, and `/404`.
+   * Parameterized pages are included only when they declare `static.entries`.
+   */
+  protected getSitemapPages(): any[] {
+    const pages = this.alepha.primitives("page") as any[];
+    return pages.filter((page) => {
+      const options = page.options;
+      const path: string = options.path ?? "";
+      if (options.children) {
+        return false;
+      }
+      if (path.includes("*")) {
+        return false;
+      }
+      if (path === "/404") {
+        return false;
+      }
+      if (!options.schema?.params) {
+        return true;
+      }
+      if (
+        options.static &&
+        typeof options.static === "object" &&
+        options.static.entries
+      ) {
+        return true;
+      }
+      return false;
+    });
+  }
+
+  protected generateSitemapFromPages(pages: any[], baseUrl: string): string {
+    const urls: string[] = [];
+    const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+    for (const page of pages) {
+      const options = page.options;
+
+      if (!options.schema?.params) {
+        const path = options.path || "";
+        const url = `${normalizedBaseUrl}${path === "" ? "/" : path}`;
+        urls.push(url);
+      } else if (
+        options.static &&
+        typeof options.static === "object" &&
+        options.static.entries
+      ) {
+        for (const entry of options.static.entries) {
+          const path = this.buildPathFromParams(
+            options.path || "",
+            entry.params || {},
+          );
+          const url = `${normalizedBaseUrl}${path}`;
+          urls.push(url);
+        }
+      }
+    }
+
+    return this.buildSitemapXml(urls);
+  }
+
+  protected buildPathFromParams(
+    pathPattern: string,
+    params: Record<string, any>,
+  ): string {
+    let path = pathPattern;
+    for (const [key, value] of Object.entries(params)) {
+      path = path.replace(`:${key}`, String(value));
+    }
+    return path || "/";
+  }
+
+  protected buildSitemapXml(urls: string[]): string {
+    const lastMod = this.dateTime.now().format("YYYY-MM-DD");
+    const urlEntries = urls
+      .map(
+        (url) =>
+          `  <url>\n    <loc>${this.escapeXml(url)}</loc>\n    <lastmod>${lastMod}</lastmod>\n  </url>`,
+      )
+      .join("\n");
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlEntries}
+</urlset>`;
+  }
+
+  protected escapeXml(str: string): string {
+    return str
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+}
+
+$sitemap[KIND] = SitemapPrimitive;

package/src/react/ui/services/SchemaControl.ts

@@ -1,9 +1,8 @@
 import type { FormModel } from "alepha/react/form";
 
 /**
- * Schema-bound metadata read by `<Control>` (in `@alepha/ui-registry`) to
- * configure how a field renders. Place under `$control` on any TypeBox
- * schema option.
+ * Schema-bound metadata read by `<Control>` (in `@alepha/ui`) to configure
+ * how a field renders. Place under `$control` on any TypeBox schema option.
  *
  * Two forms:
  *
@@ -201,7 +200,7 @@ export const resolveSchemaControl = (
 declare module "typebox" {
   interface TSchemaOptions {
     /**
-     * UI metadata read by `<Control>` from `@alepha/ui-registry`. See
+     * UI metadata read by `<Control>` from `@alepha/ui`. See
      * {@link SchemaControl}.
      */
     $control?: SchemaControlOption;

package/src/server/auth/__tests__/appleClientSecret.spec.ts

@@ -0,0 +1,34 @@
+import {
+  decodeJwt,
+  decodeProtectedHeader,
+  exportPKCS8,
+  generateKeyPair,
+} from "jose";
+import { describe, expect, it } from "vitest";
+import { signAppleClientSecret } from "../helpers/appleClientSecret.ts";
+
+describe("apple client secret", () => {
+  it("signs an ES256 JWT with the Apple-required claims + kid header", async () => {
+    const { privateKey } = await generateKeyPair("ES256", {
+      crv: "P-256",
+      extractable: true,
+    });
+    const pem = await exportPKCS8(privateKey);
+    const secret = await signAppleClientSecret({
+      privateKeyPem: pem,
+      teamId: "TEAM123456",
+      serviceId: "club.alepha.signin",
+      keyId: "KEY1234567",
+    });
+    const claims = decodeJwt(secret);
+    expect(claims.iss).toBe("TEAM123456");
+    expect(claims.sub).toBe("club.alepha.signin");
+    expect(claims.aud).toBe("https://appleid.apple.com");
+    expect(typeof claims.exp).toBe("number");
+
+    // Apple requires ES256 + the Key ID in the protected header.
+    const header = decodeProtectedHeader(secret);
+    expect(header.alg).toBe("ES256");
+    expect(header.kid).toBe("KEY1234567");
+  });
+});