alepha 0.20.3 → 0.20.5

package/src/react/core/hooks/useQuery.ts

@@ -0,0 +1,153 @@
+import type { Async } from "alepha";
+import type { DurationLike } from "alepha/datetime";
+import { type DependencyList, useCallback, useState } from "react";
+import type { ActionContext } from "./useAction.ts";
+import { useAction } from "./useAction.ts";
+
+/**
+ * Hook for declarative data fetching with automatic execution and refetch.
+ *
+ * Thin wrapper over {@link useAction}: it pre-applies `runOnInit: true`,
+ * exposes the last result as `data`, and provides a stable `refetch()` to
+ * re-run the query on demand. For optimistic mutations and side-effects,
+ * use {@link useAction} directly — `useQuery` is for the read path.
+ *
+ * Caching, request deduplication, and AbortSignal cancellation come from
+ * `useAction` + `HttpClient`. There is no separate cache layer — pass
+ * `localCache` to your `HttpClient.fetch()`/`fetchAction()` call inside
+ * the query handler if you want per-call caching.
+ *
+ * @example Basic
+ * ```tsx
+ * const client = useInject(HttpClient);
+ * const { data, loading, error, refetch } = useQuery({
+ *   handler: async ({ signal }) => {
+ *     const res = await client.fetch("/api/users", { request: { signal } });
+ *     return res.data;
+ *   },
+ * }, []);
+ * ```
+ *
+ * @example Re-fetch when a dep changes
+ * ```tsx
+ * const { data } = useQuery({
+ *   handler: async () => api.getUser(userId),
+ * }, [userId]);
+ * ```
+ *
+ * @example Polling
+ * ```tsx
+ * const { data } = useQuery({
+ *   handler: async () => api.getStatus(),
+ *   runEvery: [5, "seconds"],
+ * }, []);
+ * ```
+ */
+export function useQuery<Result>(
+  options: UseQueryOptions<Result>,
+  deps: DependencyList,
+): UseQueryReturn<Result> {
+  const [data, setData] = useState<Result | undefined>(options.initialData);
+
+  const action = useAction<[], Result>(
+    {
+      id: options.id,
+      handler: options.handler,
+      runOnInit: options.enabled !== false,
+      runEvery: options.runEvery,
+      debounce: options.debounce,
+      onError: options.onError,
+      onSuccess: async (result) => {
+        setData(result);
+        if (options.onSuccess) {
+          await options.onSuccess(result);
+        }
+      },
+    },
+    deps,
+  );
+
+  const refetch = useCallback(() => action.run(), [action.run]);
+
+  return {
+    data,
+    loading: action.loading,
+    error: action.error,
+    refetch,
+    cancel: action.cancel,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface UseQueryOptions<Result> {
+  /**
+   * Async query handler. Receives an {@link ActionContext} with an
+   * AbortSignal that fires on unmount, dependency change, or `cancel()`.
+   */
+  handler: (context: ActionContext) => Async<Result>;
+
+  /**
+   * Optional identifier (used in lifecycle events for debugging/analytics).
+   */
+  id?: string;
+
+  /**
+   * If `false`, skip automatic execution on mount and dep change. Use
+   * `refetch()` to trigger manually. Defaults to `true`.
+   */
+  enabled?: boolean;
+
+  /**
+   * Initial value for `data` before the first successful fetch.
+   */
+  initialData?: Result;
+
+  /**
+   * Re-run periodically. See {@link useAction} `runEvery`.
+   */
+  runEvery?: DurationLike;
+
+  /**
+   * Debounce delay in milliseconds. See {@link useAction} `debounce`.
+   */
+  debounce?: number;
+
+  /**
+   * Called on success with the resolved value.
+   */
+  onSuccess?: (result: Result) => void | Promise<void>;
+
+  /**
+   * Custom error handler. If provided, prevents default error re-throw.
+   */
+  onError?: (error: Error) => void | Promise<void>;
+}
+
+export interface UseQueryReturn<Result> {
+  /**
+   * The last successful result. `undefined` until the first fetch resolves
+   * (or the value of `initialData` if provided).
+   */
+  data: Result | undefined;
+
+  /**
+   * Loading state — `true` while a fetch is in flight.
+   */
+  loading: boolean;
+
+  /**
+   * Error from the last failed fetch, if any.
+   */
+  error?: Error;
+
+  /**
+   * Re-run the query. The previous in-flight request, if any, is aborted.
+   */
+  refetch: () => Promise<Result | undefined>;
+
+  /**
+   * Abort the in-flight request without scheduling another.
+   */
+  cancel: () => void;
+}

package/src/react/core/index.ts

@@ -13,6 +13,7 @@ export * from "./hooks/useAlepha.ts";
 export * from "./hooks/useClient.ts";
 export * from "./hooks/useEvents.ts";
 export * from "./hooks/useInject.ts";
+export * from "./hooks/useQuery.ts";
 export * from "./hooks/useStore.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------

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

@@ -140,15 +140,23 @@ export class FormModel<T extends TObject> {
 
   public readonly reset = (event?: FormEventLike) => {
     event?.preventDefault?.();
+    // Snapshot all keys that need notification — both keys present
+    // before reset (so subscribers learn the cleared value) and keys
+    // restored from initialValues. Without the union, fields that were
+    // typed but absent from initialValues stay visually stale.
+    const keys = new Set<string>([
+      ...Object.keys(this.values),
+      ...Object.keys(this.initialValues),
+    ]);
     for (const key in this.values) {
       delete this.values[key];
     }
     Object.assign(this.values, { ...this.initialValues });
-    for (const [key, value] of Object.entries(this.values)) {
+    for (const key of keys) {
       const path = `/${key.replaceAll(".", "/")}`;
       this.alepha.events.emit(
         "form:change",
-        { id: this.id, path, value },
+        { id: this.id, path, value: this.values[key] },
         { catch: true },
       );
     }
@@ -356,10 +364,11 @@ export class FormModel<T extends TObject> {
       name: key,
     };
 
-    if (options.id) {
-      attr.id = `${options.id}-${key}`;
-      (attr as any)["data-testid"] = attr.id;
-    }
+    // Use the form's runtime id (always set — comes from `useId()` when
+    // no explicit `options.id` was provided). This guarantees stable
+    // per-field DOM ids without forcing callers to pass `id`.
+    attr.id = `${this.id}-${key}`;
+    (attr as any)["data-testid"] = attr.id;
 
     if (t.schema.isString(field)) {
       if (field.maxLength != null) {

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)