@terpjs/react-core 0.9.0 → 0.11.0

package/src/EmptyState.tsx

@@ -19,6 +19,17 @@ export interface EmptyStateProps {
   description?: ReactNode;
   /** Optional call to action (typically a `Button`). */
   action?: ReactNode;
+  /**
+   * `"compact"` for an empty block that is not the whole screen.
+   *
+   * The default is sized to be the only thing on a page — generous padding, a 2rem
+   * glyph, centred. That is right for an empty list and wrong the moment a screen has two
+   * of them: stacked, they were 480px of chrome repeating a sentence, and the emptiness of
+   * one section is not the page's headline. Compact keeps the frame and the wording and
+   * takes back the space — tighter padding, a smaller glyph, left-aligned, because a
+   * block that is one item among several reads as a row rather than a poster.
+   */
+  size?: "default" | "compact";
 }
 
 /**
@@ -27,15 +38,24 @@ export interface EmptyStateProps {
  * UX platform-wide tells the user "this is not an error — there is just nothing to show",
  * and the `action` slot turns the dead end into the obvious next step.
  */
-export function EmptyState({ icon, title, description, action }: EmptyStateProps) {
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  size = "default",
+}: EmptyStateProps) {
   const resolve = useUiText();
+  const compact = size === "compact";
   const leading = icon ?? (
     <span data-terp="empty-state-icon">
-      <Icon name="inbox" size="2rem" />
+      <Icon name="inbox" size={compact ? "1.25rem" : "2rem"} />
     </span>
   );
+  // Stamped only for `compact`: the full-page block's geometry IS the base rule, the same
+  // shape `Button`'s sizes and the shell's density take.
   return (
-    <div data-terp="empty-state">
+    <div data-terp="empty-state" data-size={compact ? "compact" : undefined}>
       {leading}
       <p data-terp="empty-state-title">{resolve(title)}</p>
       {description !== undefined && <div data-terp="empty-state-description">{description}</div>}

package/src/Field.test.tsx

@@ -22,6 +22,36 @@ describe("Field", () => {
     expect(screen.getByText("required")).toBeInTheDocument();
   });
 
+  it("exposes the error as an alert, and nothing else in the field", () => {
+    // `aria-describedby` is read when focus reaches the control. That covers an error which was
+    // already there and covers nothing about one that arrives on submit, when focus has left the
+    // field and the only thing that changed is a span nobody is pointed at. The two channels fire
+    // at different moments, and a submit-time rejection only has the second one.
+    //
+    // The length assertion is the half with teeth: `role="alert"` on the hint as well would
+    // satisfy a bare `getByRole` while training the user to ignore the channel the error needs.
+    // Mutation: drop `role="alert"` from the span and the lookup finds nothing.
+    render(
+      <Field label="Email" hint="we never share it" error="required">
+        <Input defaultValue="" />
+      </Field>,
+    );
+    expect(screen.getAllByRole("alert")).toHaveLength(1);
+    expect(screen.getByRole("alert")).toHaveTextContent("required");
+  });
+
+  it("raises no alert when there is nothing wrong", () => {
+    // An alert that is present on every render is an alert that means nothing. The span is
+    // conditional, so it enters the accessibility tree exactly when the error appears, which is
+    // the event the role exists to report.
+    render(
+      <Field label="Email" hint="we never share it">
+        <Input defaultValue="" />
+      </Field>,
+    );
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
   it("renders no error node when error is null", () => {
     render(
       <Field label="Name" error={null}>

package/src/Field.tsx

@@ -31,6 +31,14 @@ export interface FieldProps {
  * declares either keeps its own value; the field adds to `aria-describedby` rather than replacing
  * it. `Input`, `Select`, `Textarea` and `Combobox` all spread their props onto the DOM element, so
  * the attributes land where assistive tech reads them.
+ *
+ * The error also carries `role="alert"`, and `aria-describedby` is why it has to. A description is
+ * read when focus reaches the control, which covers an error that was already there and covers
+ * nothing about one that appears on submit — by then focus has left the field, or the button, and
+ * the only thing that changed is a span nobody is pointed at. The two are not redundant: they
+ * announce at different moments, and a submit-time rejection only has the second one. Because the
+ * span is conditional, it enters the accessibility tree exactly when the error appears, which is
+ * the event `alert` exists to report.
  */
 export function Field({ label, children, error, hint }: FieldProps) {
   const resolve = useUiText();
@@ -39,17 +47,35 @@ export function Field({ label, children, error, hint }: FieldProps) {
   const hintId = hint !== undefined ? `${baseId}-hint` : undefined;
   const errorId = hasError ? `${baseId}-error` : undefined;
   const described = [hintId, errorId].filter((id) => id !== undefined).join(" ");
+  const labelId = `${baseId}-label`;
 
-  // Only a single element child can be described — which is the documented contract ("the
-  // control"). Anything else is passed through untouched rather than guessed at.
-  const control = described.length > 0 && isValidElement<{
+  // Only a single element child can be named and described — which is the documented contract
+  // ("the control"). Anything else is passed through untouched rather than guessed at.
+  const control = isValidElement<{
     "aria-describedby"?: string;
     "aria-invalid"?: boolean | "true" | "false";
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
   }>(children)
     ? cloneElement(children, {
-        "aria-describedby": [children.props["aria-describedby"], described]
-          .filter((id) => id !== undefined && id !== "")
-          .join(" "),
+        // The control is named by the label TEXT, not by the label element's subtree, and that
+        // distinction is the whole reason this exists. A wrapping label takes its name from
+        // everything inside it, so a control that renders an adornment of its own — the password
+        // reveal is the first — hands its own button's name to the field: Chromium computes
+        // "Password Show password" for that input, which is a WCAG 2.5.3 failure and a sentence
+        // no voice-control user can see to say. Pointing at the span makes the name exact.
+        //
+        // A caller that named the control itself keeps their name; this never overrides one.
+        "aria-labelledby":
+          children.props["aria-label"] === undefined
+            ? (children.props["aria-labelledby"] ?? labelId)
+            : undefined,
+        "aria-describedby":
+          described.length > 0
+            ? [children.props["aria-describedby"], described]
+                .filter((id) => id !== undefined && id !== "")
+                .join(" ")
+            : children.props["aria-describedby"],
         "aria-invalid": children.props["aria-invalid"] ?? (hasError ? true : undefined),
       })
     : children;
@@ -57,7 +83,9 @@ export function Field({ label, children, error, hint }: FieldProps) {
   return (
     <div data-terp="field">
       <label data-terp="field-label">
-        <span data-terp="field-label-text">{resolve(label)}</span>
+        <span id={labelId} data-terp="field-label-text">
+          {resolve(label)}
+        </span>
         {control}
       </label>
       {hint !== undefined && (
@@ -66,7 +94,7 @@ export function Field({ label, children, error, hint }: FieldProps) {
         </span>
       )}
       {hasError && (
-        <span id={errorId} data-terp="field-error">
+        <span id={errorId} role="alert" data-terp="field-error">
           {error}
         </span>
       )}

package/src/FormPage.tsx

@@ -0,0 +1,54 @@
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { LayoutSlotContext } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+
+export interface FormPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /**
+   * The layers this form sits under, outermost first — the list it was reached from, and
+   * anything above that.
+   *
+   * Required, and for the reason `DetailPage`'s is: a create or edit screen is always reached
+   * from somewhere, and a form with no way back is a dead end with unsaved work in it.
+   */
+  parents: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The form archetype: one create-or-edit screen, reached from the collection it writes into.
+ *
+ * It is a `Page` with two things fixed. The frame is `measure="narrow"` by default — header
+ * included — because a form is a single column of controls and a Save button a screen-width
+ * from its last field is worse than one sitting over it. And the body slot admits the shape a
+ * form actually has rather than the shape a record screen has.
+ *
+ * **The body is a container, so `Field` is deliberately not admitted directly.** The slot takes
+ * the form container, plus `Grid` for a two-column arrangement inside a wide form, `Card` for a
+ * grouped section, `Divider` and `Text` between them, and the framework states.
+ *
+ * What that refusal does and does not buy is worth stating exactly, because the obvious claim is
+ * too strong. It keeps fields out of the top level, so a form body is always a container — which
+ * is the shape the archetype is for. It does **not** guarantee the form can be submitted: both
+ * halves of the contract match on `data-terp` markers, and `Stack` renders the same marker
+ * whether or not it was given `as="form"`. So `<Stack><Field/></Stack>` passes and is still
+ * unsubmittable by Enter. Closing that would mean a second marker for the form case, which is
+ * six more names describing the same DOM — the `Section` trade 4b already declined.
+ *
+ * It renders no element of its own — the slot context and `Page`, nothing between them, because
+ * a wrapper around the body would become the sole entry in `article.children` and fail every
+ * governed page closed (ADR 0079).
+ */
+export function FormPage({ parents, measure = "narrow", ...page }: FormPageProps) {
+  return (
+    <LayoutSlotContext.Provider value="FormPage">
+      {/* Spread FIRST, then the archetype's own props — `HubPage`'s order, not
+          `DetailPage`'s. `Omit<PageProps, "breadcrumbs">` removes the key from the type but not
+          from a runtime object, and a JSX spread gets no excess-property check: a wrapper
+          forwarding `{...props}` with a present-but-undefined `breadcrumbs` would otherwise
+          overwrite `parents` and silently drop the trail this archetype requires.
+          (`DetailPage` and `OverviewPage` still spread last. Same latent shape, pre-existing,
+          and left for a change that can re-record their baselines rather than this one.) */}
+      <Page {...page} breadcrumbs={parents} measure={measure} />
+    </LayoutSlotContext.Provider>
+  );
+}

package/src/LoginView.test.tsx

@@ -51,7 +51,39 @@ describe("LoginView dev credentials", () => {
       </TerpProvider>,
     );
     fireEvent.click(await screen.findByRole("button", { name: "Fill dev credentials" }));
-    expect(screen.getByPlaceholderText("Email")).toHaveValue("admin@example.test");
-    expect(screen.getByPlaceholderText("Password")).toHaveValue("correct horse battery staple");
+    // By label, not by placeholder. Reaching for a placeholder here was itself a symptom:
+    // it was the only handle these inputs had.
+    expect(screen.getByLabelText("Email")).toHaveValue("admin@example.test");
+    expect(screen.getByLabelText("Password")).toHaveValue("correct horse battery staple");
+  });
+});
+
+describe("LoginView accessible names", () => {
+  it("labels both credentials so they survive typing and can be addressed by name", async () => {
+    // The first screen of every Terp app, and it was labelled by placeholder alone. A
+    // placeholder is not an accessible name and it disappears the moment someone types, so
+    // the field a user is halfway through filling had nothing identifying it (WCAG 3.3.2)
+    // — and `getByLabel` could not find either input, which made the one screen every app
+    // ships the one screen its own tests could not address by name.
+    stubFetch();
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LoginView />
+      </TerpProvider>,
+    );
+    await screen.findByRole("heading", { name: "Sign in" });
+
+    const email = screen.getByLabelText("Email");
+    const password = screen.getByLabelText("Password");
+    expect(email).toHaveAttribute("type", "email");
+    expect(password).toHaveAttribute("type", "password");
+
+    // The name has to survive typing, which is the whole difference from a placeholder.
+    fireEvent.change(email, { target: { value: "someone@example.test" } });
+    expect(screen.getByLabelText("Email")).toHaveValue("someone@example.test");
+
+    // And the autocomplete tokens stay, so a password manager still offers to fill.
+    expect(email).toHaveAttribute("autocomplete", "username");
+    expect(password).toHaveAttribute("autocomplete", "current-password");
   });
 });

package/src/LoginView.tsx

@@ -5,6 +5,7 @@ import { TerpMark } from "./icons";
 import { useAuth, useSso } from "./TerpProvider";
 import { useStrings } from "./uiText";
 import { Button } from "./ui/Button";
+import { Field } from "./Field";
 import { Input } from "./ui/Input";
 import type { SsoProvider } from "./sso";
 
@@ -37,9 +38,16 @@ export interface DevCredentials {
  *
  * It renders no inline styles: the full-viewport page, the card, the brand row, both button
  * groups, the separator and the error line take their geometry and ink from the injected
- * react-core sheet (ADR 0094). The buttons fill their group through a rule on the group
- * rather than a prop on `Button` — `Button` declares `width: fit-content`, so a grid does not
- * stretch them for free, and a `block` prop for one internal caller is API this does not need.
+ * react-core sheet (ADR 0094).
+ *
+ * Two things here used to be worked around and are not any more, which is worth recording
+ * because the workarounds were both reasonable while they lasted. The buttons filled their
+ * group through a rule on the GROUP, because `Button` declares `width: fit-content` — a
+ * definite width, so a grid does not stretch them for free — and a prop for one internal
+ * caller was API the package did not need. `Button` has `fullWidth` now, so the rule retires
+ * and the four call sites say what they mean. And the submit button hand-rolled a busy state
+ * out of `disabled` plus a swapped label; `loading` is that state, and it adds the spinner and
+ * the `aria-busy` the hand-rolled version never had.
  */
 export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps = {}) {
   const auth = useAuth();
@@ -85,27 +93,43 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
           <h1 data-terp="login-title">{strings.signIn}</h1>
         </div>
         <form data-terp="login-form" onSubmit={onSubmit}>
-          <Input
-            type="email"
-            placeholder={strings.email}
-            value={email}
-            onChange={(event) => setEmail(event.target.value)}
-            required
-          />
-          <Input
-            type="password"
-            placeholder={strings.password}
-            value={password}
-            onChange={(event) => setPassword(event.target.value)}
-            required
-          />
-          <Button type="submit" disabled={busy}>
+          {/* Labelled through `Field`, not by placeholder. A placeholder is not an
+              accessible name and it disappears the moment someone types, so the field a
+              user is halfway through filling has nothing identifying it — WCAG 3.3.2 asks
+              for a label that survives typing. It also made these two inputs unreachable
+              by `getByLabel`, so every app's very first screen was the one place its own
+              tests could not address by name. The framework's own answer was already here:
+              `Field` wraps the control in a `<label>`, which is why it needs no id wiring.
+              The comment below is left because it dates the omission — an autocomplete
+              token was considered for these fields and a label was not. */}
+          <Field label={strings.email}>
+            <Input
+              type="email"
+              // Neither field declared an autocomplete token, so no password manager offered to
+              // fill or save this form — the one place in the framework where that matters most.
+              autoComplete="username"
+              value={email}
+              onChange={(event) => setEmail(event.target.value)}
+              required
+            />
+          </Field>
+          <Field label={strings.password}>
+            <Input
+              type="password"
+              autoComplete="current-password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+              required
+            />
+          </Field>
+          <Button type="submit" fullWidth loading={busy}>
             {busy ? strings.signingIn : strings.signIn}
           </Button>
           {devCredentials ? (
             <Button
               type="button"
               variant="secondary"
+              fullWidth
               disabled={busy}
               onClick={() => {
                 setEmail(devCredentials.email);
@@ -130,6 +154,7 @@ export function LoginView({ ssoProviders = [], devCredentials }: LoginViewProps
                   key={provider.name}
                   type="button"
                   variant="secondary"
+                  fullWidth
                   disabled={busy}
                   onClick={() => void onSso(provider)}
                 >

package/src/ModuleNav.test.tsx

@@ -61,16 +61,16 @@ describe("ModuleNav", () => {
     );
     expect(screen.getByRole("link", { name: "Overview" })).not.toHaveAttribute("aria-current");
 
-    // The styling key is data-active, and the point is that it is NOT the aria-current
-    // beside it. A router Link merges its own active props last, so aria-current on this
-    // element has a second author — keying the accent edge on it would be the breadcrumb
-    // defect again the moment the two disagreed about "active", which they can, in BOTH
-    // directions: the router also demands an exact query-string match (so it is narrower
-    // on a filtered URL), and it compares paths through removeTrailingSlash while this
-    // component compares them raw (so it is broader on a trailing slash, and then the
-    // accent edge goes missing on a tab the router calls current). The second is a real
-    // defect, older than the marker — the inline styling read the same isActive — and it
-    // is the navigation model's to fix. Neither case is reachable from this specimen.
+    // The styling key is data-active, and the point is that it is NOT the aria-current beside
+    // it: a router Link merges its own active props last, so that attribute has a second author.
+    //
+    // The divergence this comment used to describe is fixed (ADR 0097 §6, amended in 4e). Both
+    // authors now compute the same thing by construction rather than by coincidence. The
+    // component asks `activeNavPath` over the whole strip; the Link is pinned to
+    // `exact: true, includeSearch: false`, so the router volunteers `aria-current` only when the
+    // path equals the URL — the longest possible match, hence always the tab the predicate
+    // picked. It can agree or stay silent; it cannot name a different tab. Which is why the
+    // assertion below can now demand exactly one `aria-current` in the strip.
     const active = screen.getByRole("link", { name: "Projects" });
     const inactive = screen.getByRole("link", { name: "Overview" });
     expect(active).toHaveAttribute("data-terp", "module-nav-link");
@@ -79,6 +79,13 @@ describe("ModuleNav", () => {
     expect(inactive).not.toHaveAttribute("data-active");
     expect(active.getAttribute("style")).toBeNull();
     expect(inactive.getAttribute("style")).toBeNull();
+
+    // Exactly one, over the whole strip. Before 4e the Link was left prefix-matching, so at
+    // /tickets/projects the router added its own aria-current to the /tickets tab as well and a
+    // screen reader announced two current pages.
+    expect(
+      document.querySelectorAll('[data-terp="module-nav"] [aria-current="page"]'),
+    ).toHaveLength(1);
   });
 
   it("returns nothing for an empty tab list", () => {

package/src/ModuleNav.tsx

@@ -1,13 +1,24 @@
 import { Link, useRouterState } from "@tanstack/react-router";
 
+import { activeNavPath } from "./navActive";
 import { useStrings, useUiText } from "./uiText";
 import type { UiText } from "./uiText";
 
 export interface ModuleNavTab {
   /** Display label. */
   label: UiText;
-  /** Router path for an exact sub-page route. */
+  /** Router path for the sub-page route. */
   to: string;
+  /**
+   * Match this tab's path exactly rather than as a segment-aligned prefix.
+   *
+   * The default is the prefix, so a tab stays current on the pages beneath it — a detail route
+   * under `/records/mapping` keeps "Mapping" lit instead of blanking the strip. Set this on a
+   * landing tab that also has siblings deeper in the same strip, where the prefix would keep it
+   * lit alongside them; the shared predicate resolves that case by longest match anyway, so this
+   * is for the narrower job of a tab owning only itself.
+   */
+  exact?: boolean;
 }
 
 export interface ModuleNavProps {
@@ -32,6 +43,12 @@ export function ModuleNav({ items, ariaLabel }: ModuleNavProps) {
   const strings = useStrings();
   const resolve = useUiText();
   const pathname = useRouterState({ select: (state) => state.location.pathname });
+  // Resolved over the whole strip, not per tab, and through the same function the sidebar uses
+  // (ADR 0097 §6, amended in 4e). Two tabs where one path prefixes the other would otherwise
+  // both be current, and this component previously compared `pathname === item.to` raw — which
+  // diverged from its own Link in both directions, as the sheet's comment on the active rule
+  // says. Longest match wins, so `/records` does not steal from `/records/mapping`.
+  const activeTo = activeNavPath(pathname, items);
 
   if (items.length === 0) {
     return null;
@@ -42,12 +59,27 @@ export function ModuleNav({ items, ariaLabel }: ModuleNavProps) {
       <ul data-terp="module-nav-list">
         {items.map((item) => {
           const label = resolve(item.label);
-          const isActive = pathname === item.to;
+          const isActive = item.to === activeTo;
           return (
             <li key={item.to}>
               <Link
                 to={item.to}
-                activeOptions={{ exact: true }}
+                // `exact` is ALWAYS true here, whatever the tab asked for, and the asymmetry is
+                // the mechanism rather than an oversight. The tab's own `exact` governs the
+                // component's predicate above; this governs when the ROUTER volunteers its own
+                // `aria-current`, and the router decides per link with no knowledge of siblings.
+                // Left non-exact it prefix-matches, so at `/tickets/projects` it would mark the
+                // `/tickets` tab current too — a second current item the component never chose.
+                // Exact matching means "the router thinks this is active" implies the path equals
+                // the URL, which is the longest possible match, which is always the tab the
+                // predicate picked. The router can only agree.
+                //
+                // includeSearch: false for the other half. It defaults to true and on an exact
+                // link demands a full query-string match, so at `/tickets/projects?page=2` the
+                // router's own `data-status` said inactive while this component said active.
+                // Nothing paints from `data-status`, which is exactly why that could sit there
+                // unnoticed.
+                activeOptions={{ exact: true, includeSearch: false }}
                 aria-current={isActive ? "page" : undefined}
                 data-terp="module-nav-link"
                 data-active={isActive ? "true" : undefined}

package/src/Page.tsx

@@ -23,6 +23,23 @@ export interface PageProps {
   renderLink?: RenderBreadcrumbLink;
   /** Optional page-level actions, rendered on the heading row (e.g. a primary `Button`). */
   actions?: ReactNode;
+  /**
+   * Cap the whole frame — header included — at a readable measure (default `"full"`).
+   *
+   * `"narrow"` is the single-column-of-controls shape: a create/edit form, a settings screen.
+   * The header is capped WITH the body here, unlike the shell's own content measure, and that
+   * asymmetry is the point rather than an inconsistency. A wide page with a narrow column wants
+   * its title and actions spanning the full track, because the band is what tells you the page
+   * is wider than its text. A form does not: a Save button floating a screen-width away from
+   * the field it saves is worse than one sitting over it.
+   *
+   * `data-measure` is the same attribute name `Text` uses for the same concept, keyed per
+   * marker, so there is one vocabulary for "measure" rather than two.
+   *
+   * `FormPage` and `SettingsPage` default it on; every other archetype leaves it `"full"`,
+   * which stamps nothing.
+   */
+  measure?: "full" | "narrow";
   /** Show the loading state instead of the body (the header stays for orientation). */
   isLoading?: boolean;
   /** Loading slot; defaults to the standard {@link LoadingState} spinner block. */
@@ -61,6 +78,7 @@ export function Page({
   breadcrumbs,
   renderLink,
   actions,
+  measure = "full",
   isLoading,
   loadingState,
   error,
@@ -107,8 +125,12 @@ export function Page({
     ) : (
       children
     );
+  // Hoisted, the density/collapsed idiom: the default stamps nothing, so the expression has a
+  // branch, and a conditional written at the attribute is the form the marker scanner reads
+  // every string literal out of.
+  const measureAttribute = measure === "narrow" ? "narrow" : undefined;
   return (
-    <article ref={articleRef} data-terp="page">
+    <article ref={articleRef} data-terp="page" data-measure={measureAttribute}>
       {/* A <header> ELEMENT, and it has to stay one. The slot check above drops the header
           from the body set by tagName, so re-rendering this as a marked <div> would put it
           back in and fail every governed OverviewPage / DetailPage closed. The marker is

package/src/ProfileView.test.tsx

@@ -76,7 +76,7 @@ describe("ProfileView", () => {
     // jsdom computes no cascade. The address marker matters most of the three — its
     // overflow-wrap has no specimen, since the mock session's address is short, so this is
     // the only gate that the element a long address would need is still the marked one.
-    const avatar = document.querySelector('[data-terp="profile-avatar"]');
+    const avatar = document.querySelector('[data-terp="avatar"]');
     expect(avatar).not.toBeNull();
     expect(avatar?.textContent).toBe("JD");
     expect(avatar?.getAttribute("style")).toBeNull();

package/src/ProfileView.tsx

@@ -3,7 +3,7 @@ import { useAuth } from "./TerpProvider";
 import { LanguageSwitcher } from "./locale";
 import { Stack, DetailList } from "./layout";
 import { ThemeToggle } from "./theme";
-import { userInitials } from "./UserMenu";
+import { Avatar } from "./ui/Avatar";
 import { Button } from "./ui/Button";
 import { useStrings } from "./uiText";
 
@@ -29,9 +29,7 @@ export function ProfileView() {
       <Stack gap={4}>
         <div data-terp="profile-card">
           <Stack direction="row" gap={3} align="center">
-            <span aria-hidden="true" data-terp="profile-avatar">
-              {userInitials(user.email)}
-            </span>
+            <Avatar from={user.email} />
             <Stack gap={0}>
               <strong data-terp="profile-email">{user.email}</strong>
               <p data-terp="profile-role">{user.role_name}</p>

package/src/SettingsPage.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+import type { BreadcrumbItem } from "./Breadcrumbs";
+import { LayoutSlotContext } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+
+export interface SettingsPageProps extends Omit<PageProps, "breadcrumbs"> {
+  /**
+   * Optional parent layers, for a settings screen nested under an area rather than reached
+   * from the account menu.
+   *
+   * Optional where `FormPage`'s is required, and the difference is real: a form is always
+   * reached from the thing it writes into, while a preferences screen is often a destination in
+   * its own right — the built-in profile page has no parent at all.
+   */
+  parents?: readonly (BreadcrumbItem & { to: string })[];
+}
+
+/**
+ * The settings archetype: preferences and account screens — a stack of titled sections, each
+ * owning a few controls.
+ *
+ * `measure="narrow"` by default, header included, for the reason `FormPage` has it: this is a
+ * single column of controls, not a data surface. `ProfileView`'s own card carries exactly this
+ * measure today, and 4b already named that card as a page measure wearing a card's clothes — so
+ * this is the mechanism it was hand-rolling.
+ *
+ * **The body is `Card` sections and nothing that holds a collection.** No `DataView`, no
+ * `DetailList`, no `Tabs`: a settings screen whose body is a table is an overview, and one with
+ * tabs is a hub with the wrong chrome. `Card` is how a titled region is owned here — which is
+ * what 4b decided when it refused to ship `Section`, and this slot is the first archetype to
+ * depend on that decision rather than merely be compatible with it.
+ *
+ * Renders no element of its own, for the reason every non-hub archetype does not: a wrapper
+ * around the body becomes the sole entry in `article.children` and fails every governed page
+ * closed (ADR 0079).
+ */
+export function SettingsPage({
+  parents,
+  measure = "narrow",
+  ...page
+}: SettingsPageProps): ReactNode {
+  return (
+    <LayoutSlotContext.Provider value="SettingsPage">
+      {/* Spread first, then the archetype's own props — see `FormPage` for why. */}
+      <Page {...page} breadcrumbs={parents} measure={measure} />
+    </LayoutSlotContext.Provider>
+  );
+}