@terpjs/react-core 0.8.0 → 0.10.0

package/src/Page.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { ReactNode } from "react";
 import { useContext, useEffect, useRef, useState } from "react";
 
 import { Breadcrumbs } from "./Breadcrumbs";
@@ -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. */
@@ -40,39 +57,6 @@ export interface PageProps {
   children: ReactNode;
 }
 
-const pageStyle: CSSProperties = {
-  display: "grid",
-  gridTemplateColumns: "minmax(0, 1fr)",
-  gap: "var(--space-4)",
-  alignContent: "start",
-  minWidth: 0,
-};
-
-const headerStyle: CSSProperties = { display: "grid", gap: "var(--space-2)" };
-
-const breadcrumbRowStyle: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  minHeight: "2rem",
-};
-
-const titleRowStyle: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  gap: "var(--space-3)",
-  flexWrap: "wrap",
-};
-
-const titleStyle: CSSProperties = {
-  margin: 0,
-  fontSize: "var(--font-size-lg)",
-  fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
-  letterSpacing: 0,
-  color: "var(--color-neutral-900)",
-  lineHeight: 1.3,
-};
-
 /**
  * The base content-page frame: every routed view is constructed the same way — one
  * header holding the breadcrumb trail (when there is a path back up through the
@@ -85,12 +69,16 @@ const titleStyle: CSSProperties = {
  * The frame also owns the async body states: `error` (which wins, so a failed
  * query never hides behind a spinner) then `isLoading` replace the body while the
  * header stays put, so the user keeps their place in the layers.
+ *
+ * It renders no inline styles: the frame's geometry and the title's type come from the
+ * injected react-core sheet, matched on the `data-terp` markers stamped below (ADR 0094).
  */
 export function Page({
   title,
   breadcrumbs,
   renderLink,
   actions,
+  measure = "full",
   isLoading,
   loadingState,
   error,
@@ -137,16 +125,26 @@ 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} style={pageStyle}>
-      <header style={headerStyle}>
+    <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
+          additive; the tag is load-bearing. For the same reason the body below takes no
+          wrapper of its own — not even a display: contents one, since article.children is a
+          DOM traversal and would see it. */}
+      <header data-terp="page-header">
         {hasAncestors && (
-          <div style={breadcrumbRowStyle}>
+          <div data-terp="page-breadcrumbs">
             <Breadcrumbs items={trail} renderLink={renderLink} />
           </div>
         )}
-        <div style={titleRowStyle}>
-          <h1 style={titleStyle}>{resolve(title)}</h1>
+        <div data-terp="page-heading">
+          <h1 data-terp="page-title">{resolve(title)}</h1>
           {actions}
         </div>
       </header>

package/src/ProfileView.test.tsx

