@charcuterie/ui 4.9.1 → 4.10.0

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -0,0 +1,250 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } 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 "./Breadcrumbs.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  Interactive,
+  Playground,
+  Responsive,
+  Routed,
+} = composeStories(stories)
+
+/**
+ * The APG breadcrumb pattern: a named `<nav>` landmark around an
+ * ordered list, one `listitem` per rung.
+ */
+test("is a named navigation landmark around an ordered list", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+
+  const nav = expectAgentDrivable(canvas, {
+    name: "Breadcrumb",
+    role: "navigation",
+  })
+
+  const list = nav.querySelector("ol")
+
+  await expect(list).not.toBeNull()
+  await expect(
+    canvas.getAllByRole("listitem"),
+  ).toHaveLength(4)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("every rung but the last is a link; the last is the current page", async () => {
+  const { canvas } = await mountStory(Playground)
+
+  const links = canvas.getAllByRole("link")
+
+  await expect(
+    links.map((link: HTMLElement) => link.textContent),
+  ).toEqual(["Library", "Handbook", "runbooks"])
+  await expect(links[1]).toHaveAttribute(
+    "href",
+    "/handbook",
+  )
+
+  const current = canvas.getByText(
+    "restoring-a-snapshot.md",
+  )
+
+  await expect(current.tagName).toBe("SPAN")
+  await expect(current).toHaveAttribute(
+    "aria-current",
+    "page",
+  )
+  // Exactly one current rung.
+  await expect(
+    canvas
+      .getByRole("navigation")
+      .querySelectorAll("[aria-current]"),
+  ).toHaveLength(1)
+})
+
+/**
+ * The Whereabouts shape: the trail sits above a heading that already
+ * names the page, so every rung links and nothing claims to be current.
+ */
+test("a trail of links only has no current rung", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  const nav: HTMLElement = canvas.getByRole("navigation", {
+    name: "Full place trail",
+  })
+
+  await expect(nav.querySelectorAll("a")).toHaveLength(3)
+  await expect(
+    nav.querySelector("[aria-current]"),
+  ).toBeNull()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the separator is decorative", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const nav: HTMLElement = canvas.getByRole("navigation", {
+    name: "Slash trail",
+  })
+
+  // Three separators between four rungs, all hidden, none before the
+  // first rung.
+  const separators = nav.querySelectorAll(
+    '[aria-hidden="true"]',
+  )
+
+  await expect(separators).toHaveLength(3)
+  await expect(
+    nav.querySelector("li")?.querySelector("[aria-hidden]"),
+  ).toBeNull()
+  // The slash never reaches a rung's name.
+  await expect(
+    nav.querySelector('a[href="/handbook"]'),
+  ).toHaveAccessibleName("Handbook")
+})
+
+/**
+ * A link rung and a button rung are the same thing to a reader, so
+ * they are painted the same: same colour, same weight.
+ */
+test("a button rung is painted as a link rung", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const link = canvas.getAllByRole("link", {
+    name: "Places",
+  })[0]
+
+  const button = canvas.getAllByRole("button", {
+    name: "Places",
+  })[0]
+
+  if (link === undefined || button === undefined) {
+    throw new Error("Both rungs must render.")
+  }
+
+  await expect(getComputedStyle(button).color).toBe(
+    getComputedStyle(link).color,
+  )
+  await expect(getComputedStyle(button).fontWeight).toBe(
+    getComputedStyle(link).fontWeight,
+  )
+  await expect(
+    getComputedStyle(button).backgroundColor,
+  ).toBe("rgba(0, 0, 0, 0)")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Wraps, never truncates: at the narrowest panel every rung's full
+ * text is still in the layout, and no rung is wider than the trail.
+ */
+test("a long trail wraps inside a narrow container and hides nothing", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  const nav: HTMLElement = canvas.getByRole("navigation", {
+    name: "Trail at 15rem",
+  })
+
+  const navWidth = nav.getBoundingClientRect().width
+
+  for (const item of Array.from(
+    nav.querySelectorAll("li"),
+  )) {
+    await expect(
+      item.getBoundingClientRect().width,
+    ).toBeLessThanOrEqual(navWidth + 0.5)
+  }
+
+  const fileName = canvas.getAllByText(
+    /a-very-long-file-name/,
+  )[0]
+
+  if (fileName === undefined) {
+    throw new Error("The file rung must render.")
+  }
+
+  await expect(
+    getComputedStyle(fileName).textOverflow,
+  ).not.toBe("ellipsis")
+  await expect(fileName.scrollWidth).toBeLessThanOrEqual(
+    fileName.clientWidth + 1,
+  )
+  // More than one line: the list wrapped.
+  await expect(
+    nav.querySelector("ol")?.getBoundingClientRect().height,
+  ).toBeGreaterThan(30)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("an in-app href goes through the injected router", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  await expect(
+    canvas.getByRole("link", { name: "Places" }),
+  ).toHaveAttribute("data-router", "soft")
+})
+
+/**
+ * Tab walks the rungs in order and skips the current folder, which is
+ * text. Enter climbs to a rung; Space does the same on the next one.
+ */
+test("the keyboard walks and climbs the trail", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  await expect(
+    canvas
+      .getAllByRole("button")
+      .map((button: HTMLElement) => button.textContent),
+  ).toEqual(["G:", "Photos", "2026"])
+
+  await userEvent.tab()
+  await expect(
+    canvas.getByRole("button", { name: "G:" }),
+  ).toHaveFocus()
+
+  await userEvent.tab()
+  await userEvent.tab()
+  await expect(
+    canvas.getByRole("button", { name: "2026" }),
+  ).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+
+  await expect(
+    canvas.getByText("2026").closest("[aria-current]"),
+  ).toHaveAttribute("aria-current", "page")
+  await expect(
+    canvas.queryByText("Garden", { selector: "li *" }),
+  ).toBeNull()
+
+  // The pressed rung became text and left the tab order, so Tab
+  // starts again from the top.
+  await userEvent.tab()
+  await userEvent.tab()
+  await expect(
+    canvas.getByRole("button", { name: "Photos" }),
+  ).toHaveFocus()
+
+  await userEvent.keyboard(" ")
+
+  await expect(canvas.getByText("Photos")).toHaveAttribute(
+    "aria-current",
+    "page",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,179 @@
+import type { Key, ReactNode } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { toClassName } from "../toClassName.ts"
+
+/**
+ * One rung of the trail.
+ *
+ * Which of the three it becomes is read off the fields it carries, so
+ * a caller mapping a path to items never has to say what the rung
+ * *is* — only where it goes:
+ *
+ *  - `href` — a real `<a href>`, through `TextLink`, so an in-app path
+ *    goes through the injected router exactly as every other link in
+ *    the library does.
+ *  - `onSelect` and no `href` — a `<button>` painted as the same link.
+ *    For a trail over state that has no URL: image-viewer's folder
+ *    path and mux-magic's file-explorer modal both move a browser
+ *    around a disk without touching the address bar.
+ *  - neither — plain text. On the **last** item that is the current
+ *    page, and it carries `aria-current="page"`.
+ */
+export type BreadcrumbItem = {
+  href?: string
+  /**
+   * React's list key. Optional, because `label` is a node and cannot
+   * be one; the fallback is `href`, then the position. Pass it when
+   * two rungs can share an `href` or the trail reorders.
+   */
+  key?: Key
+  label: ReactNode
+  /**
+   * Runs on activation. With an `href` it runs alongside the
+   * navigation (closing a drawer, say); without one it IS the
+   * navigation.
+   */
+  onSelect?: () => void
+}
+
+export type BreadcrumbsProps = {
+  className?: string
+  items: readonly BreadcrumbItem[]
+  /**
+   * The `<nav>` landmark's name. Two trails on one page need two
+   * different names, or axe's `landmark-unique` fails.
+   */
+  label?: string
+  /**
+   * Drawn between rungs, always `aria-hidden`. The default is a
+   * chevron drawn in CSS borders rather than a `›` character: the
+   * library ships no symbol glyphs in a default, because a font that
+   * lacks one paints nothing
+   * (`docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md`).
+   * Folio's `/` is a fine override — it is the app's choice to make.
+   */
+  separator?: ReactNode
+}
+
+/**
+ * The link paint without the `<a>`: `TextLink`'s standalone look,
+ * restated for the `onSelect` rung so a button crumb and a link crumb
+ * are indistinguishable at rest, on hover, and under focus.
+ */
+const BUTTON_CRUMB_CLASS =
+  "inline cursor-pointer rounded-xs border-0 bg-transparent p-0 text-start font-medium text-intent-accent-content underline-offset-2 hover:underline"
+
+/**
+ * `wrap-anywhere` on every label, and no `truncate`: a trail that cuts
+ * a folder name to `Office Sh…` hides the one word the reader came to
+ * find. A long unbroken segment — a hash, a file name — breaks inside
+ * itself instead of pushing the row wider than its container.
+ */
+const LABEL_CLASS = "min-w-0 wrap-anywhere"
+
+/**
+ * Right-pointing in a left-to-right page, left-pointing in a
+ * right-to-left one: the two borders are logical (`border-e`), and the
+ * rotation flips with the direction so the corner always points the
+ * way the trail reads.
+ */
+const DEFAULT_SEPARATOR = (
+  <span className="inline-block size-1.5 shrink-0 rotate-45 border-e-[1.5px] border-t-[1.5px] border-current rtl:-rotate-45" />
+)
+
+const getItemKey = (
+  item: BreadcrumbItem,
+  index: number,
+): Key => item.key ?? item.href ?? index
+
+/**
+ * A path back up a hierarchy: `Places › Office › Office Shelves`.
+ *
+ * Folio, image-viewer and mux-magic each hand-rolled one, and they
+ * disagreed on everything a shared shape should settle — one was a
+ * `<nav>` of bare links with no list, two were `<div>`s of buttons
+ * with no landmark, one truncated the current segment, one gave the
+ * current folder no `aria-current`. This is the WAI-ARIA APG
+ * breadcrumb pattern: a `<nav>` landmark around an `<ol>`, because
+ * the order is the meaning.
+ *
+ * The current page is the **last item with nowhere to go**. A trail
+ * that sits above a heading already naming the page — Whereabouts'
+ * `Places › Office` over an `Office Shelves` heading — gives every
+ * item an `href`, and then no rung is current, which is correct: the
+ * page is named once, by the heading.
+ */
+export const Breadcrumbs = ({
+  className,
+  items,
+  label = "Breadcrumb",
+  separator,
+}: BreadcrumbsProps): ReactNode => (
+  <nav aria-label={label} className={className}>
+    <ol className="m-0 flex list-none flex-wrap items-center gap-x-2 gap-y-1 p-0 text-content-secondary text-sm">
+      {items.map((item, index) => {
+        const isLast = index === items.length - 1
+
+        const isCurrent =
+          isLast &&
+          item.href === undefined &&
+          item.onSelect === undefined
+
+        return (
+          <li
+            className="inline-flex min-w-0 items-center gap-x-2"
+            key={getItemKey(item, index)}
+          >
+            {index > 0 ? (
+              <span
+                aria-hidden="true"
+                className="inline-flex shrink-0 items-center text-content-muted"
+              >
+                {separator ?? DEFAULT_SEPARATOR}
+              </span>
+            ) : null}
+
+            {item.href !== undefined ? (
+              <TextLink
+                appearance="standalone"
+                className={LABEL_CLASS}
+                href={item.href}
+                onClick={item.onSelect}
+              >
+                {item.label}
+              </TextLink>
+            ) : item.onSelect !== undefined ? (
+              <button
+                className={toClassName(
+                  BUTTON_CRUMB_CLASS,
+                  FOCUS_RING_CLASS,
+                  LABEL_CLASS,
+                )}
+                onClick={item.onSelect}
+                type="button"
+              >
+                {item.label}
+              </button>
+            ) : (
+              <span
+                aria-current={
+                  isCurrent ? "page" : undefined
+                }
+                className={toClassName(
+                  LABEL_CLASS,
+                  isCurrent
+                    ? "font-medium text-content-primary"
+                    : undefined,
+                )}
+              >
+                {item.label}
+              </span>
+            )}
+          </li>
+        )
+      })}
+    </ol>
+  </nav>
+)

package/src/index.ts

@@ -37,6 +37,8 @@ export type {
   AccordionProps,
 } from "./Accordion/Accordion.tsx"
 export { Accordion } from "./Accordion/Accordion.tsx"
+export type { ActionMenuProps } from "./ActionMenu/ActionMenu.tsx"
+export { ActionMenu } from "./ActionMenu/ActionMenu.tsx"
 export type {
   ActionTileItem,
   ActionTilesAccent,
@@ -99,6 +101,11 @@ export {
   getIsMoveMeaningful,
   toSettledIndex,
 } from "./Board/boardMove.ts"
+export type {
+  BreadcrumbItem,
+  BreadcrumbsProps,
+} from "./Breadcrumbs/Breadcrumbs.tsx"
+export { Breadcrumbs } from "./Breadcrumbs/Breadcrumbs.tsx"
 export type { ButtonProps } from "./Button/Button.tsx"
 export { Button } from "./Button/Button.tsx"
 export type { ButtonLinkProps } from "./ButtonLink/ButtonLink.tsx"

package/src/sourceRules.test.ts

@@ -615,7 +615,9 @@ test("the barrel is the only place components are re-exported", async () => {
   // question the same way the bars are placed, or the two answers
   // drift by a day and nothing says so.
   // ProgressCard composes Card and ProgressBar for progress-first dashboards.
-  expect(componentNames.length).toBe(67)
+  // Breadcrumbs composes TextLink for the path back up a hierarchy.
+  // ActionMenu composes IconButton and Menu for the overflow control.
+  expect(componentNames.length).toBe(69)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)