@charcuterie/ui 0.1.1 → 1.0.0

package/src/Menu/Menu.mdx

@@ -0,0 +1,103 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MenuStories from "./Menu.stories";
+
+<Meta of={MenuStories} />
+
+# Menu
+
+A menu is **not** a listbox, and mux-magic's `TypePicker` is the fleet's one attempt at
+telling them apart — it renders `role="menu"` over items that set a value, which is a
+listbox wearing the wrong role.
+
+<Canvas of={MenuStories.Default} />
+
+## Props
+
+<Controls />
+
+## `menuitem` versus `option`
+
+| | `menuitem` | `option` |
+| --- | --- | --- |
+| What it is | an **action** — Retry, Skip, Eject | a **value** you are choosing |
+| Announced as | "menu, 3 items" | "listbox, selected, 2 of 4" |
+| Leaves state behind | no | yes |
+| Lives in | this component | `Select` |
+
+The last row is why it matters to an agent driving the app: after choosing an `option` it
+needs to know what the control now holds. After invoking a `menuitem` there is nothing to
+read back. Getting the role wrong is invisible in a browser and invisible to axe.
+
+## A `[popover]` that was never shown is `display: none`
+
+The panel calls `showPopover()` from its ref callback, like `Popover` does — plus an
+`isConnected` guard and an effect that `Popover` does not need.
+
+`FloatingFocusManager` renders a pair of focus guards around its child, so React commits this
+subtree in an order where the ref can fire while the node is still **detached**.
+`showPopover()` on a disconnected element throws `InvalidStateError`, which surfaces as an
+unhandled rejection rather than a failing assertion — and if it is simply swallowed, the menu
+renders, typechecks, and is invisible to `getByRole` and to a user alike.
+
+The effect is the backstop, because effects run after the tree is connected. Both are
+idempotent: `:popover-open` is the same question.
+
+## There is no `label` prop, and that corrects a lesson
+
+`Spinner` (M3), `Popover` and `Modal` (M4) all take a **required** name, because a
+`role="status"` and a `role="dialog"` take none from their content. The obvious move here was
+a `label` prop doing the same job — it was written that way first, and then measured as
+doing **nothing**.
+
+`useRole(context, { role: "menu" })` puts `aria-labelledby` on the panel pointing at the
+trigger, and `aria-labelledby` beats `aria-label`. The menu was already named "Bay 3", from
+the button, and the prop was silently discarded. That is also the APG menu-button pattern.
+
+So the rule the other three teach is narrower than it looked:
+
+> An overlay with **no trigger relationship** needs its own name.
+
+A menu has one, so the requirement moves to the trigger — which `Button` and `IconButton`
+already enforce.
+
+## One kind, and that is the other half of the `Tabs` argument
+
+`Tabs` needed **two** state kinds because a tab is chosen *and* focused, and in `manual`
+activation those two disagree on purpose. A menu needs **one** — `RovingFocus` — because a
+menu item is never selected, only invoked.
+
+Two components, opposite conclusions, same model. That is the composition claim being paid
+off rather than asserted.
+
+<Canvas of={MenuStories.AllVariants} />
+
+## Focus moves in, once
+
+A menu is one of the few patterns where focus must jump on open, or the keyboard user who
+pressed Enter is still on the trigger with a menu they cannot reach.
+
+It happens in the panel's own effect rather than through `FloatingFocusManager`'s
+`initialFocus`, because the element to focus is whichever one `RovingFocus` says is active —
+and that is not known until the items have registered. `initialFocus={-1}` turns the
+manager's own aim off, so there is one owner for the caret.
+
+`modal={false}`, so Tab **leaves** the menu and lands on the next control in the page, which
+is what closes it. A trapped menu is a dialog.
+
+<Canvas of={MenuStories.AllStates} />
+
+## Registration is membership
+
+A disabled item never registers with the roving group, so the arrow keys skip it with
+nothing in `RovingFocus` knowing what "disabled" means. It stays in the DOM and stays
+announced — "not right now", rather than "does not exist".
+
+## No type-ahead, deliberately
+
+The APG lists type-ahead as **optional** for a menu and **required** for a listbox, and none
+of the fleet's menus are long enough to need it — the largest has six items. Adding it means
+a keystroke buffer and a timer in a component that has neither, for a menu you can cross in
+three arrow presses.
+
+<Canvas of={MenuStories.Interactive} />

