@terpjs/react-core 0.9.0 → 0.11.0

package/src/admin/UserCreate.tsx

@@ -16,10 +16,14 @@ import { useStrings } from "../uiText";
 import { unwrap } from "../unwrap";
 
 import { adminCrumb, renderAdminCrumb } from "./crumbs";
+import { routeFieldErrors } from "./fieldErrors";
 import { adminRoleOptions } from "./roles";
 
 const FORM_ID = "terp-admin-user-create";
 
+/** The inputs this form renders, and so the only reasons it can put anywhere the user will see. */
+const RENDERED_FIELDS = ["email", "password", "role"] as const;
+
 /** Dedicated account-provisioning page (`/admin/users/new`). */
 export function UserCreate() {
   const client = useTerpClient();
@@ -30,11 +34,16 @@ export function UserCreate() {
   const [password, setPassword] = useState("");
   const [role, setRole] = useState("10");
   const [creating, setCreating] = useState(false);
+  const [fieldErrors, setFieldErrors] = useState<Readonly<Record<string, string>>>({});
   const roles = adminRoleOptions(strings);
 
   async function onSubmit(event: FormEvent) {
     event.preventDefault();
     setCreating(true);
+    // Cleared on every attempt, not merged: the server re-validates the whole body, so its
+    // answer is the complete set of what is wrong. Keeping a stale key would leave an error
+    // under a field the user just fixed.
+    setFieldErrors({});
     try {
       const user = unwrap(
         await client.POST("/api/v1/users/", {
@@ -47,7 +56,15 @@ export function UserCreate() {
         params: { userId: user.id },
       });
     } catch (error) {
-      toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      // A reason that names a field belongs on that field, not floating above the form in a
+      // toast the user has to hold in their head while looking for the input it means. Anything
+      // the server did not attribute — or attributed to something this form has no input for —
+      // stays a toast, which is where the delete and revoke handlers correctly leave it.
+      const { shown, leftover } = routeFieldErrors(error, RENDERED_FIELDS);
+      setFieldErrors(shown);
+      if (Object.keys(shown).length === 0 || leftover) {
+        toast.warning(error instanceof Error ? error.message : strings.requestFailed);
+      }
     } finally {
       setCreating(false);
     }
@@ -83,7 +100,7 @@ export function UserCreate() {
     >
       <div data-terp="admin-form">
         <Stack id={FORM_ID} as="form" gap={4} onSubmit={onSubmit}>
-          <Field label={strings.email}>
+          <Field label={strings.email} error={fieldErrors.email}>
             <Input
               type="email"
               value={email}
@@ -91,22 +108,34 @@ export function UserCreate() {
               required
             />
           </Field>
-          <Field label={strings.password}>
+          <Field label={strings.password} error={fieldErrors.password}>
             <Input
               type="password"
+              // The admin is setting someone else's password, so this is never the browser's saved
+              // credential: `new-password` stops a manager offering the admin's own.
+              autoComplete="new-password"
               value={password}
               onChange={(event) => setPassword(event.target.value)}
               required
             />
           </Field>
-          <Field label={strings.role}>
-            <Select value={role} onChange={(event) => setRole(event.target.value)}>
-              {roles.map((option) => (
-                <option key={option.rank} value={option.rank}>
-                  {option.label}
-                </option>
-              ))}
-            </Select>
+          <Field label={strings.role} error={fieldErrors.role}>
+            {/* `options` + `onValueChange` rather than an `<option>` per rank and a raw
+                change event: the same three rows, as data. No cast is removed here — this file
+                never had one, because `role` was already a plain string — and `T` degrades to
+                `string` for the same reason, since the option values are `String(rank)` rather
+                than members of a declared union. What this conversion buys is the list, not the
+                type: the rank is a number in the ladder and a string in the DOM, which is why
+                `String(rank)` is the option value and `role` stays a string until the POST body
+                coerces it. The typed half has its exhibit in an app that owns an enum. */}
+            <Select
+              options={roles.map((option) => ({
+                value: String(option.rank),
+                label: option.label,
+              }))}
+              value={role}
+              onValueChange={setRole}
+            />
           </Field>
         </Stack>
       </div>

package/src/admin/UserDetail.tsx

@@ -13,6 +13,7 @@ import { useRecord } from "../useRecord";
 import { useToast } from "../toast";
 import { Button } from "../ui/Button";
 import { Input } from "../ui/Input";
+import { useFormatDateTime } from "../format";
 import { useStrings } from "../uiText";
 import { unwrap } from "../unwrap";
 
@@ -30,6 +31,7 @@ export function UserDetail() {
   const userId = useDeclaredParam("userId");
   const client = useTerpClient();
   const strings = useStrings();
+  const formatDateTime = useFormatDateTime();
   const toast = useToast();
   const [pendingLifecycle, setPendingLifecycle] = useState<PendingLifecycle | null>(null);
   const [mutating, setMutating] = useState(false);
@@ -173,7 +175,7 @@ export function UserDetail() {
               label: strings.statusColumn,
               value: record.is_active ? strings.statusActive : strings.statusDeactivated,
             },
-            { label: strings.createdColumn, value: new Date(record.created_at).toLocaleString() },
+            { label: strings.createdColumn, value: formatDateTime(record.created_at) },
           ]}
         />
       )}
@@ -211,6 +213,7 @@ export function UserDetail() {
           <Field label={strings.newPassword}>
             <Input
               type="password"
+              autoComplete="new-password"
               value={resetPassword}
               onChange={(event) => setResetPassword(event.target.value)}
               required

package/src/admin/UsersAdmin.tsx

@@ -9,6 +9,7 @@ import { useTerpClient } from "../TerpProvider";
 import { DataView, HttpDataViewRepository, useServerDataView } from "../dataview";
 import type { DataViewColumn } from "../dataview";
 import { Button } from "../ui/Button";
+import { useFormatDate } from "../format";
 import { useStrings } from "../uiText";
 import type { TerpStrings } from "../uiText";
 import { unwrap } from "../unwrap";
@@ -18,7 +19,10 @@ import { adminRoleLabel } from "./roles";
 
 type UserRead = components["schemas"]["UserRead"];
 
-function buildColumns(strings: TerpStrings): DataViewColumn<UserRead>[] {
+function buildColumns(
+  strings: TerpStrings,
+  formatDate: (value: string) => string,
+): DataViewColumn<UserRead>[] {
   return [
     { id: "email", header: strings.email, accessor: (u) => u.email, meta: { mobileSlot: "title" } },
     {
@@ -26,20 +30,20 @@ function buildColumns(strings: TerpStrings): DataViewColumn<UserRead>[] {
       header: strings.role,
       accessor: (u) => u.role,
       cell: (u) => adminRoleLabel(strings, u.role),
-      meta: { mobileSlot: "subtitle", width: 100 },
+      meta: { mobileSlot: "subtitle", width: "xs" },
     },
     {
       id: "is_active",
       header: strings.statusColumn,
       accessor: (u) => (u.is_active ? strings.statusActive : strings.statusDeactivated),
-      meta: { mobileSlot: "status", width: 110 },
+      meta: { mobileSlot: "status", width: "sm" },
     },
     {
       id: "created_at",
       header: strings.createdColumn,
       accessor: (u) => u.created_at,
-      cell: (u) => new Date(u.created_at).toLocaleDateString(),
-      meta: { mobileSlot: "date", width: 120 },
+      cell: (u) => formatDate(u.created_at),
+      meta: { mobileSlot: "date", width: "sm" },
     },
   ];
 }
@@ -55,7 +59,11 @@ export function UsersAdmin() {
   const navigate = useNavigate();
   const serverQuery = useServerDataView({ initialPageSize: 10 });
 
-  const columns = useMemo(() => buildColumns(strings), [strings]);
+  const formatDate = useFormatDate();
+  const columns = useMemo(
+    () => buildColumns(strings, formatDate),
+    [strings, formatDate],
+  );
   const repository = useMemo(
     () =>
       new HttpDataViewRepository<UserRead>({

package/src/admin/admin.test.tsx

@@ -8,14 +8,15 @@ import type { ComponentType } from "react";
 
 import { withAdminArea } from "../bootstrap";
 import type { AdminAreaSections } from "../bootstrap";
+import { formatDateTime } from "../format";
 import { buildAppRouter } from "../router";
 import { Page } from "../Page";
 import { TerpProvider, useAuth } from "../TerpProvider";
 import { ToastProvider } from "../toast";
 
-function jsonResponse(body: unknown): Response {
+function jsonResponse(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), {
-    status: 200,
+    status,
     headers: { "content-type": "application/json" },
   });
 }
@@ -313,7 +314,27 @@ function stubAdminFetch() {
       });
     }
     if (path.endsWith("/api/v1/audit/")) {
-      return jsonResponse(emptyPage);
+      // One row, and it earns its place rather than padding the fixture: the audit screen's
+      // expanded panel is the only place the payload renders, so with an empty page that
+      // <pre> — and the `tabIndex` that keeps its scroll container reachable — could not be
+      // asserted anywhere. The comment below this fixture used to say exactly that.
+      return jsonResponse({
+        items: [
+          {
+            id: "e1",
+            created_at: "2026-08-21T09:30:00Z",
+            action: "update",
+            target_type: "sync_definition",
+            target_id: "4d2c1b7e-0000-4000-8000-000000000001",
+            actor_id: "9f2c1b7e-0000-4000-8000-000000000002",
+            request_id: "req_01HQ8ZK4",
+            payload: { window: "02:00-04:00 UTC", retention_days: 90 },
+          },
+        ],
+        total: 1,
+        skip: 0,
+        limit: 25,
+      });
     }
     return jsonResponse(emptyPage);
   });
@@ -440,6 +461,48 @@ describe("the packaged admin area", () => {
     })).toBe(true);
   });
 
+  it("puts a 422's reason under the field it names instead of floating it in a toast", async () => {
+    // The failure path had no test at all, which is how the framework shipped `Field.error` with
+    // no production consumer for two releases: the rendering half was gated, the producing half
+    // did not exist, and nothing exercised the seam between them.
+    //
+    // The two assertions are deliberately different strings. `Field` shows the server's bare
+    // `msg`; the toast shows the joined `path: msg` sentence that `unwrap` has always produced.
+    // Asserting only the first would stay green if BOTH appeared, which is the failure mode worth
+    // guarding — three channels for one problem is what this commit set out to stop.
+    const { fetchMock } = renderAdminApp("/admin/users/new");
+    await screen.findByRole("heading", { level: 1, name: "Provision user" });
+    // A uniqueness violation, not a malformed address, and the choice is not incidental: the
+    // browser rejects a malformed one before any request leaves, so `type="email"` would have
+    // caught it and the POST would never happen (jsdom enforces that too, which is how the first
+    // draft of this test failed). What is left over after the four HTML constraint attributes
+    // have done their work is exactly what the server alone knows, and that is the class of
+    // reason this whole channel exists to carry.
+    const passthrough = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const request = input as Request;
+      if (request.method === "POST" && request.url.endsWith("/api/v1/users/")) {
+        return jsonResponse(
+          { detail: [{ loc: ["body", "email"], msg: "Email address is already registered" }] },
+          422,
+        );
+      }
+      return passthrough(input, init);
+    });
+
+    fireEvent.change(screen.getByLabelText("Email"), { target: { value: "taken@example.com" } });
+    fireEvent.change(screen.getByLabelText("Password"), { target: { value: "strong-password" } });
+    fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
+
+    const shown = await screen.findByText("Email address is already registered");
+    expect(shown.getAttribute("data-terp")).toBe("field-error");
+    expect(screen.getByLabelText("Email")).toHaveAttribute("aria-invalid", "true");
+    expect(screen.queryByText("email: Email address is already registered")).toBeNull();
+    // Still on the create page: a rejected submit must not navigate away from the input it is
+    // asking the user to fix.
+    expect(screen.getByRole("heading", { level: 1, name: "Provision user" })).toBeInTheDocument();
+  });
+
   it("confirms lifecycle mutations from the user detail action slot", async () => {
     const { fetchMock } = renderAdminApp("/admin/users/u1");
     await screen.findByRole("heading", { level: 1, name: "jane.doe@example.com" });
@@ -519,16 +582,126 @@ describe("the packaged admin area", () => {
     );
   });
 
+  it("still says something when the 422 names a field the form does not render", async () => {
+    // The hole in the obvious version of this pattern: a non-empty `fields` suppressed the toast
+    // on the way out, and if no key matched an input, the state it set was read by nothing. The
+    // user pressed Save and NOTHING happened — no field lit up, no message, no navigation. A
+    // failed write that reports nothing is worse than the floating toast it replaced.
+    //
+    // This also proves the sibling test's `queryByText(...).toBeNull()` is not vacuous: the toast
+    // really does render the joined `path: msg` sentence as findable text, so an assertion that
+    // it is absent is an assertion about something that could otherwise have been there.
+    const { fetchMock } = renderAdminApp("/admin/users/new");
+    await screen.findByRole("heading", { level: 1, name: "Provision user" });
+    const passthrough = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const request = input as Request;
+      if (request.method === "POST" && request.url.endsWith("/api/v1/users/")) {
+        return jsonResponse(
+          { detail: [{ loc: ["body", "organization_id"], msg: "Not allowed for this tenant" }] },
+          422,
+        );
+      }
+      return passthrough(input, init);
+    });
+
+    fireEvent.change(screen.getByLabelText("Email"), {
+      target: { value: "new.account@example.com" },
+    });
+    fireEvent.change(screen.getByLabelText("Password"), { target: { value: "strong-password" } });
+    fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
+
+    expect(
+      await screen.findByText("organization_id: Not allowed for this tenant"),
+    ).toBeInTheDocument();
+    // And nothing was marked invalid, because none of these inputs is the one the server meant.
+    expect(screen.getByLabelText("Email")).not.toHaveAttribute("aria-invalid");
+    expect(screen.getByLabelText("Password")).not.toHaveAttribute("aria-invalid");
+  });
+
+  it("shows the field it can and still toasts the reason it cannot, when a 422 names both", async () => {
+    // The mixed envelope is the case the `leftover` flag exists for, and the only one that
+    // distinguishes it: with no renderable reason at all the toast fires anyway because `shown` is
+    // empty, so a mutation neutering `leftover` stayed green until this test existed. Here `email`
+    // finds its input and `organization_id` does not, and BOTH have to reach the user.
+    const { fetchMock } = renderAdminApp("/admin/users/new");
+    await screen.findByRole("heading", { level: 1, name: "Provision user" });
+    const passthrough = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const request = input as Request;
+      if (request.method === "POST" && request.url.endsWith("/api/v1/users/")) {
+        return jsonResponse(
+          {
+            detail: [
+              { loc: ["body", "email"], msg: "Email address is already registered" },
+              { loc: ["body", "organization_id"], msg: "Not allowed for this tenant" },
+            ],
+          },
+          422,
+        );
+      }
+      return passthrough(input, init);
+    });
+
+    fireEvent.change(screen.getByLabelText("Email"), { target: { value: "taken@example.com" } });
+    fireEvent.change(screen.getByLabelText("Password"), { target: { value: "strong-password" } });
+    fireEvent.click(screen.getByRole("button", { name: "Provision user" }));
+
+    const shown = await screen.findByText("Email address is already registered");
+    expect(shown.getAttribute("data-terp")).toBe("field-error");
+    expect(screen.getByLabelText("Email")).toHaveAttribute("aria-invalid", "true");
+    // The reason with nowhere to go is still said out loud, in the joined sentence.
+    expect(
+      screen.getByText(
+        "email: Email address is already registered; organization_id: Not allowed for this tenant",
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it("renders its dates through the framework helper, not the built-in", async () => {
+    // What this gates is the CONVERSION, not the locale channel, and the distinction is worth
+    // naming: `renderAdminApp` mounts no `LocaleProvider`, so `useFormatDateTime` resolves an
+    // undefined locale and both sides of the assertion below say `undefined`. That the hook reads
+    // a provider at all is gated in format.test.tsx, by rendering two locales against each other.
+    //
+    // Here the teeth are in the negative half. Both spellings render the same instant and differ
+    // only in shape, so asserting the new one alone would stay green on a host whose default
+    // happened to agree with it. Asserting the old one is absent cannot be satisfied that way.
+    //
+    // Only one admin screen has a specimen (`admin-user-create`) and it renders no date, so
+    // nothing pictures these cells and nothing asserted their text before this — which is how
+    // seven of them sat on a locale-less built-in through two releases.
+    const when = "2026-08-21T09:30:00Z";
+    renderAdminApp("/admin/audit");
+    expect(await screen.findByText(formatDateTime(when, undefined))).toBeInTheDocument();
+    expect(screen.queryByText(new Date(when).toLocaleString())).toBeNull();
+  });
+
+  it("puts an unresolvable email under the member input rather than in a toast", async () => {
+    // Not a 422 — the directory simply has no match — but it is a statement about the email the
+    // user just typed, on a form whose only input is that email. Answering the server's reasons
+    // on the field and this one above it would be a distinction the user cannot perceive, so the
+    // routing follows what the message is about rather than where it came from.
+    renderAdminApp("/admin/groups/g1");
+    await screen.findByRole("heading", { level: 1, name: "Finance" });
+    fireEvent.change(screen.getByPlaceholderText("Email"), {
+      target: { value: "nobody@example.com" },
+    });
+    fireEvent.submit(screen.getByRole("button", { name: "Add member" }).closest("form")!);
+    const shown = await screen.findByText("No account matches that email.");
+    expect(shown.getAttribute("data-terp")).toBe("field-error");
+  });
+
   it("marks the detail sections it no longer styles inline", async () => {
     // The second of the three surfaces the admin views used to style at the call site. Same
     // reasoning as the create form above: markers plus the absence of a style attribute,
     // because no admin screen has a specimen.
     //
-    // The third, the audit payload, has no assertion here and it is worth saying why rather
-    // than quietly having none: the audit fixture serves an empty page, so no row exists to
-    // expand and the <pre> never renders in any test. Giving it one means adding rows to a
-    // fixture several tests share, which is not a change a styling migration should make.
-    // It is held by styles.test.ts (the rule exists) and by the values being a verbatim copy.
+    // The third, the audit payload, has its own test below now. It had none for a while, and
+    // the reason was recorded here rather than left implicit: the audit fixture served an empty
+    // page, so no row existed to expand and the <pre> never rendered in any test. That stayed
+    // true until the payload gained a `tabIndex` — a claim about the real component that no
+    // workbench specimen can make, because the specimen writes its own markup.
     renderAdminApp("/admin/groups/g1");
     const headings = await waitFor(() => {
       const found = document.querySelectorAll('[data-terp="admin-section-title"]');
@@ -541,6 +714,37 @@ describe("the packaged admin area", () => {
     }
   });
 
+  it("keeps the audit payload's scroll container reachable by keyboard", async () => {
+    // The gate for the SC 2.1.1 fix, and it has to be here rather than in the workbench.
+    // `code-block` declares `overflow-x: auto`, so a wide payload is a scroll container, and a
+    // scroll container no keyboard can reach is what axe reports as
+    // `scrollable-region-focusable`. The workbench specimen renders its own markup, so every lane
+    // there would stay green with the attribute gone from what this screen renders — the specimen
+    // would be asserting its own fixture back to itself. This reads the packaged screen.
+    //
+    // It also pins the substitution: the audit panel renders `Code block` now rather than a
+    // hand-rolled <pre> under a marker of its own, and if that reverted this would find the wrong
+    // marker rather than nothing at all.
+    renderAdminApp("/admin/audit");
+    // Expanding the row is what renders the panel; the trigger is the row's own expand control.
+    const expand = await waitFor(() => {
+      const found = document.querySelector('[data-terp="dataview-expand-cell"] button');
+      expect(found).not.toBeNull();
+      return found as HTMLButtonElement;
+    });
+    fireEvent.click(expand);
+    const payload = await waitFor(() => {
+      const found = document.querySelector('[data-terp="code-block"]');
+      expect(found).not.toBeNull();
+      return found as HTMLElement;
+    });
+    expect(payload.tagName).toBe("PRE");
+    expect(payload.tabIndex).toBe(0);
+    // And still no inline style — the third of the three surfaces the admin views used to
+    // style at the call site, which is what the note above refers to.
+    expect(payload.getAttribute("style")).toBeNull();
+  });
+
   it("clears group destructive state when navigating between detail records in place", async () => {
     const { router } = renderAdminApp("/admin/groups/g1");
     await screen.findByRole("heading", { level: 1, name: "Finance" });

package/src/admin/fieldErrors.ts

@@ -0,0 +1,45 @@
+import { ApiError } from "../unwrap";
+
+/** What a form should do with a failure: what to put on inputs, and whether anything is left over. */
+export interface RoutedFieldErrors {
+  /** Reasons naming a field this form actually renders, ready for `Field`'s `error` prop. */
+  shown: Record<string, string>;
+  /** At least one reason named something this form has no input for. */
+  leftover: boolean;
+}
+
+/**
+ * Split a failure's per-field reasons into the ones a form can show and the ones it cannot.
+ *
+ * The naive version of this — "if `fields` is non-empty, set them and return" — has a hole that is
+ * invisible until it happens: a reason naming a field the form does not render sets state nobody
+ * reads and suppresses the toast on the way out, so the user presses Save and *nothing appears*.
+ * No field lights up, no message, no navigation. A failed write that reports nothing is worse than
+ * the floating toast this replaced.
+ *
+ * The packaged forms cannot hit it today, because FastAPI's 422 can only name a key of the body
+ * they submitted and they render every one of those. That is a fact about these three endpoints,
+ * not about the pattern: a `terp.core.AppError` carrying `details` addresses whatever the rule
+ * checked, an app's form is free to submit a field it does not display, and this is the shape apps
+ * copy. `GroupDetail` already had it right by naming its one key and falling through to the toast
+ * when the server named a different one; this is that discipline, for a form with several.
+ *
+ * Not exported from the package. It becomes public API when something outside `admin/` needs it.
+ */
+export function routeFieldErrors(
+  error: unknown,
+  rendered: readonly string[],
+): RoutedFieldErrors {
+  const shown: Record<string, string> = {};
+  let leftover = false;
+  if (error instanceof ApiError) {
+    for (const [key, message] of Object.entries(error.fields)) {
+      if (rendered.includes(key)) {
+        shown[key] = message;
+      } else {
+        leftover = true;
+      }
+    }
+  }
+  return { shown, leftover };
+}