@charcuterie/ui 1.1.0 → 2.0.1

package/src/Listbox/Listbox.tsx

@@ -0,0 +1,295 @@
+import {
+  selectTabIndex,
+  useRovingFocus,
+  useSinglePicker,
+} from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  FloatingFocusManager,
+  FloatingPortal,
+} from "@floating-ui/react"
+import type { ReactElement, ReactNode } from "react"
+import { useEffect, useRef } from "react"
+
+import { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
+import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
+import { toClassName } from "../toClassName.ts"
+import { ListboxOption } from "./ListboxOption.tsx"
+
+export type ListboxItem = {
+  isDisabled?: boolean
+  label: ReactNode
+  /**
+   * Required when `label` is rich (an icon, two lines, a badge): it is
+   * the type-ahead target and the accessible name a screen reader
+   * reads. When `label` is a plain string it is used as the fallback.
+   */
+  textValue?: string
+  value: string
+}
+
+export type ListboxProps = {
+  className?: string
+  isVisible: boolean
+  /** Outside press and Escape both land here. */
+  onDismiss: () => void
+  onSelect: (value: string) => void
+  options: readonly ListboxItem[]
+  placement?: Placement
+  /** The initial seed. The live selection is the listbox's after that. */
+  selectedValue?: string
+  /** The control the listbox hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+const getOptionText = (item: ListboxItem) =>
+  (
+    item.textValue ??
+    (typeof item.label === "string" ? item.label : "")
+  ).toLowerCase()
+
+/**
+ * The single-select fancy dropdown — the rich-option sibling of the
+ * native `Select`. `Select` keeps type-ahead, the mobile wheel, form
+ * submission and autofill; `Listbox` is for the cases `<option>`
+ * cannot render: an icon, two lines, a trailing badge.
+ *
+ * A listbox is **not** a menu, and that distinction is the whole
+ * reason it is a separate component from `Menu`. An `option` *is*
+ * something you are choosing — so it carries `aria-selected`, it
+ * type-aheads (which the APG requires of a listbox and `Menu`
+ * deliberately omits), and a screen reader announces "listbox,
+ * selected, 2 of 4". A `menuitem` only ever *does* something.
+ *
+ * ### 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.
+ *
+ * ### Portalled, and named by its trigger
+ *
+ * Like `Menu`, the panel portals to `document.body` and `useRole` names
+ * it by pointing `aria-labelledby` at the trigger — so there is no
+ * `heading` prop; the button that opens it is its label.
+ */
+export const Listbox = ({
+  className,
+  isVisible,
+  onDismiss,
+  onSelect,
+  options,
+  placement = "bottom-start",
+  selectedValue,
+  trigger,
+}: ListboxProps): ReactNode => {
+  const optionElements = useRef(
+    new Map<string, HTMLButtonElement>(),
+  )
+
+  const typeahead = useRef({ buffer: "", stampMs: 0 })
+
+  const focus = useRovingFocus<string>()
+
+  const picker = useSinglePicker<string>({ selectedValue })
+
+  const { activeValue, registeredValues, setActiveValue } =
+    focus
+
+  const [firstValue] = registeredValues
+
+  const {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating,
+    triggerId,
+  } = useAnchoredOverlay({
+    isVisible,
+    maxHeightPx: 384,
+    offsetValue: 4,
+    onDismiss,
+    placement,
+    role: "listbox",
+    trigger,
+  })
+
+  const chooseValue = (value: string) => {
+    picker.select(value)
+
+    onSelect(value)
+
+    // A single choice closes, the way the native `<select>` it stands
+    // in for does — the consumer's `onDismiss` is the same one an
+    // outside press and Escape use.
+    onDismiss()
+  }
+
+  /**
+   * Opening lands the focus on the chosen option, or the first when
+   * nothing is chosen yet — the APG rule for a listbox, and the reason
+   * a reopened one resumes on the current value rather than the top.
+   */
+  useEffect(() => {
+    if (!isVisible) {
+      return
+    }
+
+    const seed = picker.selectedValue ?? firstValue
+
+    if (seed !== undefined && seed !== null) {
+      setActiveValue(seed)
+    }
+  }, [
+    firstValue,
+    isVisible,
+    picker.selectedValue,
+    setActiveValue,
+  ])
+
+  useEffect(() => {
+    if (!isVisible || activeValue === null) {
+      return
+    }
+
+    optionElements.current.get(activeValue)?.focus()
+  }, [activeValue, isVisible])
+
+  const runTypeahead = (character: string) => {
+    // Reset the buffer once the typing pauses, so "sk" then a beat
+    // then "e" is two searches rather than "ske".
+    const now = Date.now()
+
+    typeahead.current.buffer =
+      now - typeahead.current.stampMs > 500
+        ? character
+        : typeahead.current.buffer + character
+
+    typeahead.current.stampMs = now
+
+    const query = typeahead.current.buffer.toLowerCase()
+
+    const match = options.find(
+      (option) =>
+        !option.isDisabled &&
+        getOptionText(option).startsWith(query),
+    )
+
+    if (match) {
+      setActiveValue(match.value)
+    }
+  }
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <FloatingPortal>
+          <FloatingFocusManager
+            context={context}
+            initialFocus={-1}
+            modal={false}
+          >
+            <div
+              {...getFloatingProps()}
+              // A bare `role="listbox"` is an ARIA input field and must
+              // be named; pointing at the trigger across the portal is
+              // the same link `useRole` makes for a `Menu`.
+              aria-labelledby={triggerId}
+              className={toClassName(
+                PANEL_SURFACE_CLASS,
+                // The height is clamped to the viewport by the `size`
+                // middleware (`maxHeightPx`), written as an inline
+                // style; this scrolls within it.
+                "z-[var(--layer-modal)] flex min-w-48 flex-col gap-0.5 overflow-auto p-1",
+                className,
+              )}
+              onKeyDown={(keyEvent) => {
+                const commands: Record<string, () => void> =
+                  {
+                    ArrowDown: focus.next,
+                    ArrowUp: focus.previous,
+                    End: focus.last,
+                    Home: focus.first,
+                  }
+
+                const command = commands[keyEvent.key]
+
+                if (command) {
+                  keyEvent.preventDefault()
+
+                  command()
+
+                  return
+                }
+
+                if (
+                  (keyEvent.key === "Enter" ||
+                    keyEvent.key === " ") &&
+                  activeValue !== null
+                ) {
+                  keyEvent.preventDefault()
+
+                  chooseValue(activeValue)
+
+                  return
+                }
+
+                // Type-ahead: a single printable character with no
+                // modifier is a search, not a shortcut.
+                if (
+                  keyEvent.key.length === 1 &&
+                  !keyEvent.altKey &&
+                  !keyEvent.ctrlKey &&
+                  !keyEvent.metaKey
+                ) {
+                  runTypeahead(keyEvent.key)
+                }
+              }}
+              ref={setFloating}
+              // Duplicated from `getFloatingProps()` on purpose, and
+              // the two cannot differ — `useRole(context, { role:
+              // "listbox" })` in the hook is where it comes from.
+              // Stated here because a linter cannot see a role through
+              // a spread.
+              role="listbox"
+              style={floatingStyles}
+            >
+              {options.map((option) => (
+                <ListboxOption
+                  isSelected={
+                    picker.selectedValue === option.value
+                  }
+                  item={option}
+                  key={option.value}
+                  onSelect={chooseValue}
+                  registerFocus={focus.register}
+                  registerSelection={picker.register}
+                  tabIndex={selectTabIndex(
+                    focus,
+                    option.value,
+                  )}
+                  trackElement={(value, element) => {
+                    if (element) {
+                      optionElements.current.set(
+                        value,
+                        element,
+                      )
+                    } else {
+                      optionElements.current.delete(value)
+                    }
+                  }}
+                />
+              ))}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
+      ) : null}
+    </>
+  )
+}