package/src/Menu/Menu.stories.tsx

@@ -0,0 +1,161 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import {
+  RedoIcon,
+  SettingsIcon,
+  UndoIcon,
+} from "../icons.storyHelpers.tsx"
+import type { MenuItem } from "./Menu.tsx"
+import { Menu } from "./Menu.tsx"
+
+const noop = () => undefined
+
+const BAY_ACTIONS: MenuItem[] = [
+  {
+    icon: <UndoIcon />,
+    key: "retry",
+    label: "Retry title",
+    onSelect: noop,
+  },
+  {
+    icon: <RedoIcon />,
+    key: "skip",
+    label: "Skip title",
+    onSelect: noop,
+  },
+  {
+    icon: <SettingsIcon />,
+    isDisabled: true,
+    key: "eject",
+    label: "Eject disc",
+    onSelect: noop,
+  },
+]
+
+/**
+ * A menu's visibility belongs to the app, exactly like `Popover`'s —
+ * so the stories hold it in a `useVisibility`, which is what a
+ * consumer writes too.
+ */
+const MenuHarness = ({
+  isInitiallyVisible = false,
+  items = BAY_ACTIONS,
+  triggerLabel,
+}: {
+  isInitiallyVisible?: boolean
+  items?: MenuItem[]
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isInitiallyVisible,
+  })
+
+  return (
+    <Menu
+      isVisible={isVisible}
+      items={items}
+      onDismiss={hide}
+      trigger={
+        <Button appearance="outline" onClick={toggle}>
+          {triggerLabel}
+        </Button>
+      }
+    />
+  )
+}
+
+const meta = {
+  title: "Components/Menu",
+  component: Menu,
+  parameters: { layout: "centered" },
+  argTypes: { placement: placementArgType },
+  args: {
+    items: BAY_ACTIONS,
+    placement: "bottom-start",
+  },
+} satisfies Meta<typeof Menu>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => <MenuHarness triggerLabel="Actions" />,
+}
+
+/**
+ * A `menuitem` **does** something; an `option` **is** something. A
+ * screen reader announces "menu, 3 items" for one and "listbox,
+ * selected, 2 of 4" for the other, and mux-magic's `TypePicker`
+ * renders `role="menu"` over items that set a value — a listbox
+ * wearing the wrong role.
+ */
+export const AllVariants: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="closed">
+        <MenuHarness triggerLabel="Bay 1" />
+      </StoryCell>
+
+      <StoryCell label="open">
+        <MenuHarness
+          isInitiallyVisible
+          triggerLabel="Bay 2"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A disabled item is simply **not registered** with the roving
+ * group, so the arrow keys skip it without any command in
+ * `RovingFocus` knowing what "disabled" means. It stays in the DOM
+ * and stays announced — the difference between "not right now" and
+ * "does not exist".
+ */
+export const AllStates: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    <MenuHarness isInitiallyVisible triggerLabel="Bay 3" />
+  ),
+}
+
+/**
+ * Open it and arrow down. Focus lands on the first item **on
+ * opening** — a menu that leaves the caret on the trigger is one a
+ * keyboard user cannot reach — and Escape closes it without the
+ * page moving.
+ */
+export const Interactive: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    <MenuHarness triggerLabel="Open bay 4 menu" />
+  ),
+}

package/src/Menu/Menu.test.tsx

