@terpjs/react-core 0.9.0 → 0.10.0

package/src/typography.test.tsx

@@ -0,0 +1,213 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { NavLinkContext } from "./navLink";
+import { Code, Heading, Link, Text } from "./typography";
+
+afterEach(cleanup);
+
+describe("Heading", () => {
+  it("takes its element from the level and its size from a separate default", () => {
+    render(
+      <>
+        <Heading level={2}>two</Heading>
+        <Heading level={3}>three</Heading>
+        <Heading level={4}>four</Heading>
+      </>,
+    );
+    for (const [level, size] of [
+      [2, "lg"],
+      [3, "base"],
+      [4, "sm"],
+    ] as const) {
+      const el = screen.getByRole("heading", { level });
+      expect(el.tagName).toBe(`H${level}`);
+      expect(el).toHaveAttribute("data-size", size);
+      expect(el.getAttribute("style")).toBeNull();
+    }
+  });
+
+  it("lets a level carry any size, which is the point of separating them", () => {
+    // A visually small h2 is a legitimate thing to want, and forcing level and size together
+    // is what makes an author pick the wrong element to get the right size — breaking the
+    // outline a screen-reader user navigates by, as a styling decision.
+    render(
+      <Heading level={2} size="sm">
+        small but second
+      </Heading>,
+    );
+    const el = screen.getByRole("heading", { level: 2 });
+    expect(el.tagName).toBe("H2");
+    expect(el).toHaveAttribute("data-size", "sm");
+  });
+});
+
+describe("Text", () => {
+  it("leaves the default tone and step unstamped", () => {
+    render(<Text data-testid="copy">body</Text>);
+    const el = screen.getByTestId("copy");
+    expect(el.tagName).toBe("P");
+    expect(el).toHaveAttribute("data-terp", "text");
+    expect(el.hasAttribute("data-tone")).toBe(false);
+    expect(el.hasAttribute("data-size")).toBe(false);
+    expect(el.hasAttribute("data-measure")).toBe(false);
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("names a tone, a step, a measure and its element", () => {
+    render(
+      <Text data-testid="copy" as="span" tone="muted" size="sm" measure="narrow">
+        body
+      </Text>,
+    );
+    const el = screen.getByTestId("copy");
+    expect(el.tagName).toBe("SPAN");
+    expect(el).toHaveAttribute("data-tone", "muted");
+    expect(el).toHaveAttribute("data-size", "sm");
+    expect(el).toHaveAttribute("data-measure", "narrow");
+  });
+});
+
+describe("Code", () => {
+  it("is a bare code element when inline", () => {
+    render(<Code data-testid="snippet">terp dev</Code>);
+    const el = screen.getByTestId("snippet");
+    expect(el.tagName).toBe("CODE");
+    expect(el.hasAttribute("tabindex")).toBe(false);
+  });
+
+  it("wraps a block in a focusable pre, which is what preserves the whitespace", () => {
+    // The `<pre>` is not decoration: a `<code>` alone collapses whitespace, so a multi-line
+    // snippet in one runs together. And it scrolls, which is why it is focusable — a scroll
+    // container a keyboard cannot reach cannot be scrolled at all (SC 2.1.1).
+    render(<Code block>{"a\n  b"}</Code>);
+    const pre = document.querySelector('[data-terp="code-block"]')!;
+    expect(pre.tagName).toBe("PRE");
+    expect(pre).toHaveAttribute("tabindex", "0");
+    const code = pre.querySelector('[data-terp="code"]')!;
+    expect(code.tagName).toBe("CODE");
+    expect(code.textContent).toBe("a\n  b");
+  });
+});
+
+describe("Link", () => {
+  const renderer = ({
+    to,
+    children,
+    attributes,
+  }: {
+    to: string;
+    children: React.ReactNode;
+    attributes?: Record<string, unknown>;
+  }) => (
+    <a href={`#routed${to}`} data-testid="routed" {...attributes}>
+      {children}
+    </a>
+  );
+
+  it("routes an in-app path through the ambient renderer, marking a wrapper", () => {
+    // The marker lands on a wrapper the component owns, and that is deliberate rather than
+    // forced: it could travel to the anchor through the renderer's `attributes`, and must not,
+    // because an app supplying its own renderer that ignores them is source-compatible and the
+    // failure would be an unstyled link with no error. A styling hook cannot depend on a caller
+    // honouring a seam. HubCard's pattern, for a related reason.
+    render(
+      <NavLinkContext.Provider value={renderer}>
+        <Link to="/records">records</Link>
+      </NavLinkContext.Provider>,
+    );
+    const anchor = screen.getByTestId("routed");
+    expect(anchor.getAttribute("href")).toBe("#routed/records");
+    const wrapper = anchor.parentElement!;
+    expect(wrapper.tagName).toBe("SPAN");
+    expect(wrapper).toHaveAttribute("data-terp", "link");
+  });
+
+  it("puts the caller's own attributes on the ANCHOR, in both branches", () => {
+    // The defect this pins: `rest` used to land on the wrapper for an in-app path and on the
+    // anchor for an external one, so the same prop worked or silently did nothing depending on
+    // whether the destination started with a slash. An `aria-label` on a `<span>` around a link
+    // is ignored — the link keeps its content as its name and the caller's intent disappears
+    // with no error, which is the worst available failure.
+    const { rerender } = render(
+      <NavLinkContext.Provider value={renderer}>
+        <Link to="/records" aria-label="All records" id="records-link">
+          records
+        </Link>
+      </NavLinkContext.Provider>,
+    );
+    const routed = screen.getByRole("link", { name: "All records" });
+    expect(routed.tagName).toBe("A");
+    expect(routed.getAttribute("id")).toBe("records-link");
+
+    rerender(
+      <Link to="https://example.com" aria-label="The docs">
+        docs
+      </Link>,
+    );
+    expect(screen.getByRole("link", { name: "The docs" }).tagName).toBe("A");
+  });
+
+  it("falls back to a plain anchor with no router above it", () => {
+    // The story/test/bespoke-shell case, and the same degradation every layout component that
+    // renders a link already does. Without it a Link outside a Terp router renders nothing
+    // navigable at all.
+    render(<Link to="/records">records</Link>);
+    const el = screen.getByRole("link", { name: "records" });
+    expect(el.tagName).toBe("A");
+    expect(el).toHaveAttribute("href", "/records");
+    expect(el).toHaveAttribute("data-terp", "link");
+  });
+
+  it("refuses a bare relative destination rather than reloading the page", () => {
+    // The silent case this replaces: `to="records"` fell through to the external branch and
+    // rendered a relative anchor — a full reload to a URL resolved against wherever the user
+    // was, with the router's guard skipped. Every route a manifest declares is absolute, so
+    // there is no reading of a bare path that is what the caller wanted.
+    expect(() => render(<Link to="records">records</Link>)).toThrow(/leading slash/);
+  });
+
+  it("accepts a same-page fragment and a scheme, which are an anchor's own business", () => {
+    render(
+      <>
+        <Link to="#section">jump</Link>
+        <Link to="mailto:ops@example.com">mail</Link>
+      </>,
+    );
+    expect(screen.getByRole("link", { name: "jump" })).toHaveAttribute("href", "#section");
+    expect(screen.getByRole("link", { name: "mail" })).toHaveAttribute(
+      "href",
+      "mailto:ops@example.com",
+    );
+  });
+
+  it("gives an external new tab rel=noreferrer, and adds neither otherwise", () => {
+    // Without `rel`, the opened page can reach back through `window.opener` — the
+    // reverse-tabnabbing shape the boundary lint's own no-unsafe-target-blank rule exists for.
+    const { rerender } = render(
+      <Link to="https://example.com" newTab>
+        out
+      </Link>,
+    );
+    const newTab = screen.getByRole("link", { name: "out" });
+    expect(newTab).toHaveAttribute("target", "_blank");
+    expect(newTab).toHaveAttribute("rel", "noreferrer");
+    rerender(<Link to="https://example.com">out</Link>);
+    const sameTab = screen.getByRole("link", { name: "out" });
+    expect(sameTab.hasAttribute("target")).toBe(false);
+    expect(sameTab.hasAttribute("rel")).toBe(false);
+  });
+
+  it("ignores newTab for an in-app path, which has no external tab to open", () => {
+    render(
+      <NavLinkContext.Provider value={renderer}>
+        <Link to="/records" newTab>
+          records
+        </Link>
+      </NavLinkContext.Provider>,
+    );
+    const anchor = screen.getByTestId("routed");
+    expect(anchor.hasAttribute("target")).toBe(false);
+  });
+});

package/src/typography.tsx

@@ -0,0 +1,255 @@
+import type { AnchorHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+
+import { useNavLink } from "./navLink";
+import { injectTerpStyles } from "./styles";
+
+injectTerpStyles();
+
+/**
+ * The prose primitives, and the gap they close is narrower than "we had no typography".
+ *
+ * A module could always render a `<p>` or a `<code>`. What it could not do is give either any
+ * treatment: app modules may not write `style` or `className` (ADR 0059), and a bare element
+ * carries no `data-terp`, so no rule in the sheet can reach it. The framework's own generated
+ * home page shipped a bare `<p>` and a bare `<code>` for exactly that reason. So these are the
+ * marker, and the marker is what makes the ink themeable.
+ *
+ * ## They are the first readers of the published type scale
+ *
+ * `--font-line-height-*` and `--font-letter-spacing-*` shipped in 0.7.0 and nothing read them —
+ * the same shape as the motion tokens, and resolved differently, because the facts differ.
+ * Every motion literal mapped exactly onto a token, so wiring them was inert. Here only 8 of
+ * the sheet's 32 literals map: it writes `line-height` values of 1.2, 1.25, 1.3, 1.4 and 1.5,
+ * and the published scale offers 1.2, 1.35, 1.5 and 1.7. Converting the eight that match and
+ * leaving thirteen that do not would be a half-migration, and converting the rest means
+ * *changing rendered line heights* across a dozen components — a deliberate typography pass
+ * with its own baselines, not a token wiring done in passing.
+ *
+ * New components have no such problem: nothing depends on their metrics yet, so they adopt the
+ * published scale and give it its first consumers. `tokens.guard.test.ts` tracks the remainder
+ * as an exact list, so the reconciliation stays a decision somebody has to make rather than a
+ * thing that quietly never happens.
+ */
+
+/** Semantic heading level. `1` is absent on purpose — see {@link Heading}. */
+export type HeadingLevel = 2 | 3 | 4;
+
+/** Type step for a heading, independent of its level. */
+export type HeadingSize = "sm" | "base" | "lg" | "xl";
+
+export interface HeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, "style"> {
+  /**
+   * The semantic level, which decides the element.
+   *
+   * There is no `1`, and the reason is structural rather than stylistic: `Page` renders the
+   * single `<h1>` of every routed view, and every routed view is a `Page` (the page-archetype
+   * control refuses one that is not). A second `<h1>` in a body would give the document two
+   * top-level headings and break the outline a screen-reader user navigates by — so the
+   * component cannot express it.
+   */
+  level: HeadingLevel;
+  /**
+   * The type step, defaulting per level (`2` → `lg`, `3` → `base`, `4` → `sm`).
+   *
+   * Decoupled from `level` deliberately: the level is an outline fact and the size is a design
+   * one, and forcing them together is what makes authors reach for the wrong element to get the
+   * right size. A visually small `<h2>` is a legitimate thing to want.
+   */
+  size?: HeadingSize;
+  children?: ReactNode;
+}
+
+const DEFAULT_HEADING_SIZE: Record<HeadingLevel, HeadingSize> = { 2: "lg", 3: "base", 4: "sm" };
+
+/**
+ * A section heading inside a page body — `h2`–`h4`, with its size a separate choice.
+ *
+ * `data-size` is stamped for every heading, which breaks the idiom the rest of the package
+ * follows — density, Button's `md`, Grid's `auto`, Card's `boxed` and Text's own default all
+ * leave the default unstamped because the base rule *is* the default. A heading has no single
+ * default to fold into a base rule: the default depends on the level, so the base rule carries
+ * the weight and metrics and every size carries its own step. Stamping all three is what keeps
+ * the sheet from needing a rule per level as well as per size.
+ */
+export function Heading({ level, size, children, ...rest }: HeadingProps) {
+  const Component = `h${level}` as "h2" | "h3" | "h4";
+  const step = size ?? DEFAULT_HEADING_SIZE[level];
+  return (
+    <Component {...rest} data-terp="heading" data-size={step}>
+      {children}
+    </Component>
+  );
+}
+
+/** Ink weight for body copy. */
+export type TextTone = "default" | "muted" | "subtle";
+
+/** Type step for body copy. */
+export type TextSize = "xs" | "sm" | "base" | "lg";
+
+export interface TextProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** The rendered element — `"p"` by default; `"span"` for text inside a line. */
+  as?: "p" | "span" | "div";
+  /** Ink weight (default `"default"`; `"muted"` for secondary copy, `"subtle"` for hints). */
+  tone?: TextTone;
+  /** Type step (default `"base"`). */
+  size?: TextSize;
+  /**
+   * Cap the line length for readability (default off).
+   *
+   * A measure is the one typographic control that is about the container rather than the text,
+   * and it is enumerable here — `"narrow"` / `"base"` — rather than a length, so there are no
+   * arbitrary column widths for the same reason `gap` is a token index.
+   *
+   * It caps a **block**, so it does nothing on `as="span"` — `max-width` has no effect on an
+   * inline box. That combination is a no-op rather than an error, which is worth knowing because
+   * the failure is silent; the visible cue is prose that simply never wraps where it was asked
+   * to.
+   */
+  measure?: "narrow" | "base";
+  children?: ReactNode;
+}
+
+/** Body copy with themeable ink — the thing a bare `<p>` in a module cannot be. */
+export function Text({
+  as: Component = "p",
+  tone = "default",
+  size = "base",
+  measure,
+  children,
+  ...rest
+}: TextProps) {
+  return (
+    <Component
+      {...rest}
+      data-terp="text"
+      // `default` and `base` are the base rule, so their attributes would describe the default
+      // twice — the idiom density, Button's `md`, Grid's `auto` and Card's `boxed` all use.
+      data-tone={tone === "default" ? undefined : tone}
+      data-size={size === "base" ? undefined : size}
+      data-measure={measure}
+    >
+      {children}
+    </Component>
+  );
+}
+
+export interface CodeProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /**
+   * Render as a block rather than inline.
+   *
+   * A block wraps the `<code>` in a `<pre>`, which is what preserves the whitespace — a
+   * `<code>` alone collapses it, so a multi-line snippet in one runs together. `tabIndex={0}`
+   * goes on the `<pre>` because it scrolls: a scrollable region that cannot be focused cannot
+   * be scrolled by keyboard, which is SC 2.1.1.
+   */
+  block?: boolean;
+  children?: ReactNode;
+}
+
+/** An identifier or a snippet, in the mono family, with whitespace preserved when `block`. */
+export function Code({ block = false, children, ...rest }: CodeProps) {
+  if (!block) {
+    return (
+      <code {...rest} data-terp="code">
+        {children}
+      </code>
+    );
+  }
+  return (
+    // tabIndex after the spread, not before: a caller removing it would leave a scroll
+    // container no keyboard can reach, which is the SC 2.1.1 failure it exists to prevent.
+    <pre {...rest} data-terp="code-block" tabIndex={0}>
+      <code data-terp="code">{children}</code>
+    </pre>
+  );
+}
+
+export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "style" | "href"> {
+  /** Destination. A path (`/records`) routes in-app; anything else is an external anchor. */
+  to: string;
+  /** Open an external destination in a new tab (ignored for in-app paths). */
+  newTab?: boolean;
+  children?: ReactNode;
+}
+
+/** Whether `to` is an in-app path rather than an external destination. */
+function isInApp(to: string): boolean {
+  return to.startsWith("/");
+}
+
+/** A scheme (`https:`, `mailto:`, `tel:`) or a same-page fragment — an anchor's own business. */
+function isExternal(to: string): boolean {
+  return to.startsWith("#") || /^[a-z][a-z0-9+.\-]*:/i.test(to);
+}
+
+/**
+ * Refuse a destination that is neither, fail closed and directive.
+ *
+ * `to="records"` — no leading slash, no scheme — used to fall through to the external branch
+ * and render a relative anchor: a full page reload to a URL resolved against wherever the user
+ * happened to be, with the role-aware guard skipped. A caller writing that means the route, and
+ * every route in a manifest is absolute, so the silent reload is never what was wanted. Loud is
+ * strictly better, and it matches how `useRouteParam` and `useTerpNavigate` treat a path they
+ * cannot honour.
+ */
+function assertRoutable(to: string): void {
+  if (!isInApp(to) && !isExternal(to)) {
+    throw new Error(
+      `Link "to" must be an in-app path ("/records"), an absolute URL ` +
+        `("https://example.com"), or a fragment ("#section") — got "${to}". A bare relative ` +
+        "path renders an anchor that reloads the page and skips the router's guard; every " +
+        "route a manifest declares is absolute, so add the leading slash.",
+    );
+  }
+}
+
+/**
+ * A link with themeable ink, routing in-app paths through the surrounding router.
+ *
+ * Two things it exists for. A bare `<a>` carries no marker, so no rule in the sheet can reach
+ * it — which is why the shell's nav links and the breadcrumb trail each needed a selector of
+ * their own, and why a link in a module's prose had no treatment at all. And an in-app
+ * `<a href="/…">` bypasses the router: a full reload, and the role-aware guard never runs. The
+ * boundary lint refuses that anchor in module code; this is the thing to use instead.
+ *
+ * Outside a Terp router it degrades to a plain anchor, like every other layout component that
+ * renders a link, so it still works in a story or a test tree.
+ *
+ * An external destination opened in a new tab gets `rel="noreferrer"` — without it the opened
+ * page can reach back through `window.opener`, which is the reverse-tabnabbing shape the
+ * boundary lint's own `no-unsafe-target-blank` rule exists for.
+ */
+export function Link({ to, newTab = false, children, ...rest }: LinkProps) {
+  const navLink = useNavLink();
+  assertRoutable(to);
+  if (isInApp(to) && navLink !== null) {
+    // Two destinations for two kinds of attribute, and the split is deliberate.
+    //
+    // The caller's own attributes go to the ANCHOR through the renderer's `attributes`, because
+    // that is the only place they mean anything: an `aria-label` on a wrapper is ignored, so it
+    // would be silently dropped for an in-app path and honoured for an external one — the same
+    // prop behaving differently depending on whether the destination starts with a slash.
+    //
+    // The MARKER stays on the wrapper, which is `HubCard`'s pattern. It could travel through
+    // `attributes` too, and must not: an app supplying its own renderer that destructures only
+    // `{ to, children }` is source-compatible and forwards nothing, and the failure would be an
+    // unstyled link with no error. A component's own styling hook cannot depend on a caller
+    // honouring a seam. The `<span>` is inline, so it adds no box to a line of prose.
+    return (
+      <span data-terp="link">{navLink({ to, children, attributes: rest })}</span>
+    );
+  }
+  const external = !isInApp(to) && newTab;
+  return (
+    <a
+      {...rest}
+      data-terp="link"
+      href={to}
+      target={external ? "_blank" : undefined}
+      rel={external ? "noreferrer" : undefined}
+    >
+      {children}
+    </a>
+  );
+}

package/src/ui/Avatar.test.tsx

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Avatar, userInitials } from "./Avatar";
+
+afterEach(cleanup);
+
+describe("Avatar", () => {
+  it("derives initials from an email's local part", () => {
+    expect(userInitials("jane.doe@example.com")).toBe("JD");
+    expect(userInitials("admin@example.test")).toBe("A");
+    expect(userInitials("@example.test")).toBe("?");
+  });
+
+  it("splits a NAME on whitespace, which is the other half of what `from` documents", () => {
+    // The prop and the README both say "an email or a name". The split had no whitespace class, so
+    // a name produced one letter — a documented input with an undocumented answer.
+    expect(userInitials("Jane Doe")).toBe("JD");
+    expect(userInitials("ada lovelace king")).toBe("AL");
+    // And an email still behaves exactly as before.
+    expect(userInitials("jane.doe@example.com")).toBe("JD");
+  });
+
+  it("treats an empty string as absent on both props", () => {
+    // `??` only catches null and undefined, so an empty override painted a blank tile — which
+    // reads as a loading state rather than as "no initials".
+    const { container, rerender } = render(<Avatar from="jane.doe@example.com" initials="" />);
+    const tile = () => container.querySelector('[data-terp="avatar"]');
+    expect(tile()).toHaveTextContent("JD");
+    rerender(<Avatar from="" />);
+    expect(tile()).toHaveTextContent("?");
+    rerender(<Avatar />);
+    expect(tile()).toHaveTextContent("?");
+  });
+
+  it("takes explicit initials over anything it would have derived", () => {
+    render(<Avatar from="jane.doe@example.com" initials="ZZ" />);
+    expect(screen.getByText("ZZ")).toBeInTheDocument();
+    expect(screen.queryByText("JD")).toBeNull();
+  });
+
+  it("stamps a size attribute for sm and none for the default", () => {
+    // The same bargain as every other sized component: md IS the base rule, so an attribute for it
+    // would leave two places describing the standard tile. The sheet gate asserts the converse —
+    // that no `[data-size="md"]` rule exists — and this asserts the component never emits one.
+    const { container, rerender } = render(<Avatar from="a.b@example.com" />);
+    const tile = () => container.querySelector('[data-terp="avatar"]');
+    expect(tile()).not.toBeNull();
+    expect(tile()).not.toHaveAttribute("data-size");
+    rerender(<Avatar from="a.b@example.com" size="md" />);
+    expect(tile()).not.toHaveAttribute("data-size");
+    rerender(<Avatar from="a.b@example.com" size="sm" />);
+    expect(tile()).toHaveAttribute("data-size", "sm");
+  });
+
+  it("is hidden from assistive tech, because the name it abbreviates is rendered beside it", () => {
+    // Announcing "JD" before "jane.doe@example.com" is a puzzle rather than information, and both
+    // callers render the full identity next to the tile.
+    render(<Avatar from="jane.doe@example.com" />);
+    expect(screen.getByText("JD")).toHaveAttribute("aria-hidden", "true");
+  });
+});

