@charcuterie/ui 4.9.1 → 4.10.0

package/src/ActionMenu/ActionMenu.test.tsx

@@ -0,0 +1,187 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, 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 "./ActionMenu.stories.tsx"
+
+const { AllVariants, Interactive, Playground, Responsive } =
+  composeStories(stories)
+
+test("the trigger is a button named for the thing it acts on", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Actions for Office Shelves",
+    role: "button",
+  })
+
+  await expect(trigger).toHaveAttribute(
+    "aria-haspopup",
+    "menu",
+  )
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("clicking opens a menu named by the trigger, aligned to its end edge", async () => {
+  const { body, canvas } = await mountStory(Playground)
+
+  const trigger = canvas.getByRole("button", {
+    name: "Actions for Office Shelves",
+  })
+
+  await userEvent.click(trigger)
+
+  const menu = await waitFor(() =>
+    expectAgentDrivable(body, {
+      name: "Actions for Office Shelves",
+      role: "menu",
+    }),
+  )
+
+  await expect(trigger).toHaveAttribute(
+    "aria-expanded",
+    "true",
+  )
+
+  // `bottom-end`: the panel hangs from the trigger's end edge, so a
+  // trigger in a row's last column opens inward, not off screen. Not
+  // an exact edge match — this trigger touches the viewport, and
+  // `shift` keeps the panel its padding away from that edge.
+  const triggerBox = trigger.getBoundingClientRect()
+  const menuBox = menu.getBoundingClientRect()
+
+  await expect(menuBox.left).toBeLessThan(triggerBox.left)
+  await expect(menuBox.right).toBeLessThanOrEqual(
+    triggerBox.right + 1,
+  )
+  await expect(menuBox.top).toBeGreaterThanOrEqual(
+    triggerBox.bottom,
+  )
+
+  await expectNoAxeViolations(menu)
+
+  // A second click on the trigger closes it again.
+  await userEvent.click(trigger)
+
+  await waitFor(() => {
+    expect(body.queryAllByRole("menuitem")).toHaveLength(0)
+  })
+})
+
+test("the keyboard opens it, walks it, and closes it", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.tab()
+  await expect(
+    canvas.getByRole("button", {
+      name: "Actions for Office Shelves",
+    }),
+  ).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+
+  await waitFor(() => {
+    expect(
+      body.getByRole("menuitem", { name: "Rename" }),
+    ).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+  await expect(
+    body.getByRole("menuitem", {
+      name: "Move to another place",
+    }),
+  ).toHaveFocus()
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryAllByRole("menuitem")).toHaveLength(0)
+  })
+})
+
+test("choosing an item runs it and closes the menu", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Actions for Office Shelves",
+    }),
+  )
+
+  await userEvent.click(
+    await waitFor(() =>
+      body.getByRole("menuitem", { name: "Rename" }),
+    ),
+  )
+
+  await waitFor(() => {
+    expect(body.queryAllByRole("menuitem")).toHaveLength(0)
+  })
+})
+
+/**
+ * The default dots are three boxes, so they have a size to measure in
+ * a font with no `⋮`. A custom icon replaces them.
+ */
+test("the default dots draw without a font; an icon replaces them", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  const withDots = canvas.getByRole("button", {
+    name: "Actions for shelf md",
+  })
+
+  const dots = withDots.querySelectorAll(
+    "span > span.rounded-full",
+  )
+
+  await expect(dots).toHaveLength(3)
+
+  for (const dot of Array.from<Element>(dots)) {
+    await expect(
+      dot.getBoundingClientRect().width,
+    ).toBeGreaterThan(0)
+  }
+
+  await expect(withDots.querySelector("svg")).toBeNull()
+
+  const withIcon = canvas.getByRole("button", {
+    name: "Actions for bin md",
+  })
+
+  await expect(withIcon.querySelector("svg")).not.toBeNull()
+  await expect(
+    withIcon.querySelectorAll("span.rounded-full"),
+  ).toHaveLength(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the trigger keeps its size beside a wrapping title", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  const narrow: HTMLElement = canvas.getByRole("button", {
+    name: "Actions for Office Shelves at 15rem",
+  })
+
+  const wide: HTMLElement = canvas.getByRole("button", {
+    name: "Actions for Office Shelves at 34rem",
+  })
+
+  await expect(narrow.getBoundingClientRect().width).toBe(
+    wide.getBoundingClientRect().width,
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/ActionMenu/ActionMenu.tsx

@@ -0,0 +1,96 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { IconButton } from "../IconButton/IconButton.tsx"
+import type { MenuEntry } from "../Menu/Menu.tsx"
+import { Menu } from "../Menu/Menu.tsx"
+
+export type ActionMenuProps = {
+  /**
+   * Replaces the default dots. Pass the app's own glyph to match an
+   * icon set exactly — Docket and Whereabouts both use lucide's
+   * `EllipsisVertical` at `strokeWidth={1.75}`.
+   */
+  icon?: ReactNode
+  items: MenuEntry[]
+  /**
+   * The trigger's accessible name, and through it the menu's. Name
+   * the THING, not the gesture: `Actions for Cables`, so a page with
+   * twenty of these has twenty different buttons.
+   */
+  label: string
+  size?: ControlSize
+}
+
+/**
+ * Three dots stacked, drawn as three round boxes sized in `em` so they grow with the trigger's `size`, rather than a `⋮`
+ * character or an SVG. The library ships neither a glyph in a default
+ * — a font without `⋮` paints nothing — nor an icon asset
+ * (`docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md`).
+ * `currentColor` fill, so it takes the trigger's intent and its hover.
+ */
+const DEFAULT_DOTS = (
+  <span
+    aria-hidden="true"
+    className="flex flex-col items-center gap-[0.17em]"
+  >
+    <span className="block size-[0.17em] rounded-full bg-current" />
+    <span className="block size-[0.17em] rounded-full bg-current" />
+    <span className="block size-[0.17em] rounded-full bg-current" />
+  </span>
+)
+
+/**
+ * The overflow control: a thing's secondary actions behind one
+ * labelled vertical-dots button, opening a `Menu` aligned to the
+ * button's end edge.
+ *
+ * Docket's `TaskActionMenu` and Whereabouts' `PlaceActionsMenu` were
+ * the same fifty lines — a ghost neutral `IconButton`, a `useState`
+ * for visibility, `placement="bottom-end"`, a toggle on click and a
+ * close on dismiss. This owns all of it, so the caller hands over
+ * only the actions and a name.
+ *
+ * The open state is internal on purpose: nothing outside the button
+ * has a reason to open it, and choosing an item, Escape and an
+ * outside press already close it through `Menu`'s `onDismiss`.
+ */
+export const ActionMenu = ({
+  icon,
+  items,
+  label,
+  size,
+}: ActionMenuProps): ReactNode => {
+  const [isVisible, setIsVisible] = useState(false)
+
+  return (
+    <Menu
+      isVisible={isVisible}
+      items={items}
+      onDismiss={() => {
+        setIsVisible(false)
+      }}
+      placement="bottom-end"
+      trigger={
+        <IconButton
+          appearance="ghost"
+          // A trigger at the end of a flex row with a long title
+          // beside it is where this lives, and a flex item shrinks by
+          // default — measured at 23px of a 40px button.
+          className="shrink-0"
+          intent="neutral"
+          label={label}
+          onClick={() => {
+            setIsVisible(
+              (isCurrentlyVisible) => !isCurrentlyVisible,
+            )
+          }}
+          size={size}
+        >
+          {icon ?? DEFAULT_DOTS}
+        </IconButton>
+      }
+    />
+  )
+}

package/src/Breadcrumbs/Breadcrumbs.mdx

@@ -0,0 +1,71 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as BreadcrumbsStories from "./Breadcrumbs.stories";
+
+<Meta of={BreadcrumbsStories} />
+
+# Breadcrumbs
+
+A path back up a hierarchy: `Places › Office › Office Shelves`.
+
+Folio, image-viewer and mux-magic each hand-rolled one, and no two agreed on the landmark,
+the list, the current page or what happens to a long name. This is the WAI-ARIA APG
+breadcrumb pattern — a named `<nav>` around an `<ol>` — with the link paint of `TextLink`.
+
+<Canvas of={BreadcrumbsStories.Playground} />
+
+## Props
+
+<Controls />
+
+## What each rung becomes
+
+A rung is read off the fields it carries. The caller says where it goes, never what it is.
+
+| Item | Renders | Use it for |
+| --- | --- | --- |
+| `{ label, href }` | a `TextLink` — a real `<a href>`, routed through `RouterLinkProvider` | a trail over URLs: Folio, Whereabouts |
+| `{ label, onSelect }` | a `<button>` painted as the same link | a trail over state with no URL: image-viewer's folders, mux-magic's file explorer |
+| `{ label }`, last | text with `aria-current="page"` | the current page |
+| `{ label }`, not last | plain text | a level that has no page of its own |
+
+`href` and `onSelect` together render the link and run `onSelect` on click as well.
+
+<Canvas of={BreadcrumbsStories.AllVariants} />
+
+## A trail above a heading has no current rung
+
+When the page already names itself in a heading, the trail stops at the parent and every
+rung is a link. Nothing gets `aria-current`, because the heading is the current page's
+name and it should be announced once.
+
+```tsx
+<Breadcrumbs
+  items={[
+    { href: "/places", label: "Places" },
+    { href: "/places/office", label: "Office" },
+  ]}
+/>
+<h1>Office Shelves</h1>
+```
+
+## It wraps, and it never truncates
+
+A long trail wraps between rungs, and a rung with no spaces breaks inside itself. Nothing
+is cut to `Office Sh…`: the word that would be cut is the one the reader came to find.
+
+<Canvas of={BreadcrumbsStories.Responsive} />
+
+## The separator
+
+The default is a chevron drawn in CSS borders, not a `›` character — the library ships no
+symbol glyphs in a default, because a font that lacks one paints nothing. It points the
+way the trail reads in a right-to-left page too. Pass `separator` to use your own; it is
+always `aria-hidden`.
+
+## Keyboard
+
+Tab walks the rungs in order. Enter follows a link; Enter or Space presses a button rung.
+The current page is text, so Tab skips it.
+
+<Canvas of={BreadcrumbsStories.Interactive} />

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