alepha 0.20.2 → 0.20.4

package/src/react/router/__tests__/ssr.spec.tsx

@@ -0,0 +1,339 @@
+import { Alepha } from "alepha";
+import { beforeEach, describe, test } from "vitest";
+import { $page, NestedView } from "../index.ts";
+
+describe("$page ssr option", () => {
+  let alepha: Alepha;
+
+  beforeEach(() => {
+    alepha = Alepha.create();
+  });
+
+  test("default (no ssr option) renders server-side", async ({ expect }) => {
+    class App {
+      home = $page({
+        path: "/",
+        component: () => "Home content",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.home.render();
+    expect(rendered.html).toBe("Home content");
+  });
+
+  test("ssr: true renders server-side", async ({ expect }) => {
+    class App {
+      home = $page({
+        path: "/",
+        ssr: true,
+        component: () => "Home content",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.home.render();
+    expect(rendered.html).toBe("Home content");
+  });
+
+  test("ssr: false skips server rendering on a leaf page", async ({
+    expect,
+  }) => {
+    class App {
+      home = $page({
+        path: "/",
+        ssr: false,
+        component: () => "Home content",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.home.render();
+    expect(rendered.html).toBe("");
+  });
+
+  test("ssr: false still runs the loader server-side", async ({ expect }) => {
+    let loaderCalls = 0;
+
+    class App {
+      home = $page({
+        path: "/",
+        ssr: false,
+        loader: () => {
+          loaderCalls += 1;
+          return { msg: "loaded" };
+        },
+        component: ({ msg }: { msg: string }) => msg,
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.home.render();
+    expect(rendered.html).toBe("");
+    expect(loaderCalls).toBe(1);
+  });
+
+  test("parent ssr: false cascades to child without override", async ({
+    expect,
+  }) => {
+    class App {
+      parent = $page({
+        path: "/parent",
+        ssr: false,
+        component: () => (
+          <>
+            Parent
+            <NestedView />
+          </>
+        ),
+      });
+
+      child = $page({
+        path: "/child",
+        parent: this.parent,
+        component: () => "Child",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.child.render();
+    expect(rendered.html).toBe("");
+  });
+
+  test("child ssr: true overrides parent ssr: false (both render)", async ({
+    expect,
+  }) => {
+    class App {
+      parent = $page({
+        path: "/parent",
+        ssr: false,
+        component: () => (
+          <>
+            Parent
+            <NestedView />
+          </>
+        ),
+      });
+
+      child = $page({
+        path: "/child",
+        parent: this.parent,
+        ssr: true,
+        component: () => "Child",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.child.render();
+    expect(rendered.html).toBe("Parent<!-- -->Child");
+  });
+
+  test("child ssr: false overrides parent ssr: true (skip everything)", async ({
+    expect,
+  }) => {
+    class App {
+      parent = $page({
+        path: "/parent",
+        ssr: true,
+        component: () => (
+          <>
+            Parent
+            <NestedView />
+          </>
+        ),
+      });
+
+      child = $page({
+        path: "/child",
+        parent: this.parent,
+        ssr: false,
+        component: () => "Child",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.child.render();
+    expect(rendered.html).toBe("");
+  });
+
+  test("siblings: one inherits parent ssr: false, the other overrides", async ({
+    expect,
+  }) => {
+    class App {
+      parent = $page({
+        path: "/parent",
+        ssr: false,
+        component: () => (
+          <>
+            Parent
+            <NestedView />
+          </>
+        ),
+      });
+
+      home = $page({
+        path: "/home",
+        parent: this.parent,
+        ssr: true,
+        component: () => "Home",
+      });
+
+      about = $page({
+        path: "/about",
+        parent: this.parent,
+        component: () => "About",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const home = await app.home.render();
+    expect(home.html).toBe("Parent<!-- -->Home");
+
+    const about = await app.about.render();
+    expect(about.html).toBe("");
+  });
+
+  test("3-level chain: nearest explicit ssr wins (leaf decides)", async ({
+    expect,
+  }) => {
+    class App {
+      grand = $page({
+        path: "/grand",
+        ssr: false,
+        component: () => (
+          <>
+            Grand
+            <NestedView />
+          </>
+        ),
+      });
+
+      // no ssr → inherits from grand → false (default for descendants)
+      mid = $page({
+        path: "/mid",
+        parent: this.grand,
+        component: () => (
+          <>
+            Mid
+            <NestedView />
+          </>
+        ),
+      });
+
+      // explicit ssr: true → overrides inherited false
+      leaf = $page({
+        path: "/leaf",
+        parent: this.mid,
+        ssr: true,
+        component: () => "Leaf",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.leaf.render();
+    expect(rendered.html).toBe("Grand<!-- -->Mid<!-- -->Leaf");
+  });
+
+  test("3-level chain: middle ssr: true does not affect leaf without explicit value", async ({
+    expect,
+  }) => {
+    class App {
+      grand = $page({
+        path: "/grand",
+        ssr: false,
+        component: () => (
+          <>
+            Grand
+            <NestedView />
+          </>
+        ),
+      });
+
+      // explicit true overrides grand's false for itself + descendants default
+      mid = $page({
+        path: "/mid",
+        parent: this.grand,
+        ssr: true,
+        component: () => (
+          <>
+            Mid
+            <NestedView />
+          </>
+        ),
+      });
+
+      // no ssr → walks up: mid.ssr === true → leaf renders
+      leaf = $page({
+        path: "/leaf",
+        parent: this.mid,
+        component: () => "Leaf",
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.leaf.render();
+    expect(rendered.html).toBe("Grand<!-- -->Mid<!-- -->Leaf");
+  });
+
+  test("parent ssr: false: loaders still run for parent and child", async ({
+    expect,
+  }) => {
+    let parentLoaderCalls = 0;
+    let childLoaderCalls = 0;
+
+    class App {
+      parent = $page({
+        path: "/parent",
+        ssr: false,
+        loader: () => {
+          parentLoaderCalls += 1;
+          return { fromParent: "p" };
+        },
+        component: () => (
+          <>
+            Parent
+            <NestedView />
+          </>
+        ),
+      });
+
+      child = $page({
+        path: "/child",
+        parent: this.parent,
+        loader: ({ fromParent }) => {
+          childLoaderCalls += 1;
+          return { fromChild: `${fromParent}-c` };
+        },
+        component: ({ fromChild }: { fromChild: string }) => fromChild,
+      });
+    }
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const rendered = await app.child.render();
+    expect(rendered.html).toBe("");
+    expect(parentLoaderCalls).toBe(1);
+    expect(childLoaderCalls).toBe(1);
+  });
+});

package/src/react/router/primitives/$page.ts

@@ -10,7 +10,6 @@ import {
   type TSchema,
 } from "alepha";
 import { $cache } from "alepha/cache";
-import type { ClientOnlyProps } from "alepha/react";
 import type { Head } from "alepha/react/head";
 import type { ServerRequest } from "alepha/server";
 import type { FC, ReactNode } from "react";
@@ -297,10 +296,35 @@ export interface PagePrimitiveOptions<
       };
 
   /**
-   * If true, force the page to be rendered only on the client-side (browser).
-   * It uses the `<ClientOnly/>` component to render the page.
+   * Enable or disable server-side rendering for this page.
+   *
+   * - `true` (default): the page component is rendered on the server and
+   *   hydrated on the client.
+   * - `false`: the loader still runs on the server (so data is preloaded and
+   *   serialized for hydration), but the component is rendered only on the
+   *   client. The server emits no HTML for this page.
+   *
+   * **Decided at the leaf, inherited as default by descendants.**
+   *
+   * The effective value is determined by the matched leaf page: walk up the
+   * parent chain and use the nearest explicit `ssr` value. Setting
+   * `ssr: false` on a parent therefore acts as the default for its children;
+   * a child can override with `ssr: true`.
+   *
+   * Skipping rendering while keeping the loader is the recommended strategy
+   * for CPU-constrained server environments (e.g. Cloudflare Workers) and
+   * heavy admin/dashboard views where SSR provides little SEO value.
+   *
+   * @example
+   * ```ts
+   * root  = $page({ ssr: false });               // default for children
+   * home  = $page({ parent: root, ssr: true });  // overrides → SSR
+   * about = $page({ parent: root });             // inherits  → no SSR
+   * ```
+   *
+   * @default true
    */
-  client?: boolean | ClientOnlyProps;
+  ssr?: boolean;
 
   /**
    * Called before the server response is sent to the client. (server only)

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

@@ -28,9 +28,20 @@ export const reactBrowserOptions = $atom({
   name: "alepha.react.browser.options",
   schema: t.object({
     scrollRestoration: t.enum(["top", "manual"]), // TODO: must be per page?
+    /**
+     * Intercept clicks on plain `<a href="/...">` anchors and route them
+     * through the SPA router, so authors don't need `<Link>` everywhere
+     * (notably for SSR/Markdown HTML rendered as raw markup).
+     *
+     * Skips: modifier keys, non-primary mouse buttons, `target` other than
+     * `_self`, `download`, `data-no-router`, non-http(s) schemes, hash-only
+     * hrefs, external origins, and clicks already `defaultPrevented`.
+     */
+    interceptAnchorClicks: t.boolean({ default: true }),
   }),
   default: {
     scrollRestoration: "top" as const,
+    interceptAnchorClicks: true,
   },
 });
 
@@ -325,8 +336,70 @@ export class ReactBrowserProvider {
 
         this.render();
       });
+
+      this.attachAnchorInterceptor();
     },
   });
+
+  /**
+   * Attach a delegated click listener that routes plain `<a href="/...">`
+   * clicks through the SPA router. Returns a detach function (used in tests).
+   *
+   * Bails out on modifier keys, non-primary mouse buttons, `target`, `download`,
+   * `data-no-router`, hash-only/external/non-http hrefs, and already-prevented
+   * events. Honors the runtime `interceptAnchorClicks` flag.
+   */
+  protected attachAnchorInterceptor(): () => void {
+    const onClick = (ev: MouseEvent) => {
+      if (!this.options.interceptAnchorClicks) return;
+      if (ev.defaultPrevented) return;
+      if (ev.button !== 0) return;
+      if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+
+      const node = ev.target as Element | null;
+      const a = node?.closest?.("a");
+      if (!a) return;
+
+      if (a.hasAttribute("download")) return;
+      if (a.hasAttribute("data-no-router")) return;
+
+      const target = a.getAttribute("target");
+      if (target && target !== "_self") return;
+
+      const href = a.getAttribute("href");
+      if (!href) return;
+      if (href.startsWith("#")) return;
+      if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+        // absolute scheme: only intercept if it points at our own origin
+        let url: URL;
+        try {
+          url = new URL(href);
+        } catch {
+          return;
+        }
+        if (url.origin !== this.location.origin) return;
+        ev.preventDefault();
+        const path = url.pathname + url.search + url.hash;
+        this.push(this.stripBase(path)).catch((e) => this.log.error(e));
+        return;
+      }
+
+      ev.preventDefault();
+      const url = new URL(href, this.location.href);
+      const path = url.pathname + url.search + url.hash;
+      this.push(this.stripBase(path)).catch((e) => this.log.error(e));
+    };
+
+    this.document.addEventListener("click", onClick);
+    return () => this.document.removeEventListener("click", onClick);
+  }
+
+  protected stripBase(path: string): string {
+    if (this.base && path.startsWith(this.base)) {
+      return path.slice(this.base.length) || "/";
+    }
+    return path;
+  }
 }
 
 // ---------------------------------------------------------------------------------------------------------------------

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

@@ -52,7 +52,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
     previous: PreviousLayerData[] = [],
     meta = {},
     isStale: () => boolean = () => false,
-  ): Promise<string | void> {
+  ): Promise<string | undefined> {
     const { pathname, search } = url;
 
     const entry: Partial<ReactRouterState> = {

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

@@ -470,6 +470,14 @@ export class ReactPageProvider {
       }
     }
 
+    // If the matched leaf opts out of SSR (own value or inherited from
+    // parents), wrap the root layer in ClientOnly so the server emits no
+    // HTML for the route chain. Loaders have already run above.
+    if (state.layers.length > 0 && !this.isSSR(route)) {
+      const rootLayer = state.layers[0];
+      rootLayer.element = createElement(ClientOnly, {}, rootLayer.element);
+    }
+
     return { state };
   }
 
@@ -598,14 +606,6 @@ export class ReactPageProvider {
   ): ReactNode {
     view ??= this.renderEmptyView();
 
-    const element = page.client
-      ? createElement(
-          ClientOnly,
-          typeof page.client === "object" ? page.client : {},
-          view,
-        )
-      : view;
-
     return createElement(
       RouterLayerContext.Provider,
       {
@@ -616,10 +616,28 @@ export class ReactPageProvider {
             this.getErrorHandler(page) ?? ((error) => this.renderError(error)),
         },
       },
-      element,
+      view,
     );
   }
 
+  /**
+   * Resolve the effective `ssr` value for a route by walking up the parent
+   * chain. Returns the nearest explicit `ssr` value, defaulting to `true`.
+   *
+   * The decision is made at the leaf: a parent's `ssr` only acts as a default
+   * for descendants that did not set their own value.
+   */
+  public isSSR(route: PageRoute): boolean {
+    let current: PageRoute | undefined = route;
+    while (current) {
+      if (typeof current.ssr === "boolean") {
+        return current.ssr;
+      }
+      current = current.parent;
+    }
+    return true;
+  }
+
   protected map(
     pages: Array<PagePrimitive>,
     target: PagePrimitive,

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

@@ -65,7 +65,7 @@ export class ReactPreloadProvider {
     handler: ({ response }) => {
       // Only add to HTML responses (SSR pages)
       const contentType = response.headers["content-type"];
-      if (!contentType || !contentType.includes("text/html")) {
+      if (!contentType?.includes("text/html")) {
         return;
       }
 

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

@@ -306,6 +306,7 @@ export class ReactServerProvider {
       // Skip SSR for file-like URLs hitting the catch-all wildcard.
       // Bots and crawlers often probe paths like /hello.txt, /wp-login.php, etc.
       // Rendering a full React page for these is wasteful — return a plain 404 instead.
+      // biome-ignore lint/complexity/useOptionalChain: staticFilePattern is `false | RegExp`; optional chaining doesn't narrow `false`
       if (staticFilePattern && staticFilePattern.test(url.pathname)) {
         reply.status = 404;
         reply.headers["content-type"] = "text/plain";

package/src/react/ui/atoms/uiThemeListAtom.ts

@@ -0,0 +1,36 @@
+import { $atom, type Static, t } from "alepha";
+
+/**
+ * Available themes the user can pick from. Apps populate this atom on boot
+ * (e.g. `alepha.store.set(uiThemeListAtom, MY_THEMES)`); UI consumers like
+ * `<ButtonTheme/>` read it to render a picker. The selected theme id is
+ * persisted separately in `uiAtom.theme`.
+ *
+ * Defaults to a single `"default"` entry so the registry stays usable when
+ * an app doesn't declare its own list.
+ */
+export const uiThemeListAtom = $atom({
+  name: "alepha.react.ui.themes",
+  schema: t.array(
+    t.object({
+      /** Stable id stored in `uiAtom.theme`. Mapped to a CSS class on `<html>`. */
+      id: t.string(),
+      /** Human-readable label shown in the picker. */
+      label: t.string(),
+      /**
+       * Optional 4-color preview swatch in 2×2 order (TL, TR, BL, BR). Any
+       * CSS-valid color string.
+       */
+      swatch: t.optional(t.array(t.string(), { minItems: 4, maxItems: 4 })),
+      /**
+       * Optional stylesheet URL (typically Google Fonts) loaded lazily when
+       * the theme is selected.
+       */
+      fontHref: t.optional(t.string()),
+    }),
+  ),
+  default: [{ id: "default", label: "Default" }],
+});
+
+export type UiThemeList = Static<typeof uiThemeListAtom.schema>;
+export type UiTheme = UiThemeList[number];

package/src/react/ui/index.ts

@@ -1,14 +1,18 @@
 import { $module } from "alepha";
 import type { UiState } from "./atoms/uiAtom.ts";
+import type { UiThemeList } from "./atoms/uiThemeListAtom.ts";
+import { uiThemeListAtom } from "./atoms/uiThemeListAtom.ts";
 import { UiPersistence } from "./services/UiPersistence.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./atoms/uiAtom.ts";
+export * from "./atoms/uiThemeListAtom.ts";
 export * from "./components/ColorScheme.tsx";
 export * from "./hooks/useColorMode.ts";
 export * from "./hooks/useSidebarState.ts";
 export * from "./hooks/useTheme.ts";
+export * from "./services/SchemaControl.ts";
 export * from "./services/UiPersistence.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -16,6 +20,7 @@ export * from "./services/UiPersistence.ts";
 declare module "alepha" {
   export interface State {
     "alepha.react.ui": UiState;
+    "alepha.react.ui.themes": UiThemeList;
   }
 }
 
@@ -31,5 +36,6 @@ declare module "alepha" {
  */
 export const AlephaReactUi = $module({
   name: "alepha.react.ui",
+  atoms: [uiThemeListAtom],
   services: [UiPersistence],
 });