alepha 0.20.2 → 0.20.4

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/intro/components/GettingStartedAuthSlide.tsx

@@ -8,7 +8,7 @@ import type { GettingStartedSlide } from "./GettingStarted.tsx";
  * Returns undefined if auth routes are not configured.
  */
 export const useAuthSlide = (): GettingStartedSlide | undefined => {
-  const { user } = useAuth();
+  const { user, logout } = useAuth();
   const router = useRouter();
 
   // Check if auth routes exist
@@ -19,8 +19,6 @@ export const useAuthSlide = (): GettingStartedSlide | undefined => {
 
   // User is logged in - show user info and logout option
   if (user) {
-    const logoutAnchorProps = router.anchor(router.path("logout"));
-
     return {
       text: "Welcome back!",
       sub: `You're signed in as ${user.email || user.username || "user"}.`,
@@ -33,7 +31,16 @@ export const useAuthSlide = (): GettingStartedSlide | undefined => {
           num: "→",
           text: (
             <>
-              <a {...logoutAnchorProps}>Sign out</a> to test the login flow
+              <a
+                href="#"
+                onClick={(e) => {
+                  e.preventDefault();
+                  logout();
+                }}
+              >
+                Sign out
+              </a>{" "}
+              to test the login flow
             </>
           ),
         },

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__/ReactBrowserProvider.browser.spec.ts

@@ -1,9 +1,22 @@
 import { Alepha } from "alepha";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { ReactBrowserProvider } from "../providers/ReactBrowserProvider.ts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  ReactBrowserProvider,
+  type RouterPushOptions,
+  reactBrowserOptions,
+} from "../providers/ReactBrowserProvider.ts";
 
 class TestReactBrowserProvider extends ReactBrowserProvider {
   public testGetHydrationState = this.getHydrationState.bind(this);
+  public testAttachAnchorInterceptor = this.attachAnchorInterceptor.bind(this);
+  public pushCalls: Array<{ url: string; options?: RouterPushOptions }> = [];
+
+  public override async push(
+    url: string,
+    options?: RouterPushOptions,
+  ): Promise<void> {
+    this.pushCalls.push({ url, options });
+  }
 }
 
 describe("ReactBrowserProvider", () => {
@@ -102,4 +115,202 @@ describe("ReactBrowserProvider", () => {
       expect(result?.["alepha.i18n.locale"]).toBe("en");
     });
   });
+
+  describe("attachAnchorInterceptor", () => {
+    let alepha: Alepha;
+    let provider: TestReactBrowserProvider;
+    let detach: () => void;
+    let container: HTMLDivElement;
+
+    const createAnchor = (
+      attrs: Record<string, string>,
+      inner?: HTMLElement,
+    ): HTMLAnchorElement => {
+      const a = document.createElement("a");
+      for (const [k, v] of Object.entries(attrs)) {
+        a.setAttribute(k, v);
+      }
+      if (inner) {
+        a.appendChild(inner);
+      } else {
+        a.textContent = "link";
+      }
+      container.appendChild(a);
+      return a;
+    };
+
+    const click = (
+      target: HTMLElement,
+      init: MouseEventInit = {},
+    ): MouseEvent => {
+      const ev = new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        button: 0,
+        ...init,
+      });
+      target.dispatchEvent(ev);
+      return ev;
+    };
+
+    beforeEach(() => {
+      alepha = Alepha.create();
+      provider = alepha.inject(TestReactBrowserProvider);
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      detach = provider.testAttachAnchorInterceptor();
+    });
+
+    afterEach(() => {
+      detach();
+      container.remove();
+    });
+
+    it("intercepts plain internal /foo anchor clicks", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      const ev = click(a);
+
+      expect(provider.pushCalls).toHaveLength(1);
+      expect(provider.pushCalls[0].url).toBe("/foo");
+      expect(ev.defaultPrevented).toBe(true);
+    });
+
+    it("preserves query and hash when intercepting", () => {
+      const a = createAnchor({ href: "/foo?x=1#bar" });
+
+      click(a);
+
+      expect(provider.pushCalls[0].url).toBe("/foo?x=1#bar");
+    });
+
+    it("ignores cmd-click (metaKey)", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      const ev = click(a, { metaKey: true });
+
+      expect(provider.pushCalls).toHaveLength(0);
+      expect(ev.defaultPrevented).toBe(false);
+    });
+
+    it("ignores ctrl-click", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      click(a, { ctrlKey: true });
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores shift-click", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      click(a, { shiftKey: true });
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores alt-click", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      click(a, { altKey: true });
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores non-primary mouse buttons", () => {
+      const a = createAnchor({ href: "/foo" });
+
+      click(a, { button: 1 });
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores anchors with target='_blank'", () => {
+      const a = createAnchor({ href: "/foo", target: "_blank" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores anchors with download attribute", () => {
+      const a = createAnchor({ href: "/foo", download: "" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores anchors with data-no-router attribute", () => {
+      const a = createAnchor({ href: "/foo", "data-no-router": "" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores mailto: hrefs", () => {
+      const a = createAnchor({ href: "mailto:foo@bar.com" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores tel: hrefs", () => {
+      const a = createAnchor({ href: "tel:+15555555" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores hrefs to external origins", () => {
+      const a = createAnchor({ href: "https://example.com/foo" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("ignores hash-only #section hrefs", () => {
+      const a = createAnchor({ href: "#section" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("intercepts when click target is nested inside the anchor", () => {
+      const span = document.createElement("span");
+      span.textContent = "inner";
+      createAnchor({ href: "/foo" }, span);
+
+      click(span);
+
+      expect(provider.pushCalls).toHaveLength(1);
+      expect(provider.pushCalls[0].url).toBe("/foo");
+    });
+
+    it("skips when defaultPrevented is already true", () => {
+      const a = createAnchor({ href: "/foo" });
+      a.addEventListener("click", (ev) => ev.preventDefault());
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+
+    it("respects interceptAnchorClicks=false at runtime", () => {
+      alepha.store.set(reactBrowserOptions.key, {
+        ...alepha.store.get(reactBrowserOptions.key)!,
+        interceptAnchorClicks: false,
+      });
+      const a = createAnchor({ href: "/foo" });
+
+      click(a);
+
+      expect(provider.pushCalls).toHaveLength(0);
+    });
+  });
 });