@charcuterie/ui 1.1.0 → 2.0.0

package/src/Dialog/Dialog.tsx

@@ -0,0 +1,127 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Modal } from "../Modal/Modal.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type DialogSize = "full" | "lg" | "md" | "sm" | "xl"
+
+export type DialogProps = {
+  children: ReactNode
+  className?: string
+  /** The footer row. Buttons, usually. */
+  footer?: ReactNode
+  heading: string
+  headingLevel?: 2 | 3 | 4
+  /**
+   * Escape and a backdrop press both close. Off for the one honest
+   * case — a destructive confirm the user has to answer.
+   */
+  isDismissable?: boolean
+  isVisible: boolean
+  /**
+   * Every route out lands here: the close button, Escape, a backdrop
+   * press. Wire it to a `useVisibility()`'s `hide`.
+   */
+  onClose: () => void
+  size?: DialogSize
+}
+
+/**
+ * `85dvh` rather than `85vh` — on a phone the two differ by the
+ * address bar, and a dialog whose footer is under it is a dialog
+ * with no buttons.
+ */
+const SIZE_CLASS: Record<DialogSize, string> = {
+  sm: "max-h-[85dvh] w-full max-w-sm",
+  md: "max-h-[85dvh] w-full max-w-md",
+  lg: "max-h-[85dvh] w-full max-w-2xl",
+  // M5 added this, because the scale jumped from 42rem straight to
+  // the whole viewport and rip-deck's capture tail lands in the
+  // gap: a MakeMKV robot log is fixed-width `MSG:5072,0,1,"…"`
+  // lines that wrap badly at 42rem, and a full-screen dialog over a
+  // nine-bay dashboard hides the thing being diagnosed. 56rem is
+  // what that app's hand-rolled `<dialog>` used before the swap.
+  xl: "max-h-[85dvh] w-full max-w-4xl",
+  full: "h-[100dvh] max-h-[100dvh] w-full max-w-full rounded-none",
+}
+
+/**
+ * `Modal` plus the chrome — heading, a Close button, a scrolling body,
+ * an optional footer, and five sizes. This is what `Modal` *was*
+ * before the M8 rebuild renamed it: a dialog is one kind of modal, so
+ * it takes the specific name and hands the generic one back to the
+ * base layer.
+ *
+ * Everything modal — the portal, the scrim, Escape and outside-press
+ * dismiss, the focus trap, the scroll lock, the stacking — is `Modal`'s
+ * (via `OverlayPanel`), so this component is just the box's contents
+ * and the size class it wants that box to be. `SIZE_CLASS` is composed
+ * over `Modal`'s default surface, which is why `full` carries
+ * `rounded-none` to square off the base's `rounded-lg` at the viewport
+ * edge.
+ *
+ * ### The accessible name
+ *
+ * `heading` is required and is a string, not a `ReactNode`. It names
+ * both the visible header and — through `aria-labelledby` on the
+ * modal — the dialog itself. A dialog with no name is announced as
+ * "dialog" and nothing else, which is what every hand-rolled modal in
+ * the inventory does.
+ */
+export const Dialog = ({
+  children,
+  className,
+  footer,
+  heading,
+  headingLevel = 2,
+  isDismissable = true,
+  isVisible,
+  onClose,
+  size = "md",
+}: DialogProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    <Modal
+      aria-labelledby={headingId}
+      className={toClassName(SIZE_CLASS[size], className)}
+      isDismissable={isDismissable}
+      isVisible={isVisible}
+      onClose={onClose}
+    >
+      <header className="flex shrink-0 items-start justify-between gap-3 border-b border-border-subtle p-4">
+        <Heading
+          className="font-semibold text-lg leading-tight"
+          id={headingId}
+        >
+          {heading}
+        </Heading>
+
+        {isDismissable ? (
+          <Button
+            appearance="ghost"
+            intent="neutral"
+            onClick={onClose}
+            size="sm"
+          >
+            Close
+          </Button>
+        ) : null}
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-auto p-4">
+        {children}
+      </div>
+
+      {footer ? (
+        <footer className="flex shrink-0 flex-wrap justify-end gap-2 border-t border-border-subtle p-4">
+          {footer}
+        </footer>
+      ) : null}
+    </Modal>
+  )
+}

