@terpjs/react-core 0.9.0 → 0.10.0

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

package/src/bootstrap.test.tsx

@@ -64,4 +64,212 @@ describe("renderTerpApp", () => {
     );
     root.remove();
   });
+
+  it("forwards the layout declaration to buildAppRouter", () => {
+    // Same shape as the navGroups test below, for the same reason: the forwarding is one line in
+    // a hand-written enumeration, and a missing line leaves every gate on the declaration green
+    // while the one-call entry point — the one apps actually use — ignores the file entirely.
+    //
+    // Gated through a refusal only `buildAppRouter` can raise, and that took a second attempt.
+    // The first version asserted the resolver's enum refusal — which `renderTerpApp` now raises
+    // ITSELF, from its own resolve call, before `buildAppRouter` is reached. So it threw with
+    // the forwarding line deleted and reported green: a test that passes with the bug. An
+    // UNKNOWN CONTRACT is refused only inside `buildAppRouter`, against its own table, so the
+    // throw here observes the one line under test and nothing else.
+    //
+    // Mutation: delete `layout: options.layout` from the buildAppRouter call, and this stops
+    // throwing.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { contract: "bespoke" },
+          rootElement: root,
+        }),
+      ).toThrow(/Unknown layout contract "bespoke"/);
+    } finally {
+      root.remove();
+    }
+  });
+
+  it("opens on the palette the declaration names, and on the option when it does not", async () => {
+    // The forwarding tests above gate their line through a THROW, because a signed-out mount
+    // renders no shell to read. The palette is the exception and gets the stronger assertion:
+    // `ThemeProvider` wraps `RequireAuth`, so it mounts signed out, and the attribute it writes
+    // on <html> is the actual observable effect an app ships. A throw here would only prove the
+    // file was validated, not that the value reached anything.
+    //
+    // Mutations, both red, and both by reading NULL rather than "midnight": `"system"` is the
+    // provider's default and it REMOVES the attribute, so neither mutation can produce the
+    // string. (An earlier version of this comment said the first one reads "system", which is
+    // not a value `data-theme` ever holds.) Pass `options.defaultTheme` to `ThemeProvider`
+    // instead of `layout.defaultTheme`, or drop `defaultTheme` from the explicit set handed to
+    // the resolver, and the corresponding assertion reads null.
+    for (const [label, options] of [
+      ["from the file", { layout: { defaultTheme: "midnight" } }],
+      ["from the option", { defaultTheme: "midnight" as const }],
+    ] as const) {
+      // A stored choice outranks the default — that is the whole point of a *default* — so the
+      // assertion would be about localStorage rather than about the declaration without this.
+      window.localStorage.clear();
+      document.documentElement.removeAttribute("data-theme");
+      const root = document.createElement("div");
+      document.body.appendChild(root);
+      try {
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          rootElement: root,
+          ...options,
+        });
+        await waitFor(() =>
+          expect(
+            document.documentElement.getAttribute("data-theme"),
+            `${label}: the declared palette must reach <html>`,
+          ).toBe("midnight"),
+        );
+      } finally {
+        root.remove();
+        document.documentElement.removeAttribute("data-theme");
+      }
+    }
+  });
+
+  it("refuses the palette named in the file and passed as an option", () => {
+    // Non-exclusive per ADR 0009 — either source alone is complete, as the test above shows —
+    // but not both, and not even when they agree. Reachable only through `renderTerpApp`,
+    // because `buildAppRouter` has no palette option to conflict with.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { defaultTheme: "midnight" },
+          defaultTheme: "midnight",
+          rootElement: root,
+        }),
+      ).toThrow(/both declare "defaultTheme" \(file: "midnight", code: "midnight"\)/);
+    } finally {
+      root.remove();
+    }
+  });
+
+  it("names every doubly-declared key at once, groups included", async () => {
+    // The property the resolver's `conflicts.join("; ")` exists for, asserted through the entry
+    // point apps use — and it was broken here. `renderTerpApp` resolves the declaration itself
+    // (the palette mounts outside the router) and its explicit set omitted `navGroups`, so a
+    // groups conflict was invisible from this side: the author fixed the density conflict,
+    // re-ran, and hit a second, different refusal. Mutation: drop `navGroups: options.navGroups`
+    // from the resolve call at the top of `renderTerpApp` and this names only the density.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    let message = "";
+    try {
+      renderTerpApp({
+        title: "Test",
+        modules: { "./modules/notes/module.tsx": notesModule },
+        layout: {
+          shell: {
+            density: "comfortable",
+            navGroups: [{ id: "work", label: "Workspace" }],
+          },
+        },
+        density: "compact",
+        navGroups: [{ id: "admin", label: "Admin" }],
+        rootElement: root,
+      });
+    } catch (error) {
+      message = (error as Error).message;
+    } finally {
+      root.remove();
+    }
+    expect(message).toContain('"shell.density"');
+    expect(message).toContain('"shell.navGroups"');
+  });
+
+  it("refuses the navigation groups named in the file and passed as an option", () => {
+    // The array key travelling the same seam as the scalars, end to end: the resolver sees the
+    // file, `buildAppRouter` hands the resolved list to the shell, and declaring the groups in
+    // both places is one fact declared twice. Named by id, because a list of objects stringified
+    // into an error message tells the reader nothing they can match up.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: { shell: { navGroups: [{ id: "work", label: "Workspace" }] } },
+          navGroups: [{ id: "admin", label: "Admin" }],
+          rootElement: root,
+        }),
+      ).toThrow(/both declare "shell\.navGroups" \(file: "work", code: "admin"\)/);
+    } finally {
+      root.remove();
+    }
+  });
+
+  it("refuses duplicate ids declared in the file, through the router's own check", () => {
+    // The check lives in `buildAppRouter` and now reads the RESOLVED list, so this is the proof
+    // that a duplicate reaches it from the file and not only from the option. Mutation: point
+    // the check back at `options.navGroups` and this stops throwing while the option-side test
+    // above stays green.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          layout: {
+            shell: {
+              navGroups: [
+                { id: "work", label: "Workspace" },
+                { id: "work", label: "Again" },
+              ],
+            },
+          },
+          rootElement: root,
+        }),
+      ).toThrow(/duplicate id\(s\): work/);
+    } finally {
+      root.remove();
+    }
+  });
+
+  it("forwards navGroups to buildAppRouter", () => {
+    // `renderTerpApp` hands its options to `buildAppRouter` through a hand-written enumeration of
+    // names, and nothing covered it — `navPlacement`, `contentWidth` and `density` all travel that
+    // same list with no assertion that any of them arrives. A missing line there leaves every
+    // other gate on groups green while the feature does nothing for every app using the one-call
+    // entry point, which is the entry point apps actually use.
+    //
+    // Gated through the duplicate-id refusal rather than through a rendered label, and that is
+    // the point of doing it this way: this test mounts the SIGNED-OUT app, so the shell never
+    // renders and there is no nav to read. The throw only happens if the option was forwarded, so
+    // it observes the one line under test and nothing else. Mutation: delete
+    // `navGroups: options.navGroups` from the buildAppRouter call, and this stops throwing.
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    try {
+      expect(() =>
+        renderTerpApp({
+          title: "Test",
+          modules: { "./modules/notes/module.tsx": notesModule },
+          navGroups: [
+            { id: "work", label: "Werkruimte" },
+            { id: "work", label: "Weer werkruimte" },
+          ],
+          rootElement: root,
+        }),
+      ).toThrow(/duplicate id\(s\): work/);
+    } finally {
+      root.remove();
+    }
+  });
 });