@@ -69,6 +69,21 @@ describe("ProfileView", () => {
     );
     expect(screen.getAllByText("jane.doe@example.com").length).toBeGreaterThanOrEqual(1);
     expect(screen.getByText("editor (20)")).toBeInTheDocument();
+
+    // The identity block, which nothing asserted before: the initials tile was entirely
+    // unreached by any test, and is aria-hidden so axe skips it too. Markers plus the
+    // absence of a style attribute, because the geometry is a sheet rule now (ADR 0094) and
+    // 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="avatar"]');
+    expect(avatar).not.toBeNull();
+    expect(avatar?.textContent).toBe("JD");
+    expect(avatar?.getAttribute("style")).toBeNull();
+    const email = document.querySelector('[data-terp="profile-email"]');
+    expect(email?.textContent).toBe("jane.doe@example.com");
+    expect(email?.getAttribute("style")).toBeNull();
+    expect(document.querySelectorAll('[data-terp="profile-card"]')).toHaveLength(2);
     // The stacked preference controls live here (settings surface).
     expect(screen.getByLabelText("Theme")).toBeInTheDocument();
     expect(screen.getByLabelText("Language")).toBeInTheDocument();

package/src/ProfileView.tsx

@@ -1,46 +1,21 @@
-import type { CSSProperties } from "react";
-
 import { Page } from "./Page";
 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";
 
-const avatarStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "3.5rem",
-  height: "3.5rem",
-  flexShrink: 0,
-  borderRadius: "var(--radius-full)",
-  background: "var(--color-brand-primary)",
-  color: "var(--color-brand-primary-contrast)",
-  fontSize: "var(--font-size-lg)",
-  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
-};
-
-const mutedStyle: CSSProperties = { margin: 0, color: "var(--color-neutral-600)" };
-
-const cardStyle: CSSProperties = {
-  display: "grid",
-  gap: "var(--space-4)",
-  padding: "var(--space-4)",
-  maxWidth: "32rem",
-  background: "var(--color-neutral-0)",
-  border: "1px solid var(--color-neutral-200)",
-  borderRadius: "var(--radius-lg)",
-};
-
 /**
  * The built-in profile / settings page the {@link UserMenu}'s Settings item opens.
  * `buildAppRouter` mounts it at `/profile` in every app (an app manifest claiming
  * that path wins): the signed-in identity (avatar, email, role — the server-validated
  * `/me` session, not token claims), the standard theme + language preferences, and
  * sign-out. A `Page` archetype, so it satisfies the routed-view frame control.
+ *
+ * It renders no inline styles: both cards, the avatar tile and the two identity lines take
+ * their geometry and ink from the injected react-core sheet (ADR 0094).
  */
 export function ProfileView() {
   const auth = useAuth();
@@ -52,14 +27,12 @@ export function ProfileView() {
   return (
     <Page title={strings.profile}>
       <Stack gap={4}>
-        <div style={cardStyle}>
+        <div data-terp="profile-card">
           <Stack direction="row" gap={3} align="center">
-            <span aria-hidden="true" style={avatarStyle}>
-              {userInitials(user.email)}
-            </span>
+            <Avatar from={user.email} />
             <Stack gap={0}>
-              <strong style={{ overflowWrap: "anywhere" }}>{user.email}</strong>
-              <p style={mutedStyle}>{user.role_name}</p>
+              <strong data-terp="profile-email">{user.email}</strong>
+              <p data-terp="profile-role">{user.role_name}</p>
             </Stack>
           </Stack>
           <DetailList
@@ -69,7 +42,7 @@ export function ProfileView() {
             ]}
           />
         </div>
-        <div style={cardStyle}>
+        <div data-terp="profile-card">
           <ThemeToggle />
           <LanguageSwitcher />
           <div>

package/src/ResourceList.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import type { CSSProperties, FormEvent, ReactNode } from "react";
+import type { FormEvent, ReactNode } from "react";
 
 import { Authorized } from "./Authorized";
 import { useErrorMessage } from "./errorMessages";
@@ -9,19 +9,6 @@ import { Button } from "./ui/Button";
 import { Input } from "./ui/Input";
 import type { Resource } from "./useResource";
 
-const rowStyle: CSSProperties = {
-  display: "flex",
-  alignItems: "center",
-  justifyContent: "space-between",
-  gap: "var(--space-3)",
-  padding: "var(--space-3)",
-  border: "1px solid var(--color-neutral-200)",
-  borderRadius: "var(--radius-md)",
-  background: "var(--color-neutral-0)",
-};
-
-const mutedStyle: CSSProperties = { color: "var(--color-neutral-600)" };
-
 export interface ResourceListProps<T extends { id: string }> {
   /** Section heading; omit when composed under a `Page` (whose title is the `h1`). */
   title?: UiText;
@@ -52,6 +39,10 @@ export interface ResourceListProps<T extends { id: string }> {
  *
  * It is a composable component, not a hidden CRUD DSL: a screen that needs more just renders its own
  * React and ignores this.
+ *
+ * It renders no inline styles: the section, the create row, both messages, the list and the
+ * rows take their geometry and ink from the injected react-core sheet, matched on the
+ * `data-terp` markers stamped below (ADR 0094).
  */
 export function ResourceList<T extends { id: string }>({
   title,
@@ -81,37 +72,35 @@ export function ResourceList<T extends { id: string }>({
   }
 
   return (
-    <section
-      data-terp="resource-list"
-      style={{ display: "grid", gap: "var(--space-4)", maxWidth: "40rem" }}
-    >
+    <section data-terp="resource-list">
       {title !== undefined && <h1>{resolve(title)}</h1>}
       {renderCreate !== undefined ? (
         <Authorized action="write">{renderCreate()}</Authorized>
       ) : createPlaceholder !== undefined ? (
         <Authorized action="write">
-          <form onSubmit={onCreate} style={{ display: "flex", gap: "var(--space-2)" }}>
+          <form onSubmit={onCreate} data-terp="resource-list-create">
             <Input
               placeholder={resolve(createPlaceholder ?? "")}
               value={draft}
               onChange={(event) => setDraft(event.target.value)}
-              style={{ flex: 1 }}
             />
             <Button type="submit">{strings.add}</Button>
           </form>
         </Authorized>
       ) : null}
       {resource.error !== null && (
-        <p role="alert" style={{ color: "var(--color-status-danger)" }}>
+        <p role="alert" data-terp="resource-list-error">
           {messageForCode(resource.cause) ?? resource.error}
         </p>
       )}
       {resource.items.length === 0 ? (
-        <p style={mutedStyle}>{resource.loading ? strings.loading : resolve(emptyMessage ?? strings.emptyList)}</p>
+        <p data-terp="resource-list-empty">
+          {resource.loading ? strings.loading : resolve(emptyMessage ?? strings.emptyList)}
+        </p>
       ) : (
-        <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "grid", gap: "var(--space-2)" }}>
+        <ul data-terp="resource-list-items">
           {resource.items.map((item) => (
-            <li key={item.id} style={rowStyle}>
+            <li key={item.id} data-terp="resource-list-row">
               <div>{renderItem(item)}</div>
               {renderActions && <Authorized action="write">{renderActions(item)}</Authorized>}
             </li>

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

package/src/SplitPage.tsx

@@ -0,0 +1,150 @@
+import type { ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import { useLayoutContract, verifySlotChildren } from "./layoutContract";
+import { Page } from "./Page";
+import type { PageProps } from "./Page";
+import { injectTerpStyles } from "./styles";
+import { useUiText } from "./uiText";
+import type { UiText } from "./uiText";
+
+injectTerpStyles();
+
+/** How much of the row the list pane takes — a step, not a length (ADR 0097 §4). */
+export type SplitListWidth = "sm" | "md" | "lg";
+
+export type SplitPageProps = Omit<PageProps, "children" | "measure"> & {
+  /** Parent trail for a split screen nested below a hub; aliases `Page`'s `breadcrumbs`. */
+  parents?: PageProps["breadcrumbs"];
+  /**
+   * The list pane's track (default `"md"`).
+   *
+   * Enumerable rather than a percentage or a length, which is the same call `Grid`'s
+   * `minColumn` made and for the same reason: a CSS length here would be a measured value and
+   * therefore an inline style on the panes element — a tenth entry in a ledger that admits only
+   * two permanent kinds (ADR 0094 §3). Three steps cover the cases; an app wanting 37% cannot
+   * have it, which is the trade `gap` already makes.
+   *
+   * A **draggable** divider is deliberately not offered: that is a measured value *and* a
+   * per-user preference, so it waits for the preference seam rather than arriving as an inline
+   * style with nowhere to persist.
+   */
+  listWidth?: SplitListWidth;
+  /**
+   * The two panes, **list first** — a `SplitPane role="list"` then a `SplitPane role="detail"`.
+   *
+   * Order is load-bearing: the tracks are filled by grid auto-placement, so the first pane takes
+   * the narrow one. The contract can see that both children are `SplitPane`s and cannot see
+   * which is which, so this is a convention the render makes obvious rather than a rule the
+   * runtime enforces.
+   */
+  children: ReactNode;
+};
+
+/**
+ * The split archetype: a list beside the record it selects — the master-detail screen.
+ *
+ * It is structured on `HubPage`, not on `DetailPage`, and that is the decision worth knowing.
+ * The obvious shape for two panes is one body slot holding two children, but the layout
+ * contract's runtime check takes a single slot owner and reads `article.children`, so two panes
+ * would be two entries in one slot with nothing distinguishing them. Teaching the contract two
+ * slots per archetype was the invasive option. Instead the panes are the governed thing:
+ * `SplitPage` owns the row element and admits `SplitPane` in it and nothing else, exactly as
+ * `HubPage` owns its grid and admits `HubCard`. `verifySlotChildren`, the mirrored table's
+ * shape and the message builder are all untouched.
+ *
+ * It therefore provides **no** `LayoutSlotContext`, for the reason `HubPage` provides none: the
+ * row element carries a marker that appears in no allow table, so a slot context above it would
+ * refuse every split page on its own body.
+ *
+ * Below the mobile breakpoint the panes stack, in DOM order, list first — so the tab sequence is
+ * the reading order in both layouts. That is the property `visual/keyboard.spec.ts` holds.
+ */
+export function SplitPage({
+  parents,
+  breadcrumbs,
+  listWidth = "md",
+  children,
+  ...page
+}: SplitPageProps) {
+  // The runtime half of the slot-typed layout contract control (ADR 0079) for the pane row:
+  // with a contract active, every rendered child of the row must be a SplitPane (its data-terp
+  // marker) — verified one macrotask after mount, refused fail closed. Same shape as HubPage's.
+  const contract = useLayoutContract();
+  const panesRef = useRef<HTMLDivElement>(null);
+  const [slotViolation, setSlotViolation] = useState<string | null>(null);
+  useEffect(() => {
+    if (contract === null) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      const panes = panesRef.current;
+      if (panes === null) {
+        return;
+      }
+      setSlotViolation(verifySlotChildren(contract, "SplitPage", [...panes.children]));
+    }, 0);
+    return () => clearTimeout(timer);
+  });
+  if (slotViolation !== null) {
+    throw new Error(slotViolation);
+  }
+  return (
+    <Page {...page} breadcrumbs={parents ?? breadcrumbs}>
+      <div ref={panesRef} data-terp="splitpage-panes" data-list-width={listWidth}>
+        {children}
+      </div>
+    </Page>
+  );
+}
+
+/** Which half of the split a pane is — the list, or the record it selects. */
+export type SplitPaneRole = "list" | "detail";
+
+export interface SplitPaneProps {
+  /**
+   * Which half this is.
+   *
+   * It does **not** place the pane. The row's tracks are `minmax(0, <listWidth>) minmax(0, 1fr)`
+   * and grid auto-placement fills them in DOM order, so the FIRST pane gets the narrow track
+   * whatever its role says — write the list first. A `detail`-first composition renders the
+   * record in the narrow column, which is wrong and immediately visible.
+   *
+   * Placing by role instead was considered and refused: it would render correctly whatever the
+   * DOM order, and correct-looking is exactly the wrong failure here. Tab order follows the DOM
+   * and CSS cannot change it, so a `detail`-first tree would then read left-to-right and tab
+   * right-to-left — the WCAG 1.3.2 / 2.4.3 mismatch, silent. Leaving placement to the DOM makes
+   * a mis-ordered split look mis-ordered.
+   *
+   * What the role does carry: the pane's identity for anything that needs to tell the two apart
+   * (`visual/keyboard.spec.ts` asserts the tab order through it), and a hook for a rule should
+   * one ever need to distinguish them.
+   */
+  role: SplitPaneRole;
+  /**
+   * The pane's accessible name.
+   *
+   * Required, because each pane is a `<section>` and therefore a landmark: two unnamed regions
+   * side by side are two indistinguishable entries in a screen reader's landmark list, which is
+   * worse than one region containing both.
+   */
+  label: UiText;
+  children: ReactNode;
+}
+
+/**
+ * One half of a {@link SplitPage} — the list, or the detail beside it.
+ *
+ * A named `<section>`, so the two halves are distinguishable landmarks, and the only component
+ * the split's row admits. It renders no inline style, and no style at all beyond a
+ * `min-width: 0` floor: which track it takes comes from its POSITION, not from `role` — see the
+ * prop for why that is the safer of the two.
+ */
+export function SplitPane({ role, label, children }: SplitPaneProps) {
+  const resolve = useUiText();
+  return (
+    <section data-terp="splitpane" data-role={role} aria-label={resolve(label)}>
+      {children}
+    </section>
+  );
+}

package/src/UserMenu.test.tsx

@@ -66,7 +66,7 @@ describe("UserMenu", () => {
         <UserMenu />
       </TerpProvider>,
     );
-    expect(screen.queryByRole("button", { name: "Account menu" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /jane\.doe@example\.com/ })).not.toBeInTheDocument();
   });
 
   it("shows the avatar initials, email and role, and opens the panel", async () => {
@@ -81,7 +81,7 @@ describe("UserMenu", () => {
         </LocaleProvider>
       </ThemeProvider>,
     );
-    const trigger = await screen.findByRole("button", { name: "Account menu" });
+    const trigger = await screen.findByRole("button", { name: /jane\.doe@example\.com/ });
     expect(screen.getByText("JD")).toBeInTheDocument();
     expect(screen.getByText("jane.doe@example.com")).toBeInTheDocument();
     expect(screen.getByText("editor")).toBeInTheDocument();
@@ -104,7 +104,7 @@ describe("UserMenu", () => {
         <UserMenu onSettings={onSettings} />
       </TerpProvider>,
     );
-    fireEvent.click(await screen.findByRole("button", { name: "Account menu" }));
+    fireEvent.click(await screen.findByRole("button", { name: /jane\.doe@example\.com/ }));
     fireEvent.click(screen.getByRole("menuitem", { name: "Settings" }));
     expect(onSettings).toHaveBeenCalledTimes(1);
     expect(screen.queryByRole("menuitem", { name: "Sign out" })).not.toBeInTheDocument();
@@ -118,6 +118,10 @@ describe("UserMenu", () => {
         <UserMenu collapsed />
       </TerpProvider>,
     );
+    // Collapsed is the one variant that still carries `triggerLabel`, because its only
+    // content is the aria-hidden avatar — without the label the button would have no
+    // accessible name at all. Expanded takes its name from the email and role it renders,
+    // which is what the other cases in this file now assert.
     const trigger = await screen.findByRole("button", { name: "Account menu" });
     expect(screen.getByText("JD")).toBeInTheDocument();
     expect(screen.queryByText("jane.doe@example.com")).not.toBeInTheDocument();
@@ -137,6 +141,25 @@ describe("UserMenu", () => {
     expect(screen.getByRole("menu").parentElement).toHaveAttribute("data-owner", "user-menu");
   });
 
+  it("keeps the trigger inside its own root when expanded, which is how the sign-out helper finds it", async () => {
+    // `@terpjs/conformance`'s `logout()` signs a user out of any Terp app through this button, and
+    // located it by the accessible name "Account menu" until that name stopped existing here —
+    // expanded, the button is named after the user's email and role on purpose (WCAG 2.5.3). The
+    // helper reaches it by marker path now, so the DESCENDANT relationship is a cross-package
+    // contract; the collapsed case above already pins the marker itself, and this pins the shape
+    // of the path in the state the sidebar is actually in by default.
+    stubAuthFetch();
+    const { container } = render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <UserMenu />
+      </TerpProvider>,
+    );
+    await screen.findByText("jane.doe@example.com");
+    const trigger = container.querySelector('[data-terp="user-menu"] [data-terp="menu-trigger"]');
+    expect(trigger?.tagName).toBe("BUTTON");
+  });
+
   it("signs out via the menu (revokes the token server-side)", async () => {
     const fetchMock = stubAuthFetch();
     render(
@@ -145,7 +168,7 @@ describe("UserMenu", () => {
         <UserMenu />
       </TerpProvider>,
     );
-    fireEvent.click(await screen.findByRole("button", { name: "Account menu" }));
+    fireEvent.click(await screen.findByRole("button", { name: /jane\.doe@example\.com/ }));
     fireEvent.click(screen.getByRole("menuitem", { name: "Sign out" }));
     await waitFor(() =>
       expect(
@@ -164,7 +187,7 @@ describe("UserMenu", () => {
         <UserMenu />
       </TerpProvider>,
     );
-    const trigger = await screen.findByRole("button", { name: "Account menu" });
+    const trigger = await screen.findByRole("button", { name: /jane\.doe@example\.com/ });
     fireEvent.click(trigger);
     expect(screen.getByRole("menuitem", { name: "Sign out" })).toBeInTheDocument();
     fireEvent.keyDown(document, { key: "Escape" });

package/src/UserMenu.tsx

@@ -1,18 +1,18 @@
 import { Icon } from "./icons";
 import { injectTerpStyles } from "./styles";
 import { useAuth } from "./TerpProvider";
+import { Avatar } from "./ui/Avatar";
 import { Menu, MenuItem } from "./ui/Menu";
 import { useStrings } from "./uiText";
 
 injectTerpStyles();
 
-/** Initials for the avatar: the first letters of the email's local-part words. */
-export function userInitials(email: string): string {
-  const local = email.split("@")[0] ?? "";
-  const words = local.split(/[._+-]+/).filter((word) => word.length > 0);
-  const initials = words.slice(0, 2).map((word) => word[0]!.toUpperCase());
-  return initials.join("") || "?";
-}
+/**
+ * Re-exported from where the tile now lives. It was public under this name before `Avatar`
+ * existed, and moving a published export to another module is a breaking change for no
+ * reason — the tile is what needed one home, not the name.
+ */
+export { userInitials } from "./ui/Avatar";
 
 export interface UserMenuProps {
   /** Icon-rail mode: show only the avatar on the trigger (the shell's collapsed state). */
@@ -39,7 +39,7 @@ export function UserMenu({ collapsed = false, onSettings, defaultOpen }: UserMen
 
   const trigger = (
     <>
-      <span aria-hidden="true" data-terp="user-menu-avatar">{userInitials(user.email)}</span>
+      <Avatar from={user.email} size="sm" />
       {!collapsed && (
         <span data-terp="user-menu-identity">
           <span data-terp="user-menu-email">{user.email}</span>
@@ -52,7 +52,13 @@ export function UserMenu({ collapsed = false, onSettings, defaultOpen }: UserMen
   return (
     <Menu
       trigger={trigger}
-      triggerLabel={strings.accountMenu}
+      // Only in the icon rail, and the asymmetry is the point. `aria-label` REPLACES the
+      // subtree text in the accessible name, so in the expanded trigger — which renders the
+      // user's email and role as visible text — naming it "Account menu" hid both from anyone
+      // relying on the name, and left a voice-control user with no spoken label that matches
+      // what they can see (WCAG 2.5.3, Label in Name). Collapsed there is nothing to hide: the
+      // avatar initials are aria-hidden, so without this the button would have no name at all.
+      triggerLabel={collapsed ? strings.accountMenu : undefined}
       placement="top"
       align="start"
       defaultOpen={defaultOpen}