@charcuterie/ui 4.9.0 → 4.10.0

package/src/ActionMenu/ActionMenu.stories.tsx

@@ -0,0 +1,183 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import {
+  MoreIcon,
+  RedoIcon,
+  SettingsIcon,
+  UndoIcon,
+} from "../icons.storyHelpers.tsx"
+import type { MenuEntry } from "../Menu/Menu.tsx"
+import { ActionMenu } from "./ActionMenu.tsx"
+
+const noop = () => undefined
+
+const SHELF_ACTIONS: MenuEntry[] = [
+  {
+    icon: <UndoIcon />,
+    key: "rename",
+    label: "Rename",
+    onSelect: noop,
+  },
+  {
+    icon: <RedoIcon />,
+    key: "move",
+    label: "Move to another place",
+    onSelect: noop,
+  },
+  { key: "divider", type: "separator" },
+  {
+    icon: <SettingsIcon />,
+    isDisabled: true,
+    key: "archive",
+    label: "Archive",
+    onSelect: noop,
+  },
+]
+
+const meta = {
+  title: "Components/Actions/ActionMenu",
+  component: ActionMenu,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  args: {
+    items: SHELF_ACTIONS,
+    label: "Actions for Office Shelves",
+    size: "md",
+  },
+} satisfies Meta<typeof ActionMenu>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * At the end of its row, where it lives: the panel opens at
+ * `bottom-end`, so its end edge lines up with the button's and it
+ * opens inward.
+ */
+export const Playground: Story = {
+  parameters: playgroundParameters,
+  render: (actionMenuProps) => (
+    <div className="flex justify-end">
+      <ActionMenu {...actionMenuProps} />
+    </div>
+  ),
+}
+
+/**
+ * The default dots against an app's own glyph, at every size. The
+ * dots are three round boxes, not a `⋮` and not an SVG, so they draw
+ * in a font that has no such character.
+ */
+export const AllVariants: Story = {
+  render: (actionMenuProps) => (
+    <StorySection title="Default dots or the app's own icon, at sm, md and lg. Every trigger names the thing it acts on.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell key={size} label={`size=${size}`}>
+            <ActionMenu
+              {...actionMenuProps}
+              label={`Actions for shelf ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell
+            key={`icon-${size}`}
+            label={`icon={<MoreIcon />} size=${size}`}
+          >
+            <ActionMenu
+              {...actionMenuProps}
+              icon={<MoreIcon />}
+              label={`Actions for bin ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Rest, hover and focus on the trigger. The open state is `Menu`'s
+ * own board; this component adds nothing to the panel.
+ */
+export const AllStates: Story = {
+  parameters: {
+    pseudo: {
+      focusVisible: ["#focus-target button"],
+      hover: ["#hover-target button"],
+    },
+  },
+  render: (actionMenuProps) => (
+    <StoryGrid columns={3}>
+      <StoryCell label="rest">
+        <ActionMenu
+          {...actionMenuProps}
+          label="Actions for Cables"
+        />
+      </StoryCell>
+
+      <StoryCell label="hover (forced)">
+        <div id="hover-target">
+          <ActionMenu
+            {...actionMenuProps}
+            label="Actions for Adapters"
+          />
+        </div>
+      </StoryCell>
+
+      <StoryCell label="focus-visible (forced)">
+        <div id="focus-target">
+          <ActionMenu
+            {...actionMenuProps}
+            label="Actions for Chargers"
+          />
+        </div>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Where it lives: at the end of a card's header row. The title wraps
+ * and the trigger keeps its size, at every container width.
+ */
+export const Responsive: Story = {
+  render: (actionMenuProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <Card>
+          <div className="flex items-start justify-between gap-2">
+            <h3 className="m-0 min-w-0 font-semibold text-content-primary text-md wrap-anywhere">
+              Office Shelves, the tall unit by the window
+            </h3>
+            <ActionMenu
+              {...actionMenuProps}
+              label={`Actions for Office Shelves at ${width}`}
+            />
+          </div>
+        </Card>
+      )}
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * Enter or Space opens it and focus moves to the first item; the
+ * arrows walk the items and skip the disabled one; choosing an item
+ * or pressing Escape closes it.
+ */
+export const Interactive: Story = {}

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} />