@charcuterie/ui 1.1.0 → 2.0.1

package/src/Lightbox/Lightbox.test.tsx

@@ -10,23 +10,8 @@ import * as stories from "./Lightbox.stories.tsx"
 const { Controlled, Default, Interactive, WithCaption } =
   composeStories(stories)
 
-/**
- * The close request, dispatched where the browser would raise it.
- * `userEvent`'s Escape is untrusted and a native `<dialog>` runs no
- * default action for it, so — exactly as `Modal`'s tests do — the
- * `cancel` event is dispatched directly, and only the half
- * downstream of it (this component's `onClose`, the effect, the
- * focus restore) is ours to assert.
- */
-const requestClose = (dialog: HTMLElement) => {
-  dialog.dispatchEvent(
-    new Event("cancel", { cancelable: true }),
-  )
-}
-
 test("the thumbnail opens the enlarged image", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(Default)
+  const { body, canvas } = await mountStory(Default)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -35,16 +20,14 @@ test("the thumbnail opens the enlarged image", async () => {
     }),
   )
 
-  const dialog = expectAgentDrivable(canvas, {
+  const dialog = expectAgentDrivable(body, {
     name: "THE OUTFIT poster",
     role: "dialog",
   })
 
-  await expect(dialog).toHaveAttribute("open")
-
   // The enlarged image carries the name — a bare `<img>` in a dialog
   // otherwise announces as nothing.
-  expectAgentDrivable(canvas, {
+  expectAgentDrivable(body, {
     name: "THE OUTFIT poster",
     role: "img",
   })
@@ -52,11 +35,11 @@ test("the thumbnail opens the enlarged image", async () => {
   // The open dialog audits itself: the empty-alt thumbnail, the
   // named trigger and the named enlarged image are the arrangement
   // most likely to trip `button-name` or a duplicate name.
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(dialog)
 })
 
 test("the caption rides along with the enlarged image", async () => {
-  const { canvas } = await mountStory(WithCaption)
+  const { body, canvas } = await mountStory(WithCaption)
 
   await userEvent.click(
     canvas.getByRole("button", {
@@ -65,17 +48,19 @@ test("the caption rides along with the enlarged image", async () => {
   )
 
   await expect(
-    canvas.getByText("2022 · Blu-ray · 1080p"),
+    body.getByText("2022 · Blu-ray · 1080p"),
   ).toBeInTheDocument()
 })
 
 /**
- * The keyboard contract, inherited from `Modal` and asserted here so
+ * The keyboard contract, inherited from `Dialog` and asserted here so
  * the skin cannot quietly drop it — Escape routes through `onClose`,
- * and focus returns to the trigger the platform restored it to.
+ * and focus returns to the trigger `FloatingFocusManager` restored it
+ * to. Escape is a real `userEvent` keypress now, since the overlay is
+ * no longer a native `<dialog>`.
  */
 test("closing restores focus to the thumbnail trigger", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Enlarge THE OUTFIT poster",
@@ -84,19 +69,21 @@ test("closing restores focus to the thumbnail trigger", async () => {
 
   await userEvent.click(trigger)
 
-  const dialog = expectAgentDrivable(canvas, {
+  const dialog = expectAgentDrivable(body, {
     name: "THE OUTFIT poster",
     role: "dialog",
   })
 
-  await expect(dialog).toContainElement(
-    document.activeElement as HTMLElement,
-  )
+  await waitFor(() => {
+    expect(dialog.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
 
-  requestClose(dialog)
+  await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
   })
 
   await expect(document.activeElement).toBe(trigger)
@@ -108,7 +95,7 @@ test("closing restores focus to the thumbnail trigger", async () => {
  * opens it, and closing it flows back through `onOpenChange`.
  */
 test("a controlled lightbox opens from an outside button", async () => {
-  const { canvas } = await mountStory(Controlled)
+  const { body, canvas } = await mountStory(Controlled)
 
   // No built-in trigger: the only "Enlarge …" button a `thumbnail`
   // would have added is absent.
@@ -122,14 +109,16 @@ test("a controlled lightbox opens from an outside button", async () => {
     canvas.getByRole("button", { name: "View the poster" }),
   )
 
-  const dialog = expectAgentDrivable(canvas, {
+  const dialog = expectAgentDrivable(body, {
     name: "THE OUTFIT poster",
     role: "dialog",
   })
 
-  requestClose(dialog)
+  await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
   })
+
+  await expect(dialog).not.toBeInTheDocument()
 })

package/src/Lightbox/Lightbox.tsx

@@ -1,7 +1,7 @@
 import { useVisibility } from "@charcuterie/logic"
 import type { ReactNode } from "react"
 
-import { Modal } from "../Modal/Modal.tsx"
+import { Dialog } from "../Dialog/Dialog.tsx"
 import { toClassName } from "../toClassName.ts"
 
 export type LightboxProps = {
@@ -43,13 +43,13 @@ export type LightboxProps = {
 /**
  * A thumbnail that opens its own full-size view — the one image
  * interaction three apps hand-roll and none get the focus trap or
- * the scroll lock right. It is a **skin over `Modal`**, not a second
- * dialog: `Modal` owns `showModal()`, the top layer, Escape, the
- * `::backdrop` scrim and `lockScrollBehind`, and everything that
- * makes those correct in every browser the fleet runs. What this
- * adds is the image-specific part — a `cursor-zoom-in` trigger and
- * an `object-contain` image clamped to the viewport so a 2:3 poster
- * and a 16:9 still both land whole.
+ * the scroll lock right. It is a **skin over `Dialog`**, not a second
+ * dialog: `Dialog` (through `Modal`/`OverlayPanel`) owns the portal,
+ * the scrim, Escape, the focus trap and `lockScrollBehind`, and
+ * everything that makes those correct in every browser the fleet
+ * runs. What this adds is the image-specific part — a `cursor-zoom-in`
+ * trigger and an `object-contain` image clamped to the viewport so a
+ * 2:3 poster and a 16:9 still both land whole.
  *
  * ### Controlled and not, one component
  *
@@ -115,7 +115,7 @@ export const Lightbox = ({
         </button>
       )}
 
-      <Modal
+      <Dialog
         heading={heading ?? alt}
         isVisible={isShown}
         onClose={requestClose}
@@ -137,7 +137,7 @@ export const Lightbox = ({
             </figcaption>
           ) : null}
         </figure>
-      </Modal>
+      </Dialog>
     </>
   )
 }

package/src/Listbox/Listbox.mdx

@@ -0,0 +1,68 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ListboxStories from "./Listbox.stories";
+
+<Meta of={ListboxStories} />
+
+# Listbox
+
+The single-select **fancy** dropdown — the rich-option sibling of the native
+[`Select`](?path=/docs/components-select--docs), not a replacement for it. `Select` keeps
+type-ahead, Home/End, the mobile wheel picker, form submission, `:invalid` and autofill;
+`Listbox` is for the cases `<option>` cannot render — a leading icon, two lines, a trailing
+badge ([decision](../../../docs/decisions/2026-08-03-listbox-and-combobox-are-siblings-of-select.md)).
+
+<Canvas of={ListboxStories.Default} />
+
+## Props
+
+<Controls />
+
+## A listbox is not a menu
+
+An `option` **is** something you are choosing; a `menuitem` **does** something. So a
+`Listbox` carries `aria-selected`, it type-aheads (the APG requires it of a listbox and
+`Menu` deliberately omits it), and a screen reader announces "listbox, selected, 2 of 4".
+That is the distinction `Menu` documents from the other side.
+
+```tsx
+const { hide, isVisible, toggle } = useVisibility()
+const [value, setValue] = useState<string>()
+
+<Listbox
+  isVisible={isVisible}
+  onDismiss={hide}
+  onSelect={setValue}
+  options={LANGUAGES}
+  selectedValue={value}
+  trigger={<Button onClick={toggle}>{label}</Button>}
+/>
+```
+
+## Two kinds of state, composed
+
+`useRovingFocus` owns which option is tabbable — exactly one, so Tab enters and leaves the
+group once and the arrow keys move within it — and `useSinglePicker` owns which option is
+chosen. They are the same two kinds `Tabs` composes, and they never disturb each other:
+arrowing moves focus without selecting, Enter selects the focused option. A disabled option
+joins the choice but not the focus group, so the arrow keys and type-ahead skip it.
+
+<Canvas of={ListboxStories.AllStates} />
+
+## Rich options, and `textValue`
+
+The options take a `ReactNode` label — two lines, a flag, an intent-coloured confidence
+badge. When the label is rich, `textValue` is required: it is the type-ahead target and the
+name a screen reader reads, so a picture of a value is still a value you can find by typing.
+
+<Canvas of={ListboxStories.AllVariants} />
+
+## Portalled, and a plain button opens it
+
+The panel portals to `document.body`. The trigger stays a native **button** that gains
+`aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls` — the button-opens-listbox
+pattern, not a `combobox` (that is `Combobox`, where focus stays in a text input). So there
+is no `heading` prop; the button names the widget. The panel height is clamped to the
+viewport by floating-ui's `size` middleware and scrolls within it.
+
+<Canvas of={ListboxStories.Interactive} />

package/src/Listbox/Listbox.stories.tsx

@@ -0,0 +1,205 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import { StoryRow } from "../board.storyHelpers.tsx"
+import type { ListboxItem } from "./Listbox.tsx"
+import { Listbox } from "./Listbox.tsx"
+
+const LANGUAGES: ListboxItem[] = [
+  { label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+  { isDisabled: true, label: "German", value: "deu" },
+  { label: "Japanese", value: "jpn" },
+]
+
+/**
+ * The rich options a native `<option>` cannot render — a leading
+ * flag, a two-line detail, a trailing confidence badge — each with a
+ * `textValue` so type-ahead and the accessible name still work.
+ */
+const TRACKS: ListboxItem[] = [
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇬🇧</span>
+        <span className="flex flex-col">
+          <span>English</span>
+          <span className="text-content-muted text-xs">
+            5.1 · forced
+          </span>
+        </span>
+      </span>
+    ),
+    textValue: "English",
+    value: "eng",
+  },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇯🇵</span>
+        <span className="flex flex-col">
+          <span>Japanese</span>
+          <span className="text-content-muted text-xs">
+            2.0 · original
+          </span>
+        </span>
+      </span>
+    ),
+    textValue: "Japanese",
+    value: "jpn",
+  },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span aria-hidden="true">🇫🇷</span>
+        <span>French</span>
+        <Badge intent="warning" size="sm">
+          low confidence
+        </Badge>
+      </span>
+    ),
+    textValue: "French",
+    value: "fra",
+  },
+]
+
+const meta = {
+  title: "Components/Listbox",
+  component: Listbox,
+  parameters: { layout: "padded" },
+  argTypes: { placement: placementArgType },
+  args: { placement: "bottom-start" },
+} satisfies Meta<typeof Listbox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ListboxHarness = ({
+  initialSelected,
+  options,
+  triggerLabel,
+}: {
+  initialSelected?: string
+  options: ListboxItem[]
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  const [selected, setSelected] = useState<
+    string | undefined
+  >(initialSelected)
+
+  const current = options.find(
+    (option) => option.value === selected,
+  )
+
+  const label =
+    current === undefined
+      ? triggerLabel
+      : (current.textValue ??
+        (typeof current.label === "string"
+          ? current.label
+          : triggerLabel))
+
+  return (
+    <Listbox
+      isVisible={isVisible}
+      onDismiss={hide}
+      onSelect={setSelected}
+      options={options}
+      selectedValue={selected}
+      trigger={
+        <Button appearance="outline" onClick={toggle}>
+          {label}
+        </Button>
+      }
+    />
+  )
+}
+
+export const Default: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}
+
+/**
+ * A disabled option stays in the list and stays announced — it joins
+ * the choice but not the focus group, so the arrow keys and type-ahead
+ * skip it. `Spanish` is seeded as the current value.
+ */
+export const AllStates: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      initialSelected="spa"
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}
+
+/**
+ * The thing a native `<select>` cannot do: two-line options, a leading
+ * flag, and a trailing intent-coloured badge.
+ */
+export const AllVariants: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: TRACKS,
+    trigger: <Button>Choose a track</Button>,
+  },
+  render: () => (
+    <StoryRow>
+      <ListboxHarness
+        options={TRACKS}
+        triggerLabel="Choose a track"
+      />
+    </StoryRow>
+  ),
+}
+
+/**
+ * Open it and drive it from the keyboard: arrows move focus without
+ * selecting, type a letter to jump, Enter chooses, Escape closes.
+ */
+export const Interactive: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Choose a language</Button>,
+  },
+  render: () => (
+    <ListboxHarness
+      options={LANGUAGES}
+      triggerLabel="Choose a language"
+    />
+  ),
+}

package/src/Listbox/Listbox.test.tsx

@@ -0,0 +1,198 @@
+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 "./Listbox.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("a button opens a listbox whose rows are options", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Choose a language",
+    role: "button",
+  })
+
+  // The trigger stays a native button that *opens* a listbox — it is
+  // not a `combobox`. It gains `aria-haspopup="listbox"`.
+  await expect(trigger).toHaveAttribute(
+    "aria-haspopup",
+    "listbox",
+  )
+
+  await userEvent.click(trigger)
+
+  const listbox = expectAgentDrivable(body, {
+    role: "listbox",
+  })
+
+  // `option`, not `menuitem` — a value being chosen, so it carries
+  // `aria-selected`.
+  const english = expectAgentDrivable(body, {
+    name: "English",
+    role: "option",
+  })
+
+  await expect(english).toHaveAttribute(
+    "aria-selected",
+    "false",
+  )
+
+  await expectNoAxeViolations(listbox)
+})
+
+test("opening focuses the seeded selection, which reads selected", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  // The trigger reflects the seeded value.
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Spanish",
+      role: "button",
+    }),
+  )
+
+  const spanish = expectAgentDrivable(body, {
+    name: "Spanish",
+    role: "option",
+  })
+
+  await expect(spanish).toHaveAttribute(
+    "aria-selected",
+    "true",
+  )
+
+  // The APG rule: a listbox opens on its current value.
+  await waitFor(() => {
+    expect(spanish).toHaveFocus()
+  })
+})
+
+test("the arrow keys move focus and skip the disabled option", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const english = expectAgentDrivable(body, {
+    name: "English",
+    role: "option",
+  })
+
+  const japanese = expectAgentDrivable(body, {
+    name: "Japanese",
+    role: "option",
+  })
+
+  await expect(
+    expectAgentDrivable(body, {
+      name: "German",
+      role: "option",
+    }),
+  ).toBeDisabled()
+
+  await waitFor(() => {
+    expect(english).toHaveFocus()
+  })
+
+  // English → Spanish → French → Japanese, skipping the disabled
+  // German, which never joined the focus group.
+  await userEvent.keyboard(
+    "{ArrowDown}{ArrowDown}{ArrowDown}",
+  )
+
+  await waitFor(() => {
+    expect(japanese).toHaveFocus()
+  })
+})
+
+test("type-ahead jumps to the first match", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const japanese = expectAgentDrivable(body, {
+    name: "Japanese",
+    role: "option",
+  })
+
+  await userEvent.keyboard("j")
+
+  await waitFor(() => {
+    expect(japanese).toHaveFocus()
+  })
+})
+
+test("Enter selects the focused option and closes", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  // English is first and focused; arrow to Spanish and choose it.
+  await userEvent.keyboard("{ArrowDown}{Enter}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("listbox")).toBeNull()
+  })
+
+  // Choosing flows back through `onSelect`, so the trigger now reads
+  // the chosen value.
+  expectAgentDrivable(canvas, {
+    name: "Spanish",
+    role: "button",
+  })
+})
+
+test("Escape dismisses without choosing, and there is one tab stop", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Choose a language",
+      role: "button",
+    }),
+  )
+
+  const listbox = expectAgentDrivable(body, {
+    role: "listbox",
+  })
+
+  const tabbable = Array.from(
+    listbox.querySelectorAll<HTMLButtonElement>(
+      '[role="option"]',
+    ),
+  ).filter((one) => one.tabIndex === 0)
+
+  await expect(tabbable).toHaveLength(1)
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("listbox")).toBeNull()
+  })
+
+  // Unchanged trigger — nothing was chosen.
+  expectAgentDrivable(canvas, {
+    name: "Choose a language",
+    role: "button",
+  })
+})