alepha 0.20.3 → 0.20.4

package/src/react/form/services/parseField.ts

@@ -45,6 +45,12 @@ export interface FieldMeta {
   constraints: FieldConstraints;
   testId?: string;
   schema: TSchema;
+  /**
+   * Raw `$control` value from the schema, untyped here. The UI layer
+   * (`alepha/react/ui`) provides the strict {@link SchemaControl} type and
+   * a `resolveSchemaControl` helper to evaluate the function form.
+   */
+  control?: unknown;
 }
 
 export interface ParseFieldOptions {
@@ -77,6 +83,7 @@ export const parseField = (
     pattern?: string;
     properties?: unknown;
     items?: { properties?: unknown };
+    $control?: unknown;
   };
 
   const label =
@@ -132,6 +139,7 @@ export const parseField = (
       | string
       | undefined,
     schema: input.schema,
+    control: schema.$control,
   };
 };
 

package/src/react/i18n/providers/I18nProvider.ts

@@ -230,15 +230,21 @@ export class I18nProvider<
     return value;
   };
 
+  /**
+   * Look up `key` in the registered dictionaries. The `(string & {})` arm
+   * keeps autocomplete for the typed dictionary keys while allowing shared
+   * library components to pass arbitrary string keys (with a `default`
+   * fallback) without casting to `as never`.
+   */
   public readonly tr = (
-    key: keyof ServiceDictionary<S>[K],
+    key: keyof ServiceDictionary<S>[K] | (string & {}),
     options: {
       args?: string[];
       default?: string;
     } = {},
   ) => {
     const translation = this.translate(key as string, options.args || []);
-    if (translation === key && options.default) {
+    if (translation === (key as string) && options.default) {
       return options.default;
     }
     return translation;

package/src/react/router/__tests__/$page.spec.tsx

@@ -419,22 +419,6 @@ describe("$page primitive tests", () => {
     expect(await app.staticPage.fetch().then((it) => it.html)).toBe(html);
   });
 
-  test("$page - client-side only rendering", async ({ expect }) => {
-    class App {
-      clientOnly = $page({
-        path: "/client",
-        client: true,
-        component: () => "Client only",
-      });
-    }
-
-    const app = alepha.inject(App);
-    await alepha.start();
-
-    const clientRendered = await app.clientOnly.fetch();
-    expect(clientRendered.html).toBe("");
-  });
-
   test("$page - server response handler", async ({ expect }) => {
     const mockHandler = vi.fn();
 

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/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/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],
 });