package/src/ui/Avatar.tsx

@@ -0,0 +1,65 @@
+import { injectTerpStyles } from "../styles";
+
+injectTerpStyles();
+
+/**
+ * Two letters from an email's local part — `jane.doe@…` becomes `JD`, `admin@…` becomes `A`.
+ *
+ * Lives here rather than beside the account menu because it is what an avatar is made of, and both
+ * places that render one needed it. Still exported under its own name; it was public before this
+ * component existed.
+ */
+export function userInitials(email: string): string {
+  const local = email.split("@")[0] ?? "";
+  // Whitespace is in the split for the same reason the dots are: the prop this feeds documents
+  // itself as taking "an email or a name", and a name separates its words with a space. Without
+  // it "Jane Doe" yielded "J" — a documented input producing an undocumented answer.
+  const words = local.split(/[\s._+-]+/).filter((word) => word.length > 0);
+  const initials = words.slice(0, 2).map((word) => word[0]!.toUpperCase());
+  return initials.join("") || "?";
+}
+
+export interface AvatarProps {
+  /** The text initials are derived from when `initials` is omitted — an email or a name. */
+  from?: string;
+  /** Explicit initials, for a caller with better material than `from`. */
+  initials?: string;
+  /** `md` = 3.5rem, the profile header. `sm` = 2rem, the account menu. Default `md`. */
+  size?: "sm" | "md";
+}
+
+/**
+ * The initials tile.
+ *
+ * A merge rather than an addition: the framework already shipped this component twice, as eleven
+ * identical declarations under `profile-avatar` and eleven more under `user-menu-avatar`, differing
+ * only in a width, a height and a font size. Two markers became one and the inventory went DOWN.
+ * That is the opposite of the `Section` / `Surface` decision, and for the opposite reason — those
+ * had no consumer, this had two of them wearing different names for the same thing.
+ *
+ * **No `src`.** `/me` returns `email`, `role_name` and `role_rank` and carries no avatar URL, so an
+ * image slot would be a prop with nothing behind it. Additive the day the payload grows one.
+ *
+ * The tile is `aria-hidden`: initials are a decoration for a name that is always rendered beside
+ * them, and announcing "JD" before "jane.doe@example.com" adds a puzzle rather than information.
+ * A caller that has no adjacent name has an unlabelled avatar, which is why this takes no label —
+ * the fix there is to render the name, not to spell out the letters.
+ */
+export function Avatar({ from, initials, size = "md" }: AvatarProps) {
+  // An empty string counts as absent on both props, not as an override that renders nothing:
+  // `??` alone would let `initials=""` paint a blank tile, and a blank tile reads as loading.
+  const explicit = initials !== undefined && initials !== "" ? initials : undefined;
+  const derived = from !== undefined && from !== "" ? userInitials(from) : "?";
+
+  return (
+    <span
+      aria-hidden="true"
+      data-terp="avatar"
+      // No attribute for the default, matching every other sized component here: `md` IS the base
+      // rule, and stamping it would leave two places describing the standard tile.
+      data-size={size === "md" ? undefined : size}
+    >
+      {explicit ?? derived}
+    </span>
+  );
+}