package/src/Listbox/ListboxOption.tsx

@@ -0,0 +1,104 @@
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { ListboxItem } from "./Listbox.tsx"
+
+export type ListboxOptionProps = {
+  isSelected: boolean
+  item: ListboxItem
+  onSelect: (value: string) => void
+  /** `RovingFocus.register` — membership of the arrow-key group. */
+  registerFocus: (value: string) => () => void
+  /** `SinglePicker.register` — membership of the choice. */
+  registerSelection: (value: string) => () => void
+  tabIndex: number
+  trackElement: (
+    value: string,
+    element: HTMLButtonElement | null,
+  ) => void
+}
+
+/**
+ * Its own file for the same reason as `MenuAction` and `TabTrigger`:
+ * **both registrations are effects**, and an effect cannot run in a
+ * loop.
+ *
+ * The two registrations are separate on purpose, exactly as
+ * `TabTrigger` splits them. A disabled option joins the *choice* — it
+ * can still be the seeded `selectedValue` and still announces
+ * `aria-selected` — and stays out of the *focus* group, so the arrow
+ * keys and type-ahead skip it without `RovingFocus` having to know
+ * what "disabled" means.
+ *
+ * ### `option`, not `menuitem`
+ *
+ * An `option` **is** something — the value being chosen — where a
+ * `menuitem` **does** something. So this carries `aria-selected`
+ * (which a menuitem must not), and a screen reader announces
+ * "listbox, selected, 2 of 4" rather than "menu, 4 items". It is a
+ * `<button>` with `role="option"` so it is natively focusable for the
+ * roving-tabindex move, the same shape `Menu` uses.
+ */
+export const ListboxOption = ({
+  isSelected,
+  item,
+  onSelect,
+  registerFocus,
+  registerSelection,
+  tabIndex,
+  trackElement,
+}: ListboxOptionProps): ReactNode => {
+  const { isDisabled = false, label, value } = item
+
+  useEffect(
+    () => registerSelection(value),
+    [registerSelection, value],
+  )
+
+  useEffect(() => {
+    if (isDisabled) {
+      return
+    }
+
+    return registerFocus(value)
+  }, [isDisabled, registerFocus, value])
+
+  return (
+    <button
+      aria-selected={isSelected}
+      className={toClassName(
+        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm bg-transparent px-2 py-1.5 text-start text-content-primary text-sm transition-colors duration-(--duration-fast) ease-standard",
+        "hover:bg-intent-neutral-surface",
+        isSelected && "bg-intent-accent-surface",
+        isDisabled &&
+          "cursor-not-allowed text-content-disabled hover:bg-transparent",
+        FOCUS_RING_CLASS,
+      )}
+      disabled={isDisabled}
+      onClick={() => {
+        onSelect(value)
+      }}
+      ref={(element) => {
+        trackElement(value, element)
+      }}
+      role="option"
+      tabIndex={tabIndex}
+      type="button"
+    >
+      {label}
+
+      {isSelected ? (
+        <span
+          // Decoration: the announced state is `aria-selected`, so the
+          // check must not also read out.
+          aria-hidden="true"
+          className="shrink-0 text-intent-accent-content"
+        >
+          ✓
+        </span>
+      ) : null}
+    </button>
+  )
+}

