@charcuterie/ui 3.12.0 → 3.13.0

package/src/Avatar/Avatar.stories.tsx

@@ -0,0 +1,254 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { categoricalArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { Avatar } from "./Avatar.tsx"
+
+/**
+ * **Invented, every one of them.** The component was built for a
+ * household task board, so its real fixture is a list of the people
+ * who live there — which must never reach a published repo and
+ * doubly never a committed screenshot, because a PNG is opaque to
+ * every grep and no text scrub can redact it.
+ *
+ * So this is a fictional studio's roster: two-word names, a mononym,
+ * a name whose first character is outside the BMP, and a
+ * non-human account.
+ */
+const ROSTER = [
+  { id: "user-1", name: "Ada Lovelace" },
+  { id: "user-2", name: "Wren Okonkwo" },
+  { id: "user-3", name: "Bo" },
+  { id: "user-4", name: "Ines Marchetti" },
+  { id: "user-5", name: "Tomas Ericsson" },
+] as const
+
+/**
+ * A photo that needs no network and no fixture file. The initials
+ * behind it are what the reader sees the moment it is absent, which
+ * is the state that actually matters.
+ */
+const PORTRAIT_URL = `data:image/svg+xml;utf8,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="#2F6F4E"/><circle cx="32" cy="24" r="12" fill="#F2E8CF"/><rect x="12" y="40" width="40" height="28" rx="14" fill="#F2E8CF"/></svg>',
+)}`
+
+/** 404s, which is what makes the fallback real rather than mocked. */
+const MISSING_PORTRAIT_URL =
+  "/charcuterie-missing-portrait.png"
+
+/**
+ * A stand-in for an app's own glyph set. The library ships none, so
+ * a story that wants one has to bring it — and a letter is the safe
+ * choice in a sandbox whose font may lack the symbol.
+ */
+const AgentGlyph = () => <span>{"AI"}</span>
+
+const meta = {
+  title: "Components/Data/Avatar",
+  component: Avatar,
+  parameters: { layout: "padded" },
+  argTypes: { categorical: categoricalArgType },
+  args: {
+    appearance: "soft",
+    categorical: undefined,
+    categoricalKey: undefined,
+    icon: undefined,
+    imageUrl: undefined,
+    initials: undefined,
+    name: "Ada Lovelace",
+    size: "md",
+  },
+} satisfies Meta<typeof Avatar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Two letters on a colour nobody chose. The name is on the chip for
+ * a screen reader and on hover for a pointer, and it is not printed
+ * anywhere — `getByRole("img", { name: "Ada Lovelace" })` resolves.
+ */
+export const Default: Story = {}
+
+/**
+ * The three appearances, and the ten colours the scale holds.
+ *
+ * `soft` is the default because a lane of solid chips competes with
+ * the card titles beside them. `solid` is for a chip that is the
+ * only colour in its row; `outline` is the quiet one.
+ */
+export const AllVariants: Story = {
+  render: (avatarProps) => (
+    <StorySection title="The colour is a hash of the key, so the same person is the same colour on every machine and every reload.">
+      <StoryGrid columns={3}>
+        {(["soft", "outline", "solid"] as const).map(
+          (appearance) => (
+            <StoryCell key={appearance} label={appearance}>
+              <StoryRow>
+                {ROSTER.map((person) => (
+                  <Avatar
+                    {...avatarProps}
+                    appearance={appearance}
+                    categoricalKey={person.id}
+                    key={person.id}
+                    name={person.name}
+                  />
+                ))}
+              </StoryRow>
+            </StoryCell>
+          ),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Everything the chip can be showing, including the two that are
+ * easy to get wrong: a photo that does not load, and nobody at all.
+ */
+export const AllStates: Story = {
+  render: (avatarProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell label="sizes">
+        <StoryRow>
+          <Avatar {...avatarProps} size="sm" />
+
+          <Avatar {...avatarProps} size="md" />
+
+          <Avatar {...avatarProps} size="lg" />
+        </StoryRow>
+      </StoryCell>
+
+      <StoryCell label="a mononym gets one letter">
+        <Avatar {...avatarProps} name="Bo" />
+      </StoryCell>
+
+      <StoryCell label="a glyph instead of the letters">
+        <Avatar
+          {...avatarProps}
+          icon={<AgentGlyph />}
+          name="Agentic"
+        />
+      </StoryCell>
+
+      <StoryCell label="a chosen colour beats the hash">
+        <StoryRow>
+          <Avatar
+            {...avatarProps}
+            categorical={4}
+            name="Wren Okonkwo"
+          />
+
+          <Avatar
+            {...avatarProps}
+            categorical={9}
+            name="Ines Marchetti"
+          />
+        </StoryRow>
+      </StoryCell>
+
+      <StoryCell label="a photo, clipped to the circle">
+        <Avatar
+          {...avatarProps}
+          imageUrl={PORTRAIT_URL}
+          name="Tomas Ericsson"
+          size="lg"
+        />
+      </StoryCell>
+
+      <StoryCell label="a photo that 404s falls back to the letters">
+        <Avatar
+          {...avatarProps}
+          imageUrl={MISSING_PORTRAIT_URL}
+          name="Kit Sandoval"
+          size="lg"
+        />
+      </StoryCell>
+
+      <StoryCell label="unassigned draws nothing at all">
+        {/*
+         * There is no chip in this cell, and that is the assertion.
+         * A grey "None" placeholder is a fact nobody needed,
+         * repeated down every unassigned row at the same weight as
+         * the chips that mean something.
+         */}
+        <Avatar {...avatarProps} name={null} />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The placement it was built for: a row per task, the chip answering
+ * "whose is this?" without spending a column on the word.
+ *
+ * The middle row is unassigned. It draws nothing, so the row is
+ * shorter by exactly one chip and says nothing false.
+ */
+export const InAList: Story = {
+  render: () => (
+    <Card heading="Today">
+      <ul className="flex list-none flex-col gap-2 p-0">
+        {[
+          {
+            assignee: ROSTER[0],
+            title:
+              "Fold the second scheduler into the broker",
+          },
+          {
+            assignee: undefined,
+            title: "Fingerprint duplicate uploads",
+          },
+          {
+            assignee: ROSTER[1],
+            title: "One composed Storybook for the fleet",
+          },
+          {
+            assignee: ROSTER[3],
+            title: "Retire the legacy rest_command bridge",
+          },
+        ].map((task) => (
+          <li
+            /*
+             * The chip's slot is **reserved by the layout**, in `em`
+             * of the row's own type, and the unassigned row simply
+             * leaves it empty. That is the composition the "draws
+             * nothing" rule asks for: a grid column keeps every
+             * title on one start edge without the design system
+             * inventing a grey placeholder to hold the space open.
+             *
+             * The wrapper around the chip is what makes it work. A
+             * component that returns `null` contributes **no grid
+             * item**, so without it the title of an unassigned row
+             * slides into the first column — which is the one way
+             * this composition goes wrong, and it goes wrong
+             * silently.
+             */
+            className="grid grid-cols-[2em_1fr] items-center gap-3"
+            key={task.title}
+          >
+            <span className="justify-self-center">
+              <Avatar
+                categoricalKey={task.assignee?.id}
+                name={task.assignee?.name}
+                size="sm"
+              />
+            </span>
+
+            <span className="text-content-secondary text-sm">
+              {task.title}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </Card>
+  ),
+}

package/src/Avatar/Avatar.test.tsx

@@ -0,0 +1,143 @@
+import { composeStories } from "@storybook/react"
+import { expect, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Avatar.stories.tsx"
+
+const { AllStates, AllVariants, Default, InAList } =
+  composeStories(stories)
+
+/**
+ * The whole contract in one test: the name reaches assistive
+ * technology and a pointer, and reaches the page as text **nowhere
+ * at all**. The component exists to delete a printed "Owner" from
+ * every card on a board, so a name that leaks back into the DOM as
+ * text is the one regression that matters.
+ */
+test("the name is readable by an agent and never printed", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const avatar = expectAgentDrivable(canvas, {
+    name: "Ada Lovelace",
+    role: "img",
+  })
+
+  await expect(avatar).toHaveAttribute(
+    "title",
+    "Ada Lovelace",
+  )
+
+  // The letters are what is on screen, and they are hidden from the
+  // accessibility tree so the chip is announced once.
+  await expect(canvas.getByText("AL")).toHaveAttribute(
+    "aria-hidden",
+    "true",
+  )
+
+  await expect(
+    canvas.queryByText("Ada Lovelace"),
+  ).toBeNull()
+
+  await expectNoAxeViolations(avatar)
+})
+
+/**
+ * Unassigned draws nothing — not a grey placeholder, not an empty
+ * circle, not a whitespace-sized gap that shifts the row.
+ *
+ * Asserted through the story rather than by rendering the component
+ * directly, because the failure this prevents is a *layout* one: a
+ * row with no assignee has to look like a row with no assignee.
+ */
+test("an unassigned avatar renders nothing at all", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  // Nine chips are storied and a tenth is `name={null}`.
+  await expect(canvas.getAllByRole("img")).toHaveLength(9)
+
+  await expect(canvas.queryByText("None")).toBeNull()
+
+  // And the same in the list placement: four rows, three chips.
+  const list = await mountStory(InAList)
+
+  await expect(
+    list.canvas.getAllByRole("listitem"),
+  ).toHaveLength(4)
+
+  await expect(
+    list.canvas.getAllByRole("img"),
+  ).toHaveLength(3)
+})
+
+/**
+ * A photo is never the only thing. An expired signed URL, a 404, or
+ * an app with no photos at all lands on the initials rather than on
+ * a broken-image glyph — which is what a hand-rolled avatar shows,
+ * because nobody writes the `onError` until they see it.
+ */
+test("a photo that fails falls back to the initials", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const broken = expectAgentDrivable(canvas, {
+    name: "Kit Sandoval",
+    role: "img",
+  })
+
+  await waitFor(async () => {
+    await expect(broken.querySelector("img")).toBeNull()
+  })
+
+  await expect(broken).toHaveTextContent("KS")
+
+  // The photo that *does* load stays a photo, so the fallback is not
+  // simply "the image never renders".
+  const loaded = expectAgentDrivable(canvas, {
+    name: "Tomas Ericsson",
+    role: "img",
+  })
+
+  await expect(loaded.querySelector("img")).not.toBeNull()
+
+  // The image carries no name of its own — the chip already has one,
+  // and a second copy is how an avatar gets announced twice.
+  await expect(loaded.querySelector("img")).toHaveAttribute(
+    "alt",
+    "",
+  )
+})
+
+/**
+ * The colour is a pure function of the key, so the same person is
+ * the same colour in every appearance, on every machine, and in a
+ * server render. A colour assigned at random on first render is a
+ * different colour on the next reload, which is the failure mode
+ * `getCategoricalIndex` exists to prevent.
+ */
+test("one person is one colour, and a chosen index wins", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const indexes = new Set(
+    canvas
+      .getAllByRole("img", { name: "Ada Lovelace" })
+      .map(
+        (avatar: HTMLElement) =>
+          /categorical-(\d+)-/.exec(avatar.className)?.[1],
+      ),
+  )
+
+  await expect(indexes.size).toBe(1)
+
+  await expect(indexes.has(undefined)).toBe(false)
+
+  // A stored pick is not a hash — it is passed, and it wins.
+  const states = await mountStory(AllStates)
+
+  await expect(
+    states.canvas.getByRole("img", {
+      name: "Wren Okonkwo",
+    }),
+  ).toHaveClass("bg-categorical-4-surface")
+})

package/src/Avatar/Avatar.tsx

@@ -0,0 +1,270 @@
+import type { CategoricalIndex } from "@charcuterie/tokens"
+import { getCategoricalIndex } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+import { useState } from "react"
+
+import { CATEGORICAL_APPEARANCE_CLASS } from "../categoricalStyles.ts"
+import type { IntentAppearance } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type AvatarSize = keyof typeof AVATAR_SIZE_CLASS
+
+export type AvatarProps = Omit<
+  ComponentPropsWithRef<"span">,
+  "children"
+> & {
+  /**
+   * The same three the rest of the categorical family wears, minus
+   * `ghost` — a chip with no fill and no border is a floating
+   * letter, and the whole job here is to be a **shape** the eye
+   * finds in a list.
+   */
+  appearance?: Exclude<IntentAppearance, "ghost">
+  /**
+   * The colour, when somebody has chosen one. Omitted, it is derived
+   * — see `categoricalKey` — so an avatar always has a colour and
+   * never has to be given one.
+   */
+  categorical?: CategoricalIndex
+  /**
+   * What the derived colour is hashed from when `categorical` is
+   * absent. Defaults to `name`.
+   *
+   * Pass the **user's id** wherever one exists. `getCategoricalIndex`
+   * does no normalization on purpose, so hashing the name means a
+   * rename — or a trailing space — silently repaints a person the
+   * reader had already learned to recognise. An id does not move.
+   */
+  categoricalKey?: string
+  /**
+   * A glyph instead of the initials — a robot for an agent account,
+   * a lock for a service account. The library ships **no icons**, so
+   * this is the app's own
+   * ([decision](../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)).
+   * It is decoration: the name still travels in `aria-label`, and a
+   * glyph the font cannot render must not be the only thing
+   * carrying who this is.
+   */
+  icon?: ReactNode
+  /**
+   * A photo. Optional, and **it is never the only thing** — a
+   * request that 404s, a signed URL that expired, or an app that
+   * simply has no photos falls back to the initials with no empty
+   * box in between.
+   */
+  imageUrl?: string
+  /**
+   * The letters, when the derivation is wrong. Derived from `name`
+   * otherwise: the first character of each of the first two
+   * whitespace-separated words, upper-cased.
+   *
+   * Worth passing for a name the split gets wrong — a mononym that
+   * wants two letters, a name whose family part comes first, a
+   * handle with punctuation in it.
+   */
+  initials?: string
+  /**
+   * Who this is. Read by assistive technology and shown on hover;
+   * **never printed as visible text**, which is the entire point of
+   * the component.
+   *
+   * Nullable, and that is a decision rather than a loose type — see
+   * the note on the component about what an unassigned row draws.
+   */
+  name: string | null | undefined
+  size?: AvatarSize
+}
+
+/**
+ * One rule: **the circle is 1.9 x its own type size**, and `size`
+ * picks which step of the type scale that is.
+ *
+ * 1.9 rather than a tighter number because a circle only offers its
+ * full width on the centre line. Two capitals measure about 1.25em
+ * in this face, and a chord taken at the cap height of a 1.75em
+ * circle is barely wider than that — measured, not guessed.
+ *
+ * It is em-based rather than a fixed `size-5` / `size-7` / `size-9`,
+ * and that is the whole of the design. Every length in this token
+ * set moves with the density axis — `--font-size-xs` is 0.88rem
+ * compact, 0.94rem at desktop and 1.11rem on the kiosk — so a chip
+ * pinned to 20px holds two letters at one density and clips them at
+ * the next. `controlStyles.ts` says the same thing about badges and
+ * dots: non-control sizing is type-relative on purpose, because a
+ * chip that stays 20px while the kiosk scales the prose around it
+ * reads as a rendering fault.
+ *
+ * The hand-rolled avatar this replaces is the worked example. It was
+ * `size-5` with `text-[0.625rem]` — a 10px font, which is **not a
+ * step of this type scale at any density**, because 20px is not
+ * enough room for two characters at the smallest size the tokens
+ * actually offer. A component that has to invent a font size to fit
+ * its own box has the wrong box.
+ */
+const AVATAR_SIZE_CLASS = {
+  sm: "size-[1.9em] text-xs",
+  md: "size-[1.9em] text-md",
+  lg: "size-[1.9em] text-xl",
+} as const
+
+/**
+ * The first character of each of the first two words.
+ *
+ * `Array.from` rather than `charAt`, so a name that starts outside
+ * the BMP contributes a whole character instead of half a surrogate
+ * pair and a replacement glyph.
+ */
+const toInitials = (name: string): string =>
+  name
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map((word) => Array.from(word)[0] ?? "")
+    .join("")
+    .toLocaleUpperCase()
+
+/**
+ * A person, as a coloured chip — a glyph or an initial, with the
+ * name attached where only assistive technology and a hover can
+ * reach it.
+ *
+ * It exists to delete a printed name. Docket's board put the word
+ * *"Owner"* on most of its cards, which is a column of identical
+ * text doing the work of a colour; the fleet's boards all want the
+ * same chip, and `Board.stories.tsx` had already hand-rolled one
+ * inside a story file.
+ *
+ * ### Unassigned draws **nothing**, and the component owns that
+ *
+ * `name` accepts `null` and `undefined`, and either renders `null`.
+ * A grey *"None"* placeholder is a decision the design system makes
+ * against the reader: it is a chip that says a fact nobody needed,
+ * repeated down every unassigned row, at the same weight as the
+ * chips that mean something.
+ *
+ * The alternative is a ternary at every call site, and the call
+ * sites are the whole problem — a board, a table, a card footer, a
+ * detail pane, each written on a different day. The one that forgets
+ * is the one that ships the grey circle. Absence is expressed once,
+ * here, which is the same call `Board` makes with `onMove`: no
+ * handler means no affordance, rather than a disabled one.
+ *
+ * A consumer that genuinely wants to *say* "unassigned" still can —
+ * that is text, or an `EmptyState`, and neither of them is an
+ * avatar.
+ *
+ * ### The name is never visible text
+ *
+ * `role="img"` with an `aria-label`, exactly as `Swatch` does, so
+ * `getByRole("img", { name })` is the one handle whether the chip is
+ * showing a photo, a glyph or two letters. `title` carries the same
+ * string for a pointer, which is the only channel a person browsing
+ * with their eyes has — the letters `KG` are not a name.
+ *
+ * That is also why there is no `isNameVisible`: an avatar whose name
+ * is printed beside it is a name with a decoration in front of it,
+ * and the layout that wants one should print the name and skip the
+ * chip.
+ *
+ * ### The colour is derived, never invented
+ *
+ * `categorical` is the ten-wide non-semantic scale — the same one
+ * `Badge` takes — and **not** an `intent`. An intent is a claim the
+ * design system makes; a person is not `danger`. With no
+ * `categorical` the index comes from `getCategoricalIndex`, which is
+ * a pure function of the key, so the same person is the same colour
+ * on every machine, every reload, and in a server render. Ten
+ * colours means collisions past ten people, and that is a property
+ * of the palette rather than a fault in the hash: the colour helps
+ * you *scan*, and the accessible name is what identifies.
+ *
+ * ### There is no `AvatarGroup`
+ *
+ * Deliberately. A stack of overlapping chips with a `+3` needs
+ * answers to which three survive, in what order, and what the
+ * overflow announces — and no consumer has asked the question yet. A
+ * row of `Avatar`s in a flex box is what a multi-assignee list looks
+ * like until one does.
+ */
+export const Avatar = ({
+  appearance = "soft",
+  categorical,
+  categoricalKey,
+  className,
+  icon,
+  imageUrl,
+  initials,
+  name,
+  size = "md",
+  title,
+  ...spanProps
+}: AvatarProps): ReactNode => {
+  /**
+   * The URL that failed, rather than a `hasFailed` boolean.
+   *
+   * A boolean has to be *reset* when `imageUrl` changes, which is an
+   * effect syncing a prop into state — the shape this library
+   * refuses everywhere else
+   * ([decision](../../../docs/decisions/2026-07-29-logic-hooks-are-uncontrolled.md)).
+   * Storing the URL makes the comparison below derive the answer, so
+   * a second photo gets its own attempt and a re-render never
+   * resurrects a dead one.
+   */
+  const [failedImageUrl, setFailedImageUrl] = useState<
+    string | undefined
+  >(undefined)
+
+  const hasImageError =
+    imageUrl !== undefined && failedImageUrl === imageUrl
+
+  const trimmedName = name?.trim()
+
+  if (!trimmedName) {
+    return null
+  }
+
+  const resolvedInitials =
+    initials ?? toInitials(trimmedName)
+
+  const resolvedCategorical =
+    categorical ??
+    getCategoricalIndex(categoricalKey ?? trimmedName)
+
+  return (
+    <span
+      {...spanProps}
+      aria-label={trimmedName}
+      className={toClassName(
+        "inline-grid shrink-0 place-items-center overflow-hidden rounded-full border font-medium leading-none",
+        AVATAR_SIZE_CLASS[size],
+        CATEGORICAL_APPEARANCE_CLASS[resolvedCategorical][
+          appearance
+        ],
+        className,
+      )}
+      role="img"
+      title={title ?? trimmedName}
+    >
+      {imageUrl !== undefined && !hasImageError ? (
+        // `alt=""` on purpose: the wrapper already carries the
+        // accessible name, and a second copy on the image is how an
+        // avatar gets announced twice.
+        <img
+          alt=""
+          className="size-full object-cover"
+          onError={() => {
+            setFailedImageUrl(imageUrl)
+          }}
+          src={imageUrl}
+        />
+      ) : (
+        <span aria-hidden="true">
+          {icon ?? resolvedInitials}
+        </span>
+      )}
+    </span>
+  )
+}

package/src/Board/Board.mdx

@@ -108,6 +108,32 @@ An app that already owns a glyph set passes `moveIcon` and buys back ~55px a row
 
 <Canvas of={BoardStories.AllVariants} />
 
+## A lane heading can be a link
+
+<Canvas of={BoardStories.LinkedLaneHeadings} />
+
+`BoardLane.href` makes the column title navigate — the "show me only this column" route a
+board screen wants. It is **a link inside the heading, never a heading replaced by a
+link**: the `<h3>` keeps the level the caller passed, keeps its id, and keeps naming the
+lane's `group`, so the screen-reader outline of a linked board is the outline of an
+unlinked one.
+
+`label` stays a `string` rather than widening to a `ReactNode`, and that is the trade the
+prop exists to avoid. The same value names the lane in the move menu on every card, in the
+Narrow View's segmented control, in the "+ n more in Todo" line, and in the sentence the
+live region reads after a move. None of those four can put a `ReactNode` in a string, so
+widening `label` would buy one linkable heading at the cost of four places that could no
+longer say which lane they mean.
+
+The link inherits the heading's colour and weight. `TextLink` still supplies the cursor,
+the focus ring and the hover underline, which is what says it is a link; a board whose
+three column titles are all accent-coloured competes with the card titles underneath, and
+those are what a reader is actually scanning. The `href` is routed through
+`RouterLinkProvider` like every other one in this library, so an app with a client-side
+router navigates without a full page load.
+
+An app that was putting a link in `actions` as a stopgap can take it out.
+
 **No `onMove` means read-only**, all or nothing: no handles, no menus, no drag. A per-card
 `isMovable` would put the decision in the data, where a card that cannot move looks identical
 to one nobody has thought about.