package/src/Field/Field.test.tsx

@@ -180,7 +180,7 @@ test("a slot forwards what an outer slot gave it", async () => {
  * ref and the attribute to have all three arrived.
  */
 test("a slot forwards what an outer slot gave it, in the other order", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Archive path",
@@ -192,8 +192,10 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
   // only have been wired to the `<input>`.
   control.focus()
 
+  // The tip portals to the body now; the `aria-describedby` link still
+  // resolves across the boundary, asserted below.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "Where finished rips are moved.",
     )
   })
@@ -224,7 +226,7 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
  * tip.
  */
 test("a tip is described alongside the field's own text, not instead of it", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Rename pattern",
@@ -237,7 +239,7 @@ test("a tip is described alongside the field's own text, not instead of it", asy
   // tip is missing, and the reason this is testable without a
   // pointer at all.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "A JavaScript regular expression.",
     )
   })

package/src/Lightbox/Lightbox.mdx

@@ -10,10 +10,11 @@ A thumbnail that opens its own full-size view. Three apps hand-roll this — a p
 a still, a scan the operator wants to read — and none get the focus trap or the scroll
 lock right, because the interesting part is not the overlay, it is the dialog underneath.
 
-So a `Lightbox` is a **skin over `Modal`**, not a second dialog. `Modal` owns
-`showModal()`, the top layer, Escape, the `::backdrop` scrim and `lockScrollBehind`;
-this adds 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.
+So a `Lightbox` is a **skin over `Dialog`**, not a second dialog. `Dialog` (through
+`Modal`/`OverlayPanel`) owns the portal, the scrim, Escape, the focus trap and
+`lockScrollBehind`; this adds 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.
 
 <Canvas of={LightboxStories.Default} />
 
@@ -54,9 +55,9 @@ unread; the caller is the one truth.
 ## What it inherits, and does not re-test
 
 Escape, the focus trap, focus restore to the trigger, the scrim and the scroll lock are
-all `Modal`'s, asserted in `Modal`'s own tests. The lightbox's tests assert only the skin:
-that the thumbnail opens the enlarged image, that the caption rides along, and that the
-contract `Modal` guarantees is not quietly dropped by the wrapper — Escape → `onClose`,
-and focus back to the thumbnail.
+all `Dialog`'s (via `Modal`), asserted in their own tests. The lightbox's tests assert only
+the skin: that the thumbnail opens the enlarged image, that the caption rides along, and
+that the contract `Dialog` guarantees is not quietly dropped by the wrapper — Escape →
+`onClose`, and focus back to the thumbnail.
 
 <Canvas of={LightboxStories.Interactive} />

package/src/Lightbox/Lightbox.stories.tsx

@@ -66,8 +66,8 @@ export const WithCaption: Story = {
 
 /**
  * Boards here are a trigger plus one open overlay, not a grid — a
- * lightbox is a `Modal` underneath, and two dialogs in the top layer
- * side by side is not a thing the platform can do.
+ * lightbox is a `Dialog` underneath, and a dialog covers the viewport,
+ * so two side by side is not the real arrangement.
  */
 export const AllStates: Story = {
   render: () => (
@@ -106,8 +106,8 @@ const ControlledDemo = (): ReactNode => {
         alt="THE OUTFIT poster"
         caption="Opened from a button, not the image"
         isOpen={isVisible}
-        onOpenChange={(isOpen) => {
-          if (!isOpen) {
+        onOpenChange={(isNextOpen) => {
+          if (!isNextOpen) {
             hide()
           }
         }}
@@ -122,7 +122,7 @@ export const Controlled: Story = {
 }
 
 /**
- * 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: the trigger opens, Escape routes
  * through `onClose`, and focus returns to the thumbnail button.
  */

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