@charcuterie/ui 1.0.1 → 2.0.0

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

package/src/Menu/Menu.tsx

@@ -1,23 +1,17 @@
 import {
   selectTabIndex,
-  useClonedChild,
   useRovingFocus,
 } from "@charcuterie/logic"
 import type { Placement } from "@floating-ui/react"
 import {
-  autoUpdate,
   FloatingFocusManager,
-  flip,
-  offset,
-  shift,
-  useDismiss,
-  useFloating,
-  useInteractions,
-  useRole,
+  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 { MenuAction } from "./MenuAction.tsx"
 
@@ -112,8 +106,6 @@ export const Menu = ({
     new Map<string, HTMLButtonElement>(),
   )
 
-  const panelElement = useRef<HTMLDivElement>(null)
-
   const focus = useRovingFocus<string>()
 
   const { activeValue, registeredValues, setActiveValue } =
@@ -121,53 +113,21 @@ export const Menu = ({
 
   const [firstValue] = registeredValues
 
-  const { context, floatingStyles, refs } = useFloating({
-    open: isVisible,
-    onOpenChange: (isNextVisible) => {
-      if (!isNextVisible) {
-        onDismiss()
-      }
-    },
+  const {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating,
+  } = useAnchoredOverlay({
+    isVisible,
+    offsetValue: 4,
+    onDismiss,
     placement,
-    middleware: [offset(4), flip(), shift({ padding: 8 })],
-    strategy: "fixed",
-    whileElementsMounted: autoUpdate,
-  })
-
-  const { getFloatingProps, getReferenceProps } =
-    useInteractions([
-      useDismiss(context),
-      useRole(context, { role: "menu" }),
-    ])
-
-  const clonedTrigger = useClonedChild(trigger, {
-    ...getReferenceProps(),
-    ref: refs.setReference,
+    role: "menu",
+    trigger,
   })
 
-  /**
-   * The other half of the `isConnected` guard below. If the ref
-   * fired while the node was still detached, nothing has shown the
-   * popover — and a `[popover]` that was never shown is
-   * `display: none`, so the menu renders, passes typecheck, and is
-   * invisible to `getByRole` and to a user alike.
-   *
-   * Effects run after the tree is connected, so this is the
-   * backstop. It is idempotent: `:popover-open` is the same question
-   * the ref asks.
-   */
-  useEffect(() => {
-    const panel = panelElement.current
-
-    if (
-      isVisible &&
-      panel?.isConnected &&
-      !panel.matches(":popover-open")
-    ) {
-      panel.showPopover()
-    }
-  }, [isVisible])
-
   /**
    * Opening **makes** a member active, and this is the step the
    * first version was missing.
@@ -205,95 +165,74 @@ export const Menu = ({
       {clonedTrigger}
 
       {isVisible ? (
-        <FloatingFocusManager
-          context={context}
-          // `false`, so Tab leaves the menu and lands on the next
-          // control in the page — which is what closes it, through
-          // `useDismiss`. A trapped menu is a dialog.
-          modal={false}
-          // Focus is moved by the effect above, to whichever item
-          // `RovingFocus` made active. Letting the manager also aim
-          // it is two owners for one caret.
-          initialFocus={-1}
-        >
-          <div
-            {...getFloatingProps()}
-            className={toClassName(
-              "inset-auto m-0 flex min-w-48 flex-col gap-0.5 rounded-md border border-border-default bg-surface-overlay p-1 shadow-medium",
-              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) {
-                // Arrow keys scroll the page by default, and a menu
-                // that scrolls the document behind it while moving
-                // focus is the hand-rolled version of this
-                // component.
-                keyEvent.preventDefault()
-
-                command()
-              }
-            }}
-            popover="manual"
-            ref={(node) => {
-              refs.setFloating(node)
-
-              panelElement.current = node
-
-              // A ref callback rather than an effect, for the same
-              // reason as `Popover`: a `[popover]` is
-              // `display: none` until shown, and every child effect
-              // — including the focus move above — would otherwise
-              // be aiming at a hidden element.
-              //
-              // `isConnected` is the guard `Popover` does not need
-              // and this does. `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 — and
-              // `showPopover()` on a disconnected element throws
-              // `InvalidStateError`, which surfaces as an unhandled
-              // rejection rather than as a failing assertion.
-              if (
-                node?.isConnected &&
-                !node.matches(":popover-open")
-              ) {
-                node.showPopover()
-              }
-            }}
-            // Duplicated from `getFloatingProps()` on purpose, and
-            // the two cannot differ — `useRole(context, { role:
-            // "menu" })` above is where it comes from. Stated here
-            // because a linter cannot see a role through a spread.
-            role="menu"
-            style={floatingStyles}
+        <FloatingPortal>
+          <FloatingFocusManager
+            context={context}
+            // `false`, so Tab leaves the menu and lands on the next
+            // control in the page — which is what closes it, through
+            // `useDismiss`. A trapped menu is a dialog.
+            modal={false}
+            // Focus is moved by the effect above, to whichever item
+            // `RovingFocus` made active. Letting the manager also aim
+            // it is two owners for one caret.
+            initialFocus={-1}
           >
-            {items.map((item) => (
-              <MenuAction
-                item={item}
-                key={item.key}
-                onDismiss={onDismiss}
-                register={focus.register}
-                tabIndex={selectTabIndex(focus, item.key)}
-                trackElement={(key, element) => {
-                  if (element) {
-                    itemElements.current.set(key, element)
-                  } else {
-                    itemElements.current.delete(key)
+            <div
+              {...getFloatingProps()}
+              className={toClassName(
+                PANEL_SURFACE_CLASS,
+                "z-[var(--layer-modal)] flex min-w-48 flex-col gap-0.5 p-1",
+                className,
+              )}
+              onKeyDown={(keyEvent) => {
+                const commands: Record<string, () => void> =
+                  {
+                    ArrowDown: focus.next,
+                    ArrowUp: focus.previous,
+                    End: focus.last,
+                    Home: focus.first,
                   }
-                }}
-              />
-            ))}
-          </div>
-        </FloatingFocusManager>
+
+                const command = commands[keyEvent.key]
+
+                if (command) {
+                  // Arrow keys scroll the page by default, and a menu
+                  // that scrolls the document behind it while moving
+                  // focus is the hand-rolled version of this
+                  // component.
+                  keyEvent.preventDefault()
+
+                  command()
+                }
+              }}
+              ref={setFloating}
+              // Duplicated from `getFloatingProps()` on purpose, and
+              // the two cannot differ — `useRole(context, { role:
+              // "menu" })` in the hook is where it comes from. Stated
+              // here because a linter cannot see a role through a
+              // spread.
+              role="menu"
+              style={floatingStyles}
+            >
+              {items.map((item) => (
+                <MenuAction
+                  item={item}
+                  key={item.key}
+                  onDismiss={onDismiss}
+                  register={focus.register}
+                  tabIndex={selectTabIndex(focus, item.key)}
+                  trackElement={(key, element) => {
+                    if (element) {
+                      itemElements.current.set(key, element)
+                    } else {
+                      itemElements.current.delete(key)
+                    }
+                  }}
+                />
+              ))}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
       ) : null}
     </>
   )