@@ -0,0 +1,202 @@
+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 "./Menu.stories.tsx"
+
+const { AllStates, AllVariants, Interactive } =
+  composeStories(stories)
+
+test("the menu is named, and its items are menuitems", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  // **Named by its trigger**, not by a `label` prop. `useRole` puts
+  // `aria-labelledby` on the panel pointing at the button, and
+  // `aria-labelledby` beats `aria-label` — so the `label` prop this
+  // component was first written with did nothing at all, silently.
+  //
+  // That narrows the M3/M4 lesson rather than contradicting it: an
+  // overlay with **no trigger relationship** (`Spinner`'s
+  // `role="status"`, `Popover`'s `role="dialog"`) needs its own
+  // name. A menu has one.
+  expectAgentDrivable(canvas, {
+    name: "Bay 3",
+    role: "menu",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: "Retry title",
+    role: "menuitem",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * A menu is one of the few patterns where focus must jump on open —
+ * otherwise the keyboard user who pressed Enter on the trigger is
+ * still on the trigger, with a menu they cannot reach.
+ */
+test("opening moves focus into the menu", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open bay 4 menu",
+      role: "button",
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      expectAgentDrivable(canvas, {
+        name: "Retry title",
+        role: "menuitem",
+      }),
+    ).toHaveFocus()
+  })
+})
+
+test("the arrow keys move within the menu and skip the disabled item", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const skip = expectAgentDrivable(canvas, {
+    name: "Skip title",
+    role: "menuitem",
+  })
+
+  const eject = expectAgentDrivable(canvas, {
+    name: "Eject disc",
+    role: "menuitem",
+  })
+
+  await expect(eject).toBeDisabled()
+
+  // Not a click to get started — **choosing dismisses the menu**, so
+  // clicking an item to "focus" it closes the thing under test. This
+  // story opens already visible, and opening is what puts focus on
+  // the first item.
+  const retry = expectAgentDrivable(canvas, {
+    name: "Retry title",
+    role: "menuitem",
+  })
+
+  await waitFor(() => {
+    expect(retry).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(skip).toHaveFocus()
+  })
+
+  // Registration is membership: the disabled item never joined the
+  // roving group, so wrapping goes past it back to the first.
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(retry).toHaveFocus()
+  })
+
+  await expect(eject).not.toHaveFocus()
+})
+
+/**
+ * Exactly one tab stop for the whole menu — the roving-tabindex
+ * rule, read straight from `selectTabIndex`. `expectAgentDrivable`
+ * asserts it for every composite member it is handed; this states it
+ * outright because a menu's members all carry `tabindex="-1"` and
+ * that is the pattern, not a bug.
+ */
+test("the menu has one tab stop", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const menu = expectAgentDrivable(canvas, {
+    name: "Bay 3",
+    role: "menu",
+  })
+
+  const tabbable = Array.from(
+    menu.querySelectorAll<HTMLButtonElement>(
+      '[role="menuitem"]',
+    ),
+  ).filter((one) => one.tabIndex === 0)
+
+  await expect(tabbable).toHaveLength(1)
+})
+
+test("choosing an item dismisses the menu", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open bay 4 menu",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Retry title",
+      role: "menuitem",
+    }),
+  )
+
+  // A menu that stays open after an action has fired is the one
+  // interaction users read as "it didn't work".
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("menuitem")).toHaveLength(
+      0,
+    )
+  })
+})
+
+test("Escape dismisses without choosing", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open bay 4 menu",
+      role: "button",
+    }),
+  )
+
+  await waitFor(() => {
+    expect(
+      canvas.queryAllByRole("menuitem").length,
+    ).toBeGreaterThan(0)
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("menuitem")).toHaveLength(
+      0,
+    )
+  })
+})
+
+/**
+ * The panel is in the top layer via `popover="manual"` and **stays
+ * in the DOM where it was written** — so a scoped query still finds
+ * it. A portalled menu would move to `document.body` and every story
+ * here would have to reach for `screen`.
+ */
+test("the menu is not portalled out of its canvas", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  const menu = expectAgentDrivable(canvas, {
+    name: "Bay 2",
+    role: "menu",
+  })
+
+  await expect(canvasElement).toContainElement(menu)
+
+  await expectNoAxeViolations(canvasElement)
+})