alepha 0.20.1 → 0.20.3

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

@@ -0,0 +1,163 @@
+import { type TSchema, TypeBoxError } from "alepha";
+import type { BaseInputField } from "./FormModel.ts";
+import { prettyName } from "./prettyName.ts";
+
+/**
+ * Semantic icon hint derived from schema metadata. UI layers map this
+ * to their own icon set — this module is headless and ships no JSX.
+ */
+export type IconHint =
+  | "email"
+  | "password"
+  | "phone"
+  | "url"
+  | "number"
+  | "calendar"
+  | "clock"
+  | "list"
+  | "text"
+  | "user"
+  | "file"
+  | "switch";
+
+export interface FieldConstraints {
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+}
+
+export interface FieldMeta {
+  id?: string;
+  label: string;
+  description?: string;
+  error?: string;
+  required: boolean;
+  type?: string;
+  format?: string;
+  isEnum: boolean;
+  isArray: boolean;
+  isObject: boolean;
+  isArrayOfObjects: boolean;
+  enum?: readonly unknown[];
+  iconHint?: IconHint;
+  constraints: FieldConstraints;
+  testId?: string;
+  schema: TSchema;
+}
+
+export interface ParseFieldOptions {
+  label?: string;
+  description?: string;
+  error?: Error;
+}
+
+/**
+ * Derives a {@link FieldMeta} from an `InputField` (from `useForm`) plus
+ * optional overrides. Pure — no React, no JSX, no UI library coupling.
+ *
+ * UI components consume this metadata to render labels, descriptions,
+ * error messages, icons, and validation constraints.
+ */
+export const parseField = (
+  input: BaseInputField,
+  options: ParseFieldOptions = {},
+): FieldMeta => {
+  const schema = input.schema as TSchema & {
+    type?: string;
+    format?: string;
+    title?: string;
+    description?: string;
+    enum?: readonly unknown[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    properties?: unknown;
+    items?: { properties?: unknown };
+  };
+
+  const label =
+    options.label ??
+    (typeof schema.title === "string" ? schema.title : undefined) ??
+    prettyName(input.path);
+
+  const description =
+    options.description ??
+    (typeof schema.description === "string" ? schema.description : undefined);
+
+  const error =
+    options.error instanceof TypeBoxError
+      ? (options.error as TypeBoxError).value?.message
+      : undefined;
+
+  const type = schema.type;
+  const format = typeof schema.format === "string" ? schema.format : undefined;
+  const isEnum = Array.isArray(schema.enum);
+  const isArray = type === "array";
+  const isObject = type === "object" && Boolean(schema.properties);
+  const isArrayOfObjects =
+    isArray && Boolean(schema.items && (schema.items as any).properties);
+
+  const name = input.props.name;
+  const iconHint = inferIconHint({ type, format, name, isEnum, isArray });
+
+  const constraints: FieldConstraints = {};
+  if (typeof schema.minLength === "number")
+    constraints.minLength = schema.minLength;
+  if (typeof schema.maxLength === "number")
+    constraints.maxLength = schema.maxLength;
+  if (typeof schema.minimum === "number") constraints.minimum = schema.minimum;
+  if (typeof schema.maximum === "number") constraints.maximum = schema.maximum;
+  if (typeof schema.pattern === "string") constraints.pattern = schema.pattern;
+
+  return {
+    id: input.props.id,
+    label,
+    description,
+    error,
+    required: input.required,
+    type,
+    format,
+    isEnum,
+    isArray,
+    isObject,
+    isArrayOfObjects,
+    enum: schema.enum,
+    iconHint,
+    constraints,
+    testId: (input.props as Record<string, unknown>)["data-testid"] as
+      | string
+      | undefined,
+    schema: input.schema,
+  };
+};
+
+const inferIconHint = (params: {
+  type?: string;
+  format?: string;
+  name?: string;
+  isEnum: boolean;
+  isArray: boolean;
+}): IconHint | undefined => {
+  const { type, format, name, isEnum, isArray } = params;
+
+  if (format === "email") return "email";
+  if (format === "url" || format === "uri") return "url";
+  if (format === "tel" || format === "phone") return "phone";
+  if (format === "date" || format === "date-time") return "calendar";
+  if (format === "time") return "clock";
+
+  if (name?.toLowerCase().includes("password")) return "password";
+  if (name?.toLowerCase().includes("email")) return "email";
+  if (name?.toLowerCase().includes("phone")) return "phone";
+
+  if (type === "boolean") return "switch";
+  if (type === "number" || type === "integer") return "number";
+  if (isEnum || isArray) return "list";
+  if (type === "string") return "text";
+
+  return undefined;
+};

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

@@ -0,0 +1,19 @@
+/**
+ * Converts a path or identifier string into a pretty display name.
+ * For paths like "/contacts/0/name", extracts just the field name "Name".
+ * Handles camelCase and snake_case conversion to Title Case.
+ *
+ * @example
+ * prettyName("/userName") // "User Name"
+ * prettyName("/contacts/0/email") // "Email"
+ * prettyName("/address/streetName") // "Street Name"
+ * prettyName("first_name") // "First Name"
+ */
+export const prettyName = (name: string): string => {
+  const segments = name.split("/").filter((s) => s && !/^\d+$/.test(s));
+  const fieldName = segments[segments.length - 1] || name.replaceAll("/", "");
+  return fieldName
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+};

package/src/react/head/providers/BrowserHeadProvider.ts

@@ -154,10 +154,12 @@ export class BrowserHeadProvider {
       | string
       | (Record<string, string | boolean | undefined> & { content?: string }),
   ): void {
-    const el = document.createElement("script");
-
-    // Handle plain string as inline script
+    // Plain string → inline script. Dedupe by exact content match against
+    // any existing inline script (handles SSR-emitted globals that would
+    // otherwise be re-appended on hydration).
     if (typeof script === "string") {
+      if (this.findInlineScriptByContent(document, script)) return;
+      const el = document.createElement("script");
       el.textContent = script;
       document.head.appendChild(el);
       return;
@@ -165,14 +167,18 @@ export class BrowserHeadProvider {
 
     const { content, ...attrs } = script;
 
-    // For scripts with src, check if already exists
+    // src-based scripts: dedupe by src attribute (existing behaviour).
     if (attrs.src) {
-      const existing = document.querySelector(`script[src="${attrs.src}"]`);
-      if (existing) {
-        return;
-      }
+      if (document.querySelector(`script[src="${attrs.src}"]`)) return;
+    } else if (typeof attrs.id === "string") {
+      // id-based dedupe — single source of truth per id.
+      if (document.querySelector(`script#${CSS.escape(attrs.id)}`)) return;
+    } else if (content) {
+      // Inline scripts with `content` and no src/id: fall back to content match.
+      if (this.findInlineScriptByContent(document, content)) return;
     }
 
+    const el = document.createElement("script");
     for (const [key, value] of Object.entries(attrs)) {
       if (value === true) {
         el.setAttribute(key, "");
@@ -180,14 +186,29 @@ export class BrowserHeadProvider {
         el.setAttribute(key, String(value));
       }
     }
-
     if (content) {
       el.textContent = content;
     }
-
     document.head.appendChild(el);
   }
 
+  /**
+   * Find an existing inline `<script>` tag (no `src`) with matching textContent.
+   * Used to make `renderScriptTag` idempotent across hydration + navigation,
+   * so SSR-emitted global scripts aren't re-appended client-side.
+   */
+  protected findInlineScriptByContent(
+    document: Document,
+    content: string,
+  ): Element | null {
+    for (const existing of document.head.querySelectorAll(
+      "script:not([src])",
+    )) {
+      if (existing.textContent === content) return existing;
+    }
+    return null;
+  }
+
   protected renderMetaTag(document: Document, meta: HeadMeta): void {
     const { content } = meta;
 

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__/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);
+    });
+  });
 });

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

