@terpjs/react-core 0.9.0 → 0.10.0

package/src/ui/Tooltip.test.tsx

@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
-import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { act, cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { vi } from "vitest";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { Button } from "./Button";
@@ -25,4 +26,58 @@ describe("Tooltip", () => {
     fireEvent.mouseEnter(trigger.parentElement!);
     expect(tooltip).toBeVisible();
   });
+
+  it("dismisses on Escape without moving the pointer or focus", () => {
+    // WCAG 1.4.13, Dismissible. There was no key handler of any kind, so a bubble covering the
+    // content under it could only be escaped by moving away from the control the user was
+    // reading about. Bound on the document, because the pointer-opened case has no focus
+    // anywhere near this component and a trigger-bound handler would never see the key.
+    // Mutation: delete the keydown effect.
+    render(
+      <Tooltip content="More information" defaultOpen>
+        <Button>Help</Button>
+      </Tooltip>,
+    );
+    const tooltip = screen.getByRole("tooltip");
+    expect(tooltip).toBeVisible();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(tooltip).not.toBeVisible();
+  });
+
+  it("stays open while the pointer crosses to the bubble", () => {
+    // WCAG 1.4.13, Hoverable. The bubble used to declare pointer-events: none, which makes
+    // reaching it impossible by construction; that is gone, and the close is delayed so the
+    // visual gap between trigger and bubble can be crossed. Re-entering cancels the close.
+    // Mutation: close synchronously on mouseleave, and this fails.
+    vi.useFakeTimers();
+    try {
+      render(
+        <Tooltip content="More information" defaultOpen>
+          <Button>Help</Button>
+        </Tooltip>,
+      );
+      const tooltip = screen.getByRole("tooltip");
+      const anchor = tooltip.parentElement!;
+      fireEvent.mouseLeave(anchor);
+      // Still open partway through the grace period...
+      act(() => {
+        vi.advanceTimersByTime(60);
+      });
+      expect(tooltip).toBeVisible();
+      // ...and re-entering cancels the close entirely.
+      fireEvent.mouseEnter(anchor);
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(tooltip).toBeVisible();
+      // Leaving and staying away does close it.
+      fireEvent.mouseLeave(anchor);
+      act(() => {
+        vi.advanceTimersByTime(500);
+      });
+      expect(tooltip).not.toBeVisible();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/ui/Tooltip.tsx

@@ -1,4 +1,4 @@
-import { cloneElement, isValidElement, useId, useState } from "react";
+import { cloneElement, isValidElement, useEffect, useId, useRef, useState } from "react";
 import type { FocusEvent, MouseEvent, ReactElement } from "react";
 
 import { injectTerpStyles } from "../styles";
@@ -10,6 +10,16 @@ injectTerpStyles();
 export interface TooltipProps {
   content: UiText;
   children: ReactElement;
+  /**
+   * Start with the bubble shown.
+   *
+   * The same dev/specimen affordance `AppShell.defaultCollapsed` and `defaultDrawerOpen` are,
+   * added for the same reason: the panel's whole style block — its surface, its ink, its shadow
+   * and its measure — was painted by nothing. The one Tooltip specimen renders the trigger with
+   * the bubble closed, and neither browser lane can hover or focus, so a change to any of those
+   * declarations moved no pixel that any gate reads. An app has no reason to pin a tooltip open.
+   */
+  defaultOpen?: boolean;
 }
 
 interface TriggerHandlers {
@@ -20,11 +30,60 @@ interface TriggerHandlers {
   "aria-describedby"?: string;
 }
 
-/** Accessible focus/hover tooltip. */
-export function Tooltip({ content, children }: TooltipProps) {
+/**
+ * Accessible focus/hover tooltip.
+ *
+ * Holds all three parts of WCAG 1.4.13 (Content on Hover or Focus, level AA), and two of them
+ * had to be added:
+ *
+ * - **Dismissible.** Escape closes the bubble without moving the pointer or focus. There was no
+ *   key handler of any kind before, so a tooltip covering the content beneath it could only be
+ *   escaped by moving away from the control the user was reading about.
+ * - **Hoverable.** The bubble is reachable with the pointer. It used to declare
+ *   `pointer-events: none`, which makes hovering it impossible by construction — so a tooltip
+ *   long enough to need reading could not be read by anyone tracking with a pointer or using
+ *   magnification. The bubble is a DOM child of the anchor, so moving onto it does not fire the
+ *   anchor's `mouseleave`; the close delay below covers the visual gap between the two, which
+ *   the pointer does cross.
+ * - **Persistent.** It stays until dismissed, focus leaves or the pointer leaves — it has never
+ *   had a timeout.
+ */
+export function Tooltip({ content, children, defaultOpen = false }: TooltipProps) {
   const id = useId();
   const resolve = useUiText();
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(defaultOpen);
+  // Cleared on re-entry, which is what makes the gap between trigger and bubble crossable.
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  function cancelClose() {
+    if (closeTimer.current !== null) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  }
+
+  function scheduleClose() {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setOpen(false), 120);
+  }
+
+  useEffect(() => cancelClose, []);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    // On the document rather than the trigger: the pointer-opened case has no focus anywhere
+    // near this component, so a handler bound to the trigger would never see the key. The same
+    // placement Popover uses, for the same reason.
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") {
+        setOpen(false);
+      }
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open]);
 
   if (!isValidElement<TriggerHandlers>(children)) {
     return children;
@@ -33,13 +92,17 @@ export function Tooltip({ content, children }: TooltipProps) {
   return (
     <span
       data-terp="tooltip-anchor"
-      onMouseEnter={() => setOpen(true)}
-      onMouseLeave={() => setOpen(false)}
+      onMouseEnter={() => {
+        cancelClose();
+        setOpen(true);
+      }}
+      onMouseLeave={scheduleClose}
     >
       {cloneElement(children, {
         "aria-describedby": id,
         onFocus: (event: FocusEvent) => {
           children.props.onFocus?.(event);
+          cancelClose();
           setOpen(true);
         },
         onBlur: (event: FocusEvent) => {

package/src/uiText.tsx

@@ -40,6 +40,10 @@ export interface TerpStrings {
   email: string;
   /** Login password placeholder. */
   password: string;
+  /** Password reveal toggle, while the value is hidden. */
+  showPassword: string;
+  /** Password reveal toggle, while the value is visible. */
+  hidePassword: string;
   /** Login failure message. */
   signInFailed: string;
   /** Label of the dev-only button that fills the seeded development credentials. */
@@ -86,6 +90,8 @@ export interface TerpStrings {
   home: string;
   /** Accessible name of the sidebar `nav` landmark. */
   primaryNavigationLabel: string;
+  /** The shell's skip link — the first thing a keyboard reaches, jumping past the chrome. */
+  skipToContent: string;
   /** Accessible label of the header toggle when it collapses the expanded sidebar. */
   collapseSidebar: string;
   /** Accessible label of the header toggle when it expands the collapsed sidebar. */
@@ -215,6 +221,8 @@ export const DEFAULT_STRINGS: TerpStrings = {
   signingIn: "Signing in…",
   email: "Email",
   password: "Password",
+  showPassword: "Show password",
+  hidePassword: "Hide password",
   signInFailed: "Sign-in failed. Check your credentials.",
   fillDevCredentials: "Fill dev credentials",
   continueWith: "Continue with",
@@ -238,6 +246,7 @@ export const DEFAULT_STRINGS: TerpStrings = {
   role: "Role",
   home: "Home",
   primaryNavigationLabel: "Primary",
+  skipToContent: "Skip to content",
   collapseSidebar: "Collapse sidebar",
   expandSidebar: "Expand sidebar",
   openNavigation: "Open navigation",

package/src/unwrap.test.ts

@@ -96,3 +96,135 @@ describe("unwrapOptional", () => {
     expect((caught as ApiError).status).toBe(403);
   });
 });
+
+// The per-field half of the error envelope.
+//
+// `Field` shipped an `error` prop, a `field-error` marker, an `aria-describedby`, an
+// `aria-invalid` and a style rule for all of it, and nothing in this package could produce the
+// value: every `error=` on a `Field` in all three trees was a test or a specimen. The reason was
+// one function here, which computed each reason's field path and then joined it into a sentence.
+// The information reached the client and was discarded on arrival.
+//
+// So these do not assert that a parser parses. Each one names a way the path can be lost again.
+describe("ApiError.fields", () => {
+  function failureOf(error: unknown, status = 422): ApiError {
+    try {
+      unwrap({ error, response: response(status) });
+    } catch (thrown) {
+      return thrown as ApiError;
+    }
+    throw new Error("unwrap returned instead of throwing");
+  }
+
+  it("keys a FastAPI 422 by dotted path, with the body/query/path prefix dropped", () => {
+    expect(
+      failureOf({
+        detail: [
+          { loc: ["body", "title"], msg: "String should have at least 1 character" },
+          { loc: ["body", "owner", "email"], msg: "Input should be a valid email" },
+        ],
+      }).fields,
+    ).toEqual({
+      title: "String should have at least 1 character",
+      "owner.email": "Input should be a valid email",
+    });
+  });
+
+  it("reads the envelope's own `details`, whose `loc` is already a dotted string", () => {
+    // `terp.core.ErrorDetail` documents its shape as "deliberately mirrors FastAPI's own 422
+    // detail entries ... so a frontend handles both with one branch", and no such branch existed:
+    // `unwrap` named `details` in a doc comment and never read the key. Handling only the array
+    // spelling would have kept half of that promise while claiming all of it.
+    // Mutation: delete the string arm of `fieldPath` and only this test goes red.
+    expect(
+      failureOf({
+        code: "validation_failed",
+        detail: "Two things are wrong.",
+        details: [
+          { code: "too_short", loc: "name", msg: "Name is too short." },
+          { code: "not_unique", loc: "contact.email", msg: "Already registered." },
+        ],
+      }).fields,
+    ).toEqual({ name: "Name is too short.", "contact.email": "Already registered." });
+  });
+
+  it("leaves the message to `detail` when `details` rides beside it", () => {
+    // `details` is additive on the wire, so it must be additive here too. If it captured the
+    // message slot that `detail` already fills, every existing caller's copy would change on the
+    // day a backend first emits a reason list.
+    expect(
+      failureOf({
+        detail: "Two things are wrong.",
+        details: [{ code: "too_short", loc: "name", msg: "Name is too short." }],
+      }).message,
+    ).toBe("Two things are wrong.");
+  });
+
+  it("is empty for every failure that names no field", () => {
+    expect(failureOf({ code: "permission_denied", detail: "Nope." }, 403).fields).toEqual({});
+    expect(failureOf({ code: "conflict" }, 409).fields).toEqual({});
+    expect(failureOf(undefined, 500).fields).toEqual({});
+  });
+
+  it("keeps a reason with no `loc` in the message, the only place it can go", () => {
+    // A record keyed by field has no slot for a reason about the request as a whole, which
+    // `ErrorDetail` documents as a supported case. Dropping it silently would be a regression
+    // from the joined string this replaced, so the message keeps carrying it.
+    const failure = failureOf({
+      detail: [
+        { loc: [], msg: "The window overlaps an existing one." },
+        { loc: ["body", "name"], msg: "Name is too short." },
+      ],
+    });
+    expect(failure.fields).toEqual({ name: "Name is too short." });
+    expect(failure.message).toBe("The window overlaps an existing one.; name: Name is too short.");
+  });
+
+  it("takes the first reason per field and leaves the rest in the message", () => {
+    const failure = failureOf({
+      detail: [
+        { loc: ["body", "password"], msg: "Too short." },
+        { loc: ["body", "password"], msg: "Needs a digit." },
+      ],
+    });
+    expect(failure.fields).toEqual({ password: "Too short." });
+    expect(failure.message).toBe("password: Too short.; password: Needs a digit.");
+  });
+
+  it("drops only a LEADING body/query/path, because elsewhere the same word is a field name", () => {
+    // FastAPI puts exactly one of these at the front to say where in the request the value came
+    // from. Anywhere else it is a name the caller chose, and a webhook with a `path` field is not
+    // a hypothetical. Stripping every occurrence attached the reason to the wrong control, or —
+    // for a top-level field called `path` — to no control at all, since the key came out empty.
+    expect(failureOf({ detail: [{ loc: ["body", "path"], msg: "Must start with a slash." }] }).fields)
+      .toEqual({ path: "Must start with a slash." });
+    expect(
+      failureOf({ detail: [{ loc: ["body", "config", "body"], msg: "Required." }] }).fields,
+    ).toEqual({ "config.body": "Required." });
+    // A loc that is ONLY the prefix is still about the request as a whole, so it keeps no key.
+    const whole = failureOf({ detail: [{ loc: ["body"], msg: "Malformed JSON." }] });
+    expect(whole.fields).toEqual({});
+    expect(whole.message).toBe("Malformed JSON.");
+  });
+
+  it("keeps a reason whose field is named after something on Object.prototype", () => {
+    // The keys are server-supplied. `fields["constructor"]` on a plain object is truthy before
+    // anything is written to it, so a first-wins guard spelled `=== undefined` decides the slot is
+    // taken and drops the reason with no trace.
+    expect(
+      failureOf({
+        detail: [
+          { loc: ["body", "constructor"], msg: "Unknown builder." },
+          { loc: ["body", "toString"], msg: "Not a template." },
+        ],
+      }).fields,
+    ).toEqual({ constructor: "Unknown builder.", toString: "Not a template." });
+  });
+
+  it("is frozen, so one failure's reasons cannot be edited into something the server never said", () => {
+    const fields = failureOf({ detail: [{ loc: ["body", "name"], msg: "Too short." }] }).fields;
+    expect(() => {
+      (fields as Record<string, string>).name = "anything";
+    }).toThrow();
+  });
+});

package/src/unwrap.ts

@@ -30,13 +30,36 @@ export class ApiError extends Error {
   readonly status: number;
   /** Correlation id from the envelope, for support and log lookup. */
   readonly requestId?: string;
+  /**
+   * Per-field reasons, keyed by dotted field path (`loc` with FastAPI's `body` / `query` /
+   * `path` prefix removed). Empty for every failure that names no field, so
+   * `Object.keys(error.fields).length > 0` is the test for "this belongs on the form".
+   *
+   * What a caller does with it is hand it to `Field`'s `error` prop, which is the whole
+   * reason it exists: the framework shipped the rendering half of field-level validation —
+   * the marker, the `aria-describedby`, the `aria-invalid`, the styling — and nothing that
+   * produces the value. The path was already being computed one function below and joined
+   * into a sentence, so the information reached the client and was discarded on arrival.
+   */
+  readonly fields: Readonly<Record<string, string>>;
 
-  constructor(message: string, options: { code?: string; status: number; requestId?: string }) {
+  constructor(
+    message: string,
+    options: {
+      code?: string;
+      status: number;
+      requestId?: string;
+      fields?: Readonly<Record<string, string>>;
+    },
+  ) {
     super(message);
     this.name = "ApiError";
     this.code = options.code;
     this.status = options.status;
     this.requestId = options.requestId;
+    // Defaulted and frozen: every caller reads `.fields` without a presence check, and an
+    // error's reasons cannot be edited into something the server never said.
+    this.fields = Object.freeze({ ...options.fields });
   }
 }
 
@@ -63,55 +86,118 @@ export function unwrap<T>(result: FetchResult<T>): T {
       result.error !== null && typeof result.error === "object"
         ? (result.error as { code?: unknown; request_id?: unknown })
         : {};
-    throw new ApiError(errorMessage(result.error, result.response), {
+    const failure = describeFailure(result.error, result.response);
+    throw new ApiError(failure.message, {
       code: typeof envelope.code === "string" ? envelope.code : undefined,
       status: result.response.status,
       requestId: typeof envelope.request_id === "string" ? envelope.request_id : undefined,
+      fields: failure.fields,
     });
   }
   return result.data as T;
 }
 
-/** Human-readable message for a failed request: envelope `detail`, else `code`, else the status. */
-function errorMessage(error: unknown, response: Response): string {
+/** A failure's message and its per-field reasons — one value, because one walk produces both. */
+interface Failure {
+  message: string;
+  fields: Record<string, string>;
+}
+
+/**
+ * Human-readable message for a failed request — envelope `detail`, else `code`, else the
+ * status — paired with whatever per-field reasons came with it.
+ *
+ * The envelope keeps its reasons in two different places depending on who raised the error,
+ * and both are read here. A Terp `AppError` puts a sentence in `detail` and its structured
+ * reasons in `details` beside it, so the sentence still wins the message. FastAPI's own 422
+ * handler makes `detail` *itself* the list — the app registers no `RequestValidationError`
+ * override, so that is the shape a schema rejection actually arrives in.
+ */
+function describeFailure(error: unknown, response: Response): Failure {
   if (error !== null && typeof error === "object") {
-    const envelope = error as { detail?: unknown; code?: unknown };
+    const envelope = error as { detail?: unknown; details?: unknown; code?: unknown };
+    // `details` sits beside `detail` rather than replacing it, so its reasons attach to
+    // whichever message wins below instead of competing for the slot.
+    const reasons = structuredDetail(envelope.details);
+    const fields = reasons?.fields ?? {};
     if (typeof envelope.detail === "string" && envelope.detail.length > 0) {
-      return envelope.detail;
+      return { message: envelope.detail, fields };
     }
-    const structured = structuredDetail(envelope.detail);
-    if (structured !== null) {
-      return structured;
+    const validation = structuredDetail(envelope.detail);
+    if (validation !== null) {
+      return validation;
     }
     if (typeof envelope.code === "string" && envelope.code.length > 0) {
-      return envelope.code;
+      return { message: envelope.code, fields };
     }
   }
-  return `Request failed (HTTP ${response.status})`;
+  return { message: `Request failed (HTTP ${response.status})`, fields: {} };
+}
+
+/**
+ * The dotted field path a reason addresses, or `""` when it is about the request as a whole.
+ *
+ * Two spellings arrive and reading only one is how the client stayed half-deaf to its own
+ * contract: FastAPI emits `loc` as an array (`["body", "owner", "email"]`), while
+ * `terp.core.ErrorDetail` emits it already dotted — a shape whose docstring says it
+ * "deliberately mirrors FastAPI's own 422 detail entries ... so a frontend handles both with
+ * one branch". Nothing had written that branch. This is it.
+ *
+ * Only a LEADING `body` / `query` / `path` is dropped. FastAPI puts exactly one of them at the
+ * front to say where in the request the value came from; anywhere else the same word is a field
+ * the caller named, and `["body", "path"]` is a webhook's `path` field, not a bare request. While
+ * this only shaped a sentence the difference was cosmetic. It now chooses which input lights up,
+ * so stripping every occurrence would attach a reason to the wrong control — or, for a top-level
+ * field called `path`, to no control at all.
+ */
+const LOC_PREFIXES = new Set(["body", "query", "path"]);
+
+function fieldPath(loc: unknown): string {
+  if (Array.isArray(loc)) {
+    const parts = loc.filter(
+      (part): part is string | number => typeof part === "string" || typeof part === "number",
+    );
+    const start = typeof parts[0] === "string" && LOC_PREFIXES.has(parts[0]) ? 1 : 0;
+    return parts.slice(start).join(".");
+  }
+  return typeof loc === "string" ? loc : "";
 }
 
-/** Flatten common FastAPI/Pydantic validation details into an agent/user-actionable message. */
-function structuredDetail(detail: unknown): string | null {
+/**
+ * Flatten common FastAPI/Pydantic validation details into an agent/user-actionable message,
+ * keeping each reason's field alongside it.
+ *
+ * The message is assembled exactly as before, deliberately: it is what every existing caller
+ * shows, and `fields` is additive beside it rather than a replacement for it. A reason with
+ * no `loc` therefore still reaches the user through the message, which is the only place it
+ * can go — a record keyed by field has no slot for a reason about the request as a whole.
+ */
+function structuredDetail(detail: unknown): Failure | null {
   if (!Array.isArray(detail)) {
     return null;
   }
-  const messages = detail
-    .map((item) => {
-      if (item === null || typeof item !== "object") {
-        return null;
-      }
-      const field = item as { loc?: unknown; msg?: unknown };
-      if (typeof field.msg !== "string" || field.msg.length === 0) {
-        return null;
-      }
-      const loc = Array.isArray(field.loc)
-        ? field.loc.filter((part) => typeof part === "string" || typeof part === "number")
-        : [];
-      const path = loc
-        .filter((part) => part !== "body" && part !== "query" && part !== "path")
-        .join(".");
-      return path.length > 0 ? `${path}: ${field.msg}` : field.msg;
-    })
-    .filter((message): message is string => message !== null);
-  return messages.length > 0 ? messages.join("; ") : null;
+  const messages: string[] = [];
+  const fields: Record<string, string> = {};
+  for (const item of detail) {
+    if (item === null || typeof item !== "object") {
+      continue;
+    }
+    const reason = item as { loc?: unknown; msg?: unknown };
+    if (typeof reason.msg !== "string" || reason.msg.length === 0) {
+      continue;
+    }
+    const path = fieldPath(reason.loc);
+    messages.push(path.length > 0 ? `${path}: ${reason.msg}` : reason.msg);
+    // First reason wins per path. A field that fails two checks shows the one the server
+    // reported first and keeps the rest in the message; overwriting would show the last,
+    // which is no more correct and reads as arbitrary.
+    //
+    // `Object.hasOwn`, not `=== undefined`: the keys are server-supplied, and a field called
+    // `constructor` or `toString` inherits a truthy value from `Object.prototype`, so the
+    // cheaper test would decide the slot was already taken and drop the reason silently.
+    if (path.length > 0 && !Object.hasOwn(fields, path)) {
+      fields[path] = reason.msg;
+    }
+  }
+  return messages.length > 0 ? { message: messages.join("; "), fields } : null;
 }