@charcuterie/ui 3.12.0 → 3.14.0

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.

package/src/Board/Board.stories.tsx

@@ -3,6 +3,7 @@ import type { ReactNode } from "react"
 import { useState } from "react"
 
 import { Alert } from "../Alert/Alert.tsx"
+import { Avatar } from "../Avatar/Avatar.tsx"
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
 import {
@@ -71,26 +72,6 @@ const Mark = ({
   </span>
 )
 
-/**
- * An assignee. Two initials and a name nobody has to hover to hear —
- * an avatar with no accessible name is a coloured circle, which is
- * the fleet's most-repeated a11y defect after the unnamed icon
- * button.
- */
-const Avatar = ({
-  initials,
-  name,
-}: {
-  initials: string
-  name: string
-}): ReactNode => (
-  <span className="grid size-5 shrink-0 place-items-center rounded-full bg-intent-info-surface font-medium text-[0.625rem] text-intent-info-content">
-    <span aria-hidden="true">{initials}</span>
-
-    <VisuallyHidden>{`Assigned to ${name}`}</VisuallyHidden>
-  </span>
-)
-
 const ProjectChip = ({
   name,
 }: {
@@ -184,8 +165,20 @@ const toItem = ({
     </>
   ),
   title,
+  /*
+   * `Avatar` from this package, not a chip hand-rolled in a story
+   * file. This story *had* one — a `size-5` circle painted
+   * `intent-info`, with the name in a `VisuallyHidden` — which is
+   * exactly the shape three apps were about to write for
+   * themselves. The library owns the shape; the story owns the
+   * data.
+   */
   trailing: (
-    <Avatar initials={assignee[0]} name={assignee[1]} />
+    <Avatar
+      initials={assignee[0]}
+      name={assignee[1]}
+      size="sm"
+    />
   ),
 })
 
@@ -705,3 +698,36 @@ export const InBoardScreen: Story = {
     </div>
   ),
 }
+
+/**
+ * A lane whose heading goes somewhere — the "show me only this
+ * column" route.
+ *
+ * `href` on the lane, not a `ReactNode` label. The heading stays an
+ * `<h3>` at the level the caller asked for, keeps its id, and keeps
+ * naming the `group`; the anchor sits **inside** it, so the document
+ * outline is the same one a board with no links has.
+ *
+ * It also reads as the same heading: `TextLink` supplies the cursor,
+ * the focus ring and the hover underline, and the colour is
+ * inherited. Three accent-coloured column titles would compete with
+ * the card titles below them, which are what a reader is scanning.
+ */
+export const LinkedLaneHeadings: Story = {
+  render: (boardProps) => (
+    // The same fixed 72rem the other three-up stories use. Three
+    // lanes at once is a measurement of the board's own box, and a
+    // story that inherited the canvas width would show three linked
+    // headings on one machine and one plus a segmented control on
+    // another.
+    <Frame inlineSize="72rem">
+      <Board
+        {...boardProps}
+        lanes={LANES.map((lane) => ({
+          ...lane,
+          href: `/board/${lane.key}`,
+        }))}
+      />
+    </Frame>
+  ),
+}

package/src/Board/Board.test.tsx

@@ -17,6 +17,7 @@ const {
   Default,
   InBoardScreen,
   Interactive,
+  LinkedLaneHeadings,
   Responsive,
 } = composeStories(stories)
 
@@ -308,3 +309,64 @@ test("the board sits under a separate attention banner, and the page is clean",
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * A linkable column title is a **link inside the heading**, never a
+ * heading replaced by a link.
+ *
+ * The distinction is the whole reason `href` is a prop rather than a
+ * widened `label`: swap the `<h3>` for an `<a>` and the lane stops
+ * having a heading, the `group` loses the element it is named by,
+ * and the document outline gains a hole that no gate but a screen
+ * reader would notice.
+ */
+test("a lane heading with an href is a link inside a real heading", async () => {
+  const { canvas } = await mountStory(LinkedLaneHeadings)
+
+  const board = expectAgentDrivable(canvas, {
+    name: "Today",
+    role: "region",
+  })
+
+  for (const [laneKey, laneLabel] of [
+    ["todo", "Todo"],
+    ["in-progress", "In Progress"],
+    ["review", "Needs Review"],
+  ]) {
+    // Still a named group — the heading did not stop being the
+    // thing that names it.
+    expectAgentDrivable(canvas, {
+      name: laneLabel,
+      role: "group",
+    })
+
+    const heading = canvas.getByRole("heading", {
+      level: 3,
+      name: laneLabel,
+    })
+
+    const link = within(heading).getByRole("link", {
+      name: laneLabel,
+    })
+
+    await expect(link).toHaveAttribute(
+      "href",
+      `/board/${laneKey}`,
+    )
+  }
+
+  await expectNoAxeViolations(board)
+})
+
+/**
+ * The lane label is still a string everywhere else it is used, and
+ * a linked heading must not have changed that. The move menu, the
+ * segmented control and the truncation line all interpolate it.
+ */
+test("a linked lane still names itself in the move menu and the overflow line", async () => {
+  const { canvas } = await mountStory(LinkedLaneHeadings)
+
+  await expect(
+    canvas.getByText("+ 11 more in Needs Review"),
+  ).toBeInTheDocument()
+})

package/src/Board/BoardLaneList.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from "react"
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
 import { EmptyState } from "../EmptyState/EmptyState.tsx"
+import { TextLink } from "../TextLink/TextLink.tsx"
 import { toClassName } from "../toClassName.ts"
 import type { BoardItem } from "./BoardCard.tsx"
 import { BoardCard } from "./BoardCard.tsx"
@@ -20,6 +21,23 @@ export type BoardLane = {
    * requirement and an empty lane is the one a person sees most.
    */
   emptyState?: ReactNode
+  /**
+   * Where the lane's own heading navigates — a route showing this
+   * lane and nothing else.
+   *
+   * **A link inside the heading, never a heading replaced by a
+   * link.** The `<h3>` keeps its level, its id and its place in the
+   * document outline, so the lane stays a named `group` and the
+   * screen-reader outline is unchanged; the anchor sits inside it.
+   * Routed through `RouterLinkProvider` like every other `href` in
+   * this library, so an app with a client-side router navigates
+   * without a full page load and one without it still gets a real
+   * `<a href>`.
+   *
+   * Absent means the heading is plain text, which is what every
+   * existing consumer gets.
+   */
+  href?: string
   /**
    * The **true** size of the lane, when `items` is a truncated page
    * of it. This is what the count badge shows, and the difference
@@ -31,6 +49,18 @@ export type BoardLane = {
   itemCount?: number
   items: readonly BoardItem[]
   key: string
+  /**
+   * The lane's name, and it stays a **string** rather than widening
+   * to a `ReactNode`.
+   *
+   * It is not only a heading: 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 out after a move. A `ReactNode` is not something
+   * any of those four can put in a string, so widening this would
+   * trade one linkable heading for four places that can no longer
+   * say which lane they mean. `href` buys the link without that.
+   */
   label: string
   /**
    * What "+ n more in this lane" does. With no handler the line is
@@ -177,7 +207,28 @@ export const BoardLaneList = ({
               className="font-semibold text-content-primary text-sm"
               id={headingId}
             >
-              {lane.label}
+              {lane.href ? (
+                /*
+                 * `text-inherit` and `font-semibold` on purpose: a
+                 * linkable column title should read as the same
+                 * heading it was, not as a blue word. The link
+                 * announces itself by being a link — the cursor,
+                 * the focus ring and the hover underline all come
+                 * from `TextLink` — and a board whose every lane
+                 * title is accent-coloured competes with the card
+                 * titles underneath it, which are the things a
+                 * reader is actually scanning.
+                 */
+                <TextLink
+                  appearance="standalone"
+                  className="font-semibold text-inherit"
+                  href={lane.href}
+                >
+                  {lane.label}
+                </TextLink>
+              ) : (
+                lane.label
+              )}
             </Heading>
 
             <Badge