@charcuterie/ui 3.12.0 → 3.13.0

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

package/src/index.ts

@@ -63,6 +63,11 @@ export type {
   AlertSize,
 } from "./Alert/Alert.tsx"
 export { Alert } from "./Alert/Alert.tsx"
+export type {
+  AvatarProps,
+  AvatarSize,
+} from "./Avatar/Avatar.tsx"
+export { Avatar } from "./Avatar/Avatar.tsx"
 export type { BadgeProps } from "./Badge/Badge.tsx"
 export { Badge } from "./Badge/Badge.tsx"
 export type { BadgeShapeProps } from "./Badge/useBadgeShape.tsx"

package/src/sourceRules.test.ts

@@ -465,7 +465,15 @@ test("the barrel is the only place components are re-exported", async () => {
   // count by the `<Name>/<Name>.tsx` rule, and it IS exported from
   // the barrel as a function, because a host with its own clipboard
   // bridge needs the fallback chain without the button.
-  expect(componentNames.length).toBe(54)
+  //
+  // `Avatar` — a person as a coloured chip, so a board stops
+  // printing the same name on every card — is +1 -> 55. It has no
+  // members: the initials derivation is a private function in
+  // `Avatar.tsx`, and the colour it falls back to is
+  // `getCategoricalIndex`, which already lives in
+  // `@charcuterie/tokens` because a Node service and a Satori render
+  // both need to answer the colour question with no React in scope.
+  expect(componentNames.length).toBe(55)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)