@charcuterie/ui 1.1.0 → 2.0.0

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

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