@charcuterie/ui 4.9.0 → 4.10.0

package/src/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -0,0 +1,319 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+import { type ReactNode, useState } from "react"
+
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import type { BreadcrumbItem } from "./Breadcrumbs.tsx"
+import { Breadcrumbs } from "./Breadcrumbs.tsx"
+
+/**
+ * A stand-in for react-router's `<Link>`, marked so `Routed` (and its
+ * test) can show which rungs the injected router was handed.
+ */
+const SoftRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a {...linkProps} data-router="soft" href={href} />
+)
+
+/** A document trail ending on the current page. */
+const DOCUMENT_TRAIL: BreadcrumbItem[] = [
+  { href: "/", label: "Library" },
+  { href: "/handbook", label: "Handbook" },
+  { href: "/handbook/runbooks", label: "runbooks" },
+  { label: "restoring-a-snapshot.md" },
+]
+
+/**
+ * A trail that sits above a heading which already names the page, so
+ * every rung is a link and none of them is current.
+ */
+const PLACE_TRAIL: BreadcrumbItem[] = [
+  { href: "/places", label: "Places" },
+  { href: "/places/office", label: "Office" },
+  {
+    href: "/places/office/shelves",
+    label: "Office Shelves",
+  },
+]
+
+const LONG_TRAIL: BreadcrumbItem[] = [
+  { href: "/", label: "Library" },
+  { href: "/archive", label: "Archive" },
+  { href: "/archive/2026", label: "2026" },
+  {
+    href: "/archive/2026/field-recordings",
+    label: "Field recordings",
+  },
+  {
+    label:
+      "a-very-long-file-name-with-no-spaces-at-all-0123456789abcdef.flac",
+  },
+]
+
+const meta = {
+  title: "Components/Layout/Breadcrumbs",
+  component: Breadcrumbs,
+  parameters: { layout: "padded" },
+  // The component's own default, restated so the props table and the
+  // control agree.
+  args: {
+    items: DOCUMENT_TRAIL,
+    label: "Breadcrumb",
+  },
+} satisfies Meta<typeof Breadcrumbs>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
+
+/**
+ * The shapes a trail takes. Each cell's landmark carries its own name,
+ * because four `<nav>`s all called "Breadcrumb" on one page is axe's
+ * `landmark-unique` — the same rule an app with two trails would hit.
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <StorySection title="The last rung with nowhere to go is the current page. Give every rung an href and none is current.">
+      <StoryGrid columns={2}>
+        <StoryCell
+          align="stretch"
+          label="ends on the current page"
+        >
+          <Breadcrumbs
+            items={DOCUMENT_TRAIL}
+            label="Document trail"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="every rung a link (above a heading)"
+        >
+          <div className="flex flex-col gap-1">
+            <Breadcrumbs
+              items={PLACE_TRAIL.slice(0, -1)}
+              label="Place trail"
+            />
+            <h3 className="m-0 font-semibold text-content-primary text-lg">
+              Office Shelves
+            </h3>
+          </div>
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="onSelect rungs (no URL)"
+        >
+          <Breadcrumbs
+            items={[
+              { label: "G:", onSelect: () => {} },
+              { label: "Photos", onSelect: () => {} },
+              { label: "2026" },
+            ]}
+            label="Folder trail"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label='separator="/"'>
+          <Breadcrumbs
+            items={DOCUMENT_TRAIL}
+            label="Slash trail"
+            separator="/"
+          />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="one rung">
+          <Breadcrumbs
+            items={[{ label: "Library" }]}
+            label="Root trail"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="all links, last included"
+        >
+          <Breadcrumbs
+            items={PLACE_TRAIL}
+            label="Full place trail"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Hover and focus, forced by the pseudo-states addon. A link rung and
+ * a button rung sit side by side in each state: they must be
+ * indistinguishable, because to the reader they are the same thing.
+ */
+export const AllStates: Story = {
+  parameters: {
+    pseudo: {
+      focusVisible: [
+        "#focus-link a",
+        "#focus-button button",
+      ],
+      hover: ["#hover-link a", "#hover-button button"],
+    },
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="link · rest">
+        <Breadcrumbs
+          items={PLACE_TRAIL.slice(0, 1)}
+          label="Link at rest"
+        />
+      </StoryCell>
+
+      <StoryCell label="button · rest">
+        <Breadcrumbs
+          items={[{ label: "Places", onSelect: () => {} }]}
+          label="Button at rest"
+        />
+      </StoryCell>
+
+      <StoryCell label="link · hover (forced)">
+        <div id="hover-link">
+          <Breadcrumbs
+            items={PLACE_TRAIL.slice(0, 1)}
+            label="Link hovered"
+          />
+        </div>
+      </StoryCell>
+
+      <StoryCell label="button · hover (forced)">
+        <div id="hover-button">
+          <Breadcrumbs
+            items={[
+              { label: "Places", onSelect: () => {} },
+            ]}
+            label="Button hovered"
+          />
+        </div>
+      </StoryCell>
+
+      <StoryCell label="link · focus-visible (forced)">
+        <div id="focus-link">
+          <Breadcrumbs
+            items={PLACE_TRAIL.slice(0, 1)}
+            label="Link focused"
+          />
+        </div>
+      </StoryCell>
+
+      <StoryCell label="button · focus-visible (forced)">
+        <div id="focus-button">
+          <Breadcrumbs
+            items={[
+              { label: "Places", onSelect: () => {} },
+            ]}
+            label="Button focused"
+          />
+        </div>
+      </StoryCell>
+
+      <StoryCell label="current page">
+        <Breadcrumbs
+          items={[{ label: "Office Shelves" }]}
+          label="Current only"
+        />
+      </StoryCell>
+
+      <StoryCell label="plain text rung (not last)">
+        <Breadcrumbs
+          items={[
+            { label: "Places" },
+            { href: "/places/office", label: "Office" },
+          ]}
+          label="Text rung"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A trail wraps; it never truncates. The narrow panel breaks the
+ * row between rungs first and then, for the one segment with no
+ * spaces in it, inside the segment — so every word is still there.
+ */
+export const Responsive: Story = {
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <Breadcrumbs
+          items={LONG_TRAIL}
+          label={`Trail at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * The seam: an in-app `href` goes through the injected router, the
+ * same way `TextLink` routes, so a Charcuterie app wired with
+ * `ReactRouterAdapter` gets soft navigation with no extra prop.
+ */
+export const Routed: Story = {
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  args: { items: PLACE_TRAIL.slice(0, -1) },
+}
+
+const FOLDERS = ["G:", "Photos", "2026", "Garden"]
+
+/**
+ * The keyboard path, and the state-driven trail image-viewer and
+ * mux-magic need: Tab walks the rungs in order, Enter or Space climbs
+ * to one, and the current folder is text, so Tab skips it.
+ */
+export const Interactive: Story = {
+  render: () => {
+    const [depth, setDepth] = useState(FOLDERS.length)
+
+    const visible = FOLDERS.slice(0, depth)
+
+    return (
+      <div className="flex flex-col gap-3">
+        <Breadcrumbs
+          items={visible.map((folder, index) => ({
+            key: folder,
+            label: folder,
+            onSelect:
+              index === visible.length - 1
+                ? undefined
+                : () => {
+                    setDepth(index + 1)
+                  },
+          }))}
+          label="Folder trail"
+        />
+
+        <p className="m-0 text-content-secondary text-sm">
+          Showing {visible.join(" / ")}
+        </p>
+      </div>
+    )
+  },
+}

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)
+})