package/src/Menu/Menu.mdx

@@ -29,19 +29,17 @@ The last row is why it matters to an agent driving the app: after choosing an `o
 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.
+## Portalled, and no `[popover]` machinery
+
+The panel renders in a `FloatingPortal` at `document.body`, through the same
+`useAnchoredOverlay` `Popover` uses
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)).
+A portalled node is visible when mounted, so the whole `popover="manual"` /
+`showPopover()` / `isConnected`-guard class of "a `[popover]` that was never shown is
+`display: none`" bug is simply gone. The menu keeps its roving focus, its arrow/Home/End
+keymap, its seed-first-item-on-open effect, and its `MenuAction` items. A scoped query for
+the panel now reaches for `body`; `useRole` names it by pointing `aria-labelledby` at the
+trigger, so the link survives the boundary.
 
 ## There is no `label` prop, and that corrects a lesson
 

package/src/Menu/Menu.test.tsx

@@ -15,8 +15,7 @@ const {
 } = composeStories(stories)
 
 test("the menu is named, and its items are menuitems", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(AllStates)
+  const { body } = await mountStory(AllStates)
 
   // **Named by its trigger**, not by a `label` prop. `useRole` puts
   // `aria-labelledby` on the panel pointing at the button, and
@@ -27,17 +26,17 @@ test("the menu is named, and its items are menuitems", async () => {
   // overlay with **no trigger relationship** (`Spinner`'s
   // `role="status"`, `Popover`'s `role="dialog"`) needs its own
   // name. A menu has one.
-  expectAgentDrivable(canvas, {
+  const menu = expectAgentDrivable(body, {
     name: "Bay 3",
     role: "menu",
   })
 
-  expectAgentDrivable(canvas, {
+  expectAgentDrivable(body, {
     name: "Retry title",
     role: "menuitem",
   })
 
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(menu)
 })
 
 /**
@@ -46,7 +45,7 @@ test("the menu is named, and its items are menuitems", async () => {
  * still on the trigger, with a menu they cannot reach.
  */
 test("opening moves focus into the menu", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -57,7 +56,7 @@ test("opening moves focus into the menu", async () => {
 
   await waitFor(() => {
     expect(
-      expectAgentDrivable(canvas, {
+      expectAgentDrivable(body, {
         name: "Retry title",
         role: "menuitem",
       }),
@@ -66,14 +65,14 @@ test("opening moves focus into the menu", async () => {
 })
 
 test("the arrow keys move within the menu and skip the disabled item", async () => {
-  const { canvas } = await mountStory(AllStates)
+  const { body } = await mountStory(AllStates)
 
-  const skip = expectAgentDrivable(canvas, {
+  const skip = expectAgentDrivable(body, {
     name: "Skip title",
     role: "menuitem",
   })
 
-  const eject = expectAgentDrivable(canvas, {
+  const eject = expectAgentDrivable(body, {
     name: "Eject disc",
     role: "menuitem",
   })
@@ -84,7 +83,7 @@ test("the arrow keys move within the menu and skip the disabled item", async ()
   // 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, {
+  const retry = expectAgentDrivable(body, {
     name: "Retry title",
     role: "menuitem",
   })
@@ -118,9 +117,9 @@ test("the arrow keys move within the menu and skip the disabled item", async ()
  * that is the pattern, not a bug.
  */
 test("the menu has one tab stop", async () => {
-  const { canvas } = await mountStory(AllStates)
+  const { body } = await mountStory(AllStates)
 
-  const menu = expectAgentDrivable(canvas, {
+  const menu = expectAgentDrivable(body, {
     name: "Bay 3",
     role: "menu",
   })
@@ -135,7 +134,7 @@ test("the menu has one tab stop", async () => {
 })
 
 test("choosing an item dismisses the menu", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -145,7 +144,7 @@ test("choosing an item dismisses the menu", async () => {
   )
 
   await userEvent.click(
-    expectAgentDrivable(canvas, {
+    expectAgentDrivable(body, {
       name: "Retry title",
       role: "menuitem",
     }),
@@ -154,14 +153,12 @@ test("choosing an item dismisses the menu", async () => {
   // 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,
-    )
+    expect(body.queryAllByRole("menuitem")).toHaveLength(0)
   })
 })
 
 test("Escape dismisses without choosing", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -172,37 +169,50 @@ test("Escape dismisses without choosing", async () => {
 
   await waitFor(() => {
     expect(
-      canvas.queryAllByRole("menuitem").length,
+      body.queryAllByRole("menuitem").length,
     ).toBeGreaterThan(0)
   })
 
   await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryAllByRole("menuitem")).toHaveLength(
-      0,
-    )
+    expect(body.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`.
+ * The panel portals to `document.body` — escaping any
+ * `overflow: hidden` ancestor — and the trigger→panel link survives
+ * the boundary: `useRole` writes `aria-labelledby` on the menu
+ * pointing back at the button that names it. A scoped query for the
+ * panel now reaches for `body`; the trigger stays in the canvas.
  */