@@ -50,16 +50,6 @@ import { ReactPageService } from "../services/ReactPageService.ts";
  * - Hierarchical error handling (child → parent)
  * - HTTP status code handling (404, 401, etc.)
  *
- * **Page Animations**
- * - CSS-based enter/exit animations
- * - Dynamic animations based on page state
- * - Custom timing and easing functions
- *
- * **Lifecycle Management**
- * - Server response hooks for headers and status codes
- * - Page leave handlers for cleanup (browser only)
- * - Permission-based access control
- *
  * @example Simple page with data fetching
  * ```typescript
  * const userProfile = $page({
@@ -202,13 +192,46 @@ export interface PagePrimitiveOptions<
   lazy?: () => Promise<{ default: FC<TProps & TPropsParent> }>;
 
   /**
-   * Attach child pages to create nested routes.
-   * This will make the page a parent route.
+   * Attach child pages to create nested routes, adopting them as children of
+   * this page.
+   *
+   * Use this when you want a parent to own children it cannot modify — most
+   * notably pages that come from an injected router in another package, whose
+   * `$page` definitions are frozen and cannot declare `parent` themselves.
+   *
+   * ```ts
+   * layout = $page({
+   *   path: "/app",
+   *   children: () => [
+   *     this.productRouter.catalogPage,  // from $inject(ProductRouter)
+   *     this.productRouter.checkoutPage,
+   *   ],
+   * });
+   * ```
+   *
+   * Use a thunk (`() => [...]`) when the children are defined later in the
+   * same class.
+   *
+   * **Declare each edge from one side only.** If a child already sets
+   * `parent: thisPage`, do NOT also add it to `children` — the link is
+   * already established, and declaring it on both sides creates a TypeScript
+   * circular dependency between the two class fields (each references the
+   * other before it is initialised).
    */
   children?: Array<PagePrimitive> | (() => Array<PagePrimitive>);
 
   /**
    * Define a parent page for nested routing.
+   *
+   * Use this when you own the child page and can edit its definition — it is
+   * the simplest way to nest routes and reads top-down. For pages you do NOT
+   * own (e.g. pages exposed by an injected router from another package), let
+   * the parent adopt them via its `children` option instead.
+   *
+   * **Declare each edge from one side only.** If you set `parent` here, do
+   * NOT also add this page to the parent's `children` array — the link is
+   * already established, and declaring it on both sides creates a TypeScript
+   * circular dependency between the two class fields.
    */
   parent?: PagePrimitive<PageConfigSchema, TPropsParent, any>;
 

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/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;
       }