-test("the menu is not portalled out of its canvas", async () => {
-  const { canvas, canvasElement } =
+test("the menu portals to the body, still named by its trigger", async () => {
+  const { body, canvas, canvasElement } =
     await mountStory(AllVariants)
 
-  const menu = expectAgentDrivable(canvas, {
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Bay 2",
+    role: "button",
+  })
+
+  const menu = expectAgentDrivable(body, {
     name: "Bay 2",
     role: "menu",
   })
 
-  await expect(canvasElement).toContainElement(menu)
+  await expect(canvasElement).not.toContainElement(menu)
+
+  await expect(document.body).toContainElement(menu)
+
+  // The link, across the portal: the menu is named by pointing at its
+  // trigger, and the id really resolves.
+  await expect(menu).toHaveAttribute(
+    "aria-labelledby",
+    trigger.id,
+  )
 
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(menu)
 })
 
 /**
@@ -239,8 +249,7 @@ const expectAnchoredTrigger = (trigger: HTMLElement) => {
 }
 
 test("a menu sharing its trigger with a tooltip is still anchored to it", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(SharedTrigger)
+  const { body, canvas } = await mountStory(SharedTrigger)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Bay 5",
@@ -252,7 +261,7 @@ test("a menu sharing its trigger with a tooltip is still anchored to it", async
   await userEvent.click(trigger)
 
   const menu = await waitFor(() =>
-    expectAgentDrivable(canvas, { role: "menu" }),
+    expectAgentDrivable(body, { role: "menu" }),
   )
 
   // `bottom-start` with `offset(4)`: flush with the trigger's
@@ -273,7 +282,7 @@ test("a menu sharing its trigger with a tooltip is still anchored to it", async
     )
   })
 
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(menu)
 })
 
 /**
@@ -282,7 +291,7 @@ test("a menu sharing its trigger with a tooltip is still anchored to it", async
  * pointing at nothing and the test above would still pass.
  */
 test("the tooltip sharing that trigger is anchored to it too", async () => {
-  const { canvas } = await mountStory(SharedTrigger)
+  const { body, canvas } = await mountStory(SharedTrigger)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Bay 5",
@@ -294,7 +303,7 @@ test("the tooltip sharing that trigger is anchored to it too", async () => {
   trigger.focus()
 
   const tip = await waitFor(() =>
-    expectAgentDrivable(canvas, { role: "tooltip" }),
+    expectAgentDrivable(body, { role: "tooltip" }),
   )
 
   // The **main axis** only: `top` with `offset(6)`. The cross axis