@charcuterie/ui 1.0.1 → 2.0.0

package/src/Overlay/useAnchoredOverlay.ts

@@ -0,0 +1,197 @@
+import {
+  useClonedChild,
+  useUniqueId,
+} from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  size,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react"
+import type { ReactElement } from "react"
+
+/**
+ * The floating-ui block every anchored overlay — `Popover`, `Menu`,
+ * `Listbox`, `Combobox` — wrote out for itself, consolidated once.
+ *
+ * `Popover` and `Menu` had the same twelve-line `useFloating` +
+ * `useInteractions` + `useClonedChild` preamble with two constants
+ * different (the offset and the role), and the fleet's four pickers
+ * hand-rolled a fifth, sixth, seventh and eighth `computePosition`
+ * that reimplemented `flip`/`shift` against `window.innerHeight`.
+ * This is the one implementation they all take.
+ *
+ * ### The owner's "configurable, but those are the basics"
+ *
+ * Escape and outside-press both close, **on by default**, for every
+ * anchored overlay — that is what an overlay is. A component switches
+ * one off through `dismiss` (a `Combobox`'s Escape clears the query
+ * before it closes; a menu opened from a context click wants no
+ * outside-press race with the thing that spawned it), but it opts out
+ * rather than opting in.
+ *
+ * ### `size`, for the pickers
+ *
+ * `matchTriggerWidth` and `maxHeightPx` are the two things
+ * `PortalDropdown` did with a hand-measured `TriggerRect` and a
+ * `window.innerHeight` clamp. The `size` middleware does both from the
+ * platform: the panel takes the trigger's width, and it never grows
+ * past the space actually left in the viewport.
+ *
+ * The computed width/height are written **straight onto the floating
+ * element's style** rather than lifted into React state, which is
+ * floating-ui's own documented shape and is deliberate twice over: a
+ * `setState` inside `apply` re-runs the position, which re-runs
+ * `apply`, which is a render loop; and because these properties never
+ * enter the `floatingStyles` object React manages, a component
+ * re-render (a keystroke in a combobox) does not wipe them — only an
+ * `autoUpdate` tick recomputes them.
+ *
+ * ### Portal-agnostic
+ *
+ * This returns the pieces — `clonedTrigger`, `getFloatingProps`,
+ * `setFloating`, `floatingStyles`, `context` — and renders nothing.
+ * Whether the panel goes in a `FloatingPortal`, the top layer, or in
+ * place is the component's call, which is what lets the same hook back
+ * a portalled `Listbox` and (for now) a top-layer `Popover`.
+ */
+export type AnchoredOverlayRole =
+  | "dialog"
+  | "listbox"
+  | "menu"
+
+export type UseAnchoredOverlayOptions = {
+  /**
+   * Both default **on** — Escape and outside-press are what makes an
+   * overlay an overlay. Switch one off for the honest exception (a
+   * combobox that swallows the first Escape to clear its query), never
+   * to make a plain overlay sticky. Named for the flattened
+   * floating-ui `useDismiss` options they carry.
+   */
+  isEscapeDismissable?: boolean
+  isOutsidePressDismissable?: boolean
+  /** Ports `PortalDropdown`'s anchor-width match, via `size`. */
+  isTriggerWidthMatched?: boolean
+  isVisible: boolean
+  /** Clamps the panel to `min(this, available viewport space)`. */
+  maxHeightPx?: number
+  /** Popover 8, Menu/Listbox/Combobox 4. */
+  offsetValue?: number
+  onDismiss: () => void
+  placement?: Placement
+  role: AnchoredOverlayRole
+  /** The control the panel hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+export const useAnchoredOverlay = ({
+  isEscapeDismissable = true,
+  isOutsidePressDismissable = true,
+  isTriggerWidthMatched = false,
+  isVisible,
+  maxHeightPx,
+  offsetValue = 8,
+  onDismiss,
+  placement = "bottom-start",
+  role,
+  trigger,
+}: UseAnchoredOverlayOptions) => {
+  const middleware = [
+    offset(offsetValue),
+    flip(),
+    shift({ padding: 8 }),
+  ]
+
+  if (isTriggerWidthMatched || maxHeightPx !== undefined) {
+    middleware.push(
+      size({
+        padding: 8,
+        apply({ availableHeight, elements, rects }) {
+          const cap =
+            maxHeightPx === undefined
+              ? availableHeight
+              : Math.min(maxHeightPx, availableHeight)
+
+          elements.floating.style.maxHeight = `${cap}px`
+
+          if (isTriggerWidthMatched) {
+            elements.floating.style.width = `${rects.reference.width}px`
+          }
+        },
+      }),
+    )
+  }
+
+  const { context, floatingStyles, refs } = useFloating({
+    // Read-only. Charcuterie remains the sole owner; floating-ui is
+    // told what is true and never decides it.
+    open: isVisible,
+    onOpenChange: (isNextVisible) => {
+      if (!isNextVisible) {
+        onDismiss()
+      }
+    },
+    placement,
+    middleware,
+    strategy: "fixed",
+    whileElementsMounted: autoUpdate,
+  })
+
+  // `useRole` writes `aria-expanded`/`aria-haspopup`/`aria-controls`
+  // on the trigger and `id` + `role` on the panel from one source —
+  // which is what keeps `aria-controls` pointing at the panel's real
+  // id across the portal boundary, the objection the top-layer
+  // decision raised and this answers.
+  const { getFloatingProps, getReferenceProps } =
+    useInteractions([
+      useDismiss(context, {
+        escapeKey: isEscapeDismissable,
+        outsidePress: isOutsidePressDismissable,
+      }),
+      useRole(context, { role }),
+    ])
+
+  // `useRole` for a `listbox` overwrites the trigger's own role with
+  // `combobox` — the select-only-combobox pattern, which then demands
+  // its own `aria-label`. The fleet's pattern is a plain button that
+  // *opens* a listbox, so the injected `role` is dropped and the
+  // trigger keeps its native semantics while still gaining
+  // `aria-haspopup="listbox"`/`aria-expanded`/`aria-controls`. `useRole`
+  // injects a reference `role` only for listbox/combobox, so this is a
+  // no-op for `Popover` (dialog) and `Menu` (menu).
+  const { role: _discardedTriggerRole, ...referenceProps } =
+    getReferenceProps()
+
+  // A stable id on the trigger, so a panel that needs a name can point
+  // `aria-labelledby` at it across the portal. `useRole` already gives
+  // a `menu`'s reference an id (and labels the panel with it); this
+  // reuses that when present and supplies one otherwise — which is what
+  // a `listbox` panel needs, since a bare `role="listbox"` is an ARIA
+  // input field and must be named.
+  const generatedTriggerId = useUniqueId()
+
+  const triggerId =
+    (referenceProps.id as string | undefined) ??
+    generatedTriggerId
+
+  const clonedTrigger = useClonedChild(trigger, {
+    ...referenceProps,
+    id: triggerId,
+    ref: refs.setReference,
+  })
+
+  return {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating: refs.setFloating,
+    triggerId,
+  }
+}

package/src/Popover/Popover.mdx

@@ -32,35 +32,32 @@ useFloating({
 ```
 
 It is used for the three things only it can do — collision handling, a real dismiss layer,
-and focus management. The top layer, the positioning strategy, and the ARIA wiring come
-from the platform and from `useRole`.
+and focus management — all consolidated in `useAnchoredOverlay`. The positioning strategy
+and the ARIA wiring come from the platform and from `useRole`.
 
 Passing `open:` *into* floating-ui does not violate the `is`/`has` rule; the adapter
 boundary is exactly the carve-out that rule already has
 ([decision](../../../docs/decisions/2026-07-29-is-has-rule-has-no-external-api-carve-out.md)).
 
-## `popover="manual"`, not a portal and not `auto`
+## Portalled, not the top layer
 
-`popover="manual"` puts the panel in the **top layer** — no `z-index` contest, and no
-`overflow: hidden` ancestor clipping it. That is what a portal is normally reached for,
-and unlike a portal the element **stays where it is in the DOM**:
+The panel renders in a `FloatingPortal` at `document.body`. `popover="manual"` was reached
+for first — no `z-index` contest, no portal — but the top layer does not escape an
+`overflow: hidden` ancestor's *clipping* in every case the fleet hit, and a portal does
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)).
 
-> `canvas.getByRole("dialog")` finds this panel. It would not find a portalled one, and
-> every story here would have to reach for `screen` and lose its scoping. Same argument as
-> `Modal`, one layer down.
+The objection a portal used to raise — that it moves the panel out of a scoped `canvas`
+query — is answered:
 
-`manual` rather than `auto` is the state-ownership decision again. `auto` brings the UA's
-own light-dismiss, which closes the element by itself and leaves `isVisible` true.
-`useDismiss` does the same job through our callback, so Charcuterie stays the only thing
-that decides.
+> `useRole` writes `aria-controls` on the trigger pointing at the panel `id`, so
+> trigger→panel stays followable across the boundary (the test asserts it). And the story
+> scopes panel queries to `within(document.body)` while `expectAgentDrivable` — structural
+> — needs no change.
 
-### Two UA defaults that must be undone
-
-`[popover]` ships `position: fixed; inset: 0; margin: auto`. Left in place it centres the
-panel in the viewport and fights every coordinate floating-ui computes — and it looks
-deliberate, which is the worst kind of bug. `inset-auto m-0` puts it back, and
-`strategy: "fixed"` keeps the numbers viewport-relative like the top layer itself.
-`AllVariants` asserts the panel is positioned at all, for exactly this reason.
+`useDismiss` owns Escape and outside-press through our callback, so Charcuterie stays the
+only thing that decides `isVisible`. `strategy: "fixed"` keeps the coordinates
+viewport-relative; `AllVariants` asserts the panel is positioned at all, for exactly this
+reason.
 
 <Canvas of={PopoverStories.AllVariants} />
 

package/src/Popover/Popover.stories.tsx

@@ -245,3 +245,36 @@ export const Interactive: Story = {
     />
   ),
 }
+
+/**
+ * The bug the whole M8 portal reversal exists to fix. The trigger sits
+ * inside a small `overflow: hidden` box — the top layer was still
+ * clipped by it; a `FloatingPortal` to `document.body` is not. Open it
+ * and the panel escapes the clip whole.
+ */
+export const EscapesOverflowClip: Story = {
+  args: {
+    children: null,
+    heading: "Filters",
+    isVisible: false,
+    onDismiss: () => {},
+    trigger: <Button>Filters</Button>,
+  },
+  render: () => (
+    <div className="h-24 w-56 overflow-hidden rounded-md border border-border-default bg-surface-raised p-3">
+      <p className="mb-2 text-content-secondary text-xs">
+        This box is `overflow: hidden`.
+      </p>
+
+      <PopoverDemo
+        heading="Escapes the clip"
+        triggerLabel="Open (escapes the clip)"
+      >
+        <p className="text-content-secondary">
+          Portalled to the body, so the clip cannot reach
+          it.
+        </p>
+      </PopoverDemo>
+    </div>
+  ),
+}

package/src/Popover/Popover.test.tsx

@@ -11,13 +11,13 @@ const {
   AllStates,
   AllVariants,
   Default,
+  EscapesOverflowClip,
   Interactive,
   Responsive,
 } = composeStories(stories)
 
 test("the trigger and the panel agree about each other", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(Default)
+  const { body, canvas } = await mountStory(Default)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Filters",
@@ -31,31 +31,31 @@ test("the trigger and the panel agree about each other", async () => {
 
   await userEvent.click(trigger)
 
-  // Found through `canvas`, not `screen` — the panel is in the top
-  // layer and still in this story's DOM, which a portal would have
-  // cost.
-  const panel = expectAgentDrivable(canvas, {
+  // Found through `body`, not `canvas` — the panel portals to
+  // `document.body`, which is the whole point of portalling over the
+  // top layer. The trigger stays in the canvas.
+  const panel = expectAgentDrivable(body, {
     name: "Filters",
     role: "dialog",
   })
 
-  // `aria-controls` really points at the panel. An id that has
-  // drifted renders identically and announces nothing, which is why
-  // `useRole` owns both ends of it.
+  // `aria-controls` really points at the panel across the portal
+  // boundary — the direct answer to the superseded top-layer
+  // decision's one real objection. An id that has drifted renders
+  // identically and announces nothing, which is why `useRole` owns
+  // both ends of it.
   await expect(trigger).toHaveAttribute(
     "aria-controls",
     panel.id,
   )
 
-  // `manual`, not `auto`: the UA's light-dismiss closes the element
-  // by itself and leaves `isVisible` true.
-  await expect(panel).toHaveAttribute("popover", "manual")
-
-  await expectNoAxeViolations(canvasElement)
+  // The open panel audits itself; the a11y addon's own pass fires on
+  // the canvas, which the panel has now left.
+  await expectNoAxeViolations(panel)
 })
 
 test("the panel is positioned rather than centred by the UA", async () => {
-  const { canvas } = await mountStory(AllVariants)
+  const { body, canvas } = await mountStory(AllVariants)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -64,14 +64,14 @@ test("the panel is positioned rather than centred by the UA", async () => {
     }),
   )
 
-  const panel = expectAgentDrivable(canvas, {
+  const panel = expectAgentDrivable(body, {
     name: "Filters — top",
     role: "dialog",
   })
 
-  // The thing that silently fails if the UA's `inset: 0; margin:
-  // auto` is left in place: the panel would sit dead centre of the
-  // viewport looking deliberate.
+  // The thing that silently fails if a portalled panel is left at its
+  // default static position: it would sit at the top-left of the
+  // document rather than anchored to its trigger.
   const { left, top } = panel.getBoundingClientRect()
 
   await expect(left).toBeGreaterThan(0)
@@ -80,7 +80,7 @@ test("the panel is positioned rather than centred by the UA", async () => {
 })
 
 test("a panel with nothing tabbable inside is still reachable", async () => {
-  const { canvas } = await mountStory(AllStates)
+  const { body, canvas } = await mountStory(AllStates)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -89,7 +89,7 @@ test("a panel with nothing tabbable inside is still reachable", async () => {
     }),
   )
 
-  const panel = expectAgentDrivable(canvas, {
+  const panel = expectAgentDrivable(body, {
     name: "Read error detail",
     role: "dialog",
   })
@@ -108,7 +108,7 @@ test("a panel with nothing tabbable inside is still reachable", async () => {
 })
 
 test("flip and shift keep the panel inside the viewport", async () => {
-  const { canvas } = await mountStory(Responsive)
+  const { body, canvas } = await mountStory(Responsive)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
@@ -117,7 +117,7 @@ test("flip and shift keep the panel inside the viewport", async () => {
     }),
   )
 
-  const panel = expectAgentDrivable(canvas, {
+  const panel = expectAgentDrivable(body, {
     name: "Filters — top start",
     role: "dialog",
   })
@@ -145,13 +145,13 @@ test("flip and shift keep the panel inside the viewport", async () => {
  * through `useDismiss` → `onDismiss` → `hide()`, so the panel is
  * never closed by anything except the state saying so.
  *
- * Escape *is* pressable here, unlike `Modal`'s: `useDismiss` listens
- * for a keydown rather than relying on a UA default action, and a
- * synthetic keydown is a real keydown as far as a listener is
- * concerned.
+ * Escape *is* pressable here, unlike the old native-`<dialog>`
+ * `Modal`'s: `useDismiss` listens for a keydown rather than relying on
+ * a UA default action, and a synthetic keydown is a real keydown as
+ * far as a listener is concerned.
  */
 test("Escape and an outside press both dismiss through the state", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Filters",
@@ -160,7 +160,7 @@ test("Escape and an outside press both dismiss through the state", async () => {
 
   await userEvent.click(trigger)
 
-  expectAgentDrivable(canvas, {
+  expectAgentDrivable(body, {
     name: "Bay 3 filters",
     role: "dialog",
   })
@@ -168,7 +168,7 @@ test("Escape and an outside press both dismiss through the state", async () => {
   await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
   })
 
   await expect(trigger).toHaveAttribute(
@@ -180,12 +180,48 @@ test("Escape and an outside press both dismiss through the state", async () => {
   await userEvent.click(trigger)
 
   await waitFor(() => {
-    expect(canvas.getByRole("dialog")).toBeInTheDocument()
+    expect(body.getByRole("dialog")).toBeInTheDocument()
   })
 
   await userEvent.click(document.body)
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+})
+
+/**
+ * The bug the whole M8 portal reversal exists to fix: the top layer was
+ * still clipped by an `overflow: hidden` ancestor, and a portal to
+ * `document.body` is not. The proof is structural — the panel is not a
+ * descendant of the clipping box at all.
+ */
+test("the panel escapes an overflow:hidden ancestor", async () => {
+  const { body, canvas, canvasElement } = await mountStory(
+    EscapesOverflowClip,
+  )
+
+  const clipBox = canvasElement.querySelector(
+    ".overflow-hidden",
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open (escapes the clip)",
+      role: "button",
+    }),
+  )
+
+  const panel = expectAgentDrivable(body, {
+    name: "Escapes the clip",
+    role: "dialog",
   })
+
+  // Portalled out of the clipping subtree entirely — so nothing clips
+  // it — while the trigger stays inside it.
+  await expect(clipBox).not.toBeNull()
+
+  await expect(clipBox?.contains(panel)).toBe(false)
+
+  await expect(document.body.contains(panel)).toBe(true)
 })

package/src/Popover/Popover.tsx

@@ -1,18 +1,12 @@
-import { useClonedChild } 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 { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
+import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
 import { toClassName } from "../toClassName.ts"
 
 export type PopoverProps = {
@@ -51,32 +45,24 @@ export type PopoverProps = {
  *
  * What floating-ui is used for is what only it can do: collision
  * handling (`flip`, `shift`), a real dismiss layer, and focus
- * management. Positioning strategy, the top layer, and the ARIA
- * wiring come from the platform and from `useRole`.
+ * management — all of it consolidated in `useAnchoredOverlay`.
+ * Positioning strategy and the ARIA wiring come from the platform and
+ * from `useRole`.
  *
- * ### The top layer, from the platform — not a portal
+ * ### Portalled, not the top layer
  *
- * `popover="manual"` puts the panel in the top layer, which is
- * what a portal is normally reached for: no `z-index` contest, and
- * no `overflow: hidden` ancestor clipping it. Unlike a portal it
- * **stays where it is in the DOM**, so `canvas.getByRole("dialog")`
- * still finds it and a story keeps its scoping. Same argument as
- * `Modal`, one layer down.
- *
- * `manual`, not `auto`, and that is the state-ownership decision
- * again: `auto` brings the UA's own light-dismiss, which closes the
- * element by itself and leaves `isVisible` true. `useDismiss` does
- * the same job through our callback, so Charcuterie stays the only
- * thing that decides.
- *
- * ### Two UA defaults that have to be undone
- *
- * `[popover]` ships `position: fixed; inset: 0; margin: auto`,
- * which centres the panel in the viewport and fights every
- * coordinate floating-ui computes — hence `inset-auto m-0`, and
- * `strategy: "fixed"` so the numbers are viewport-relative like the
- * top layer itself. Getting either wrong reads as a positioning
- * bug rather than as a UA default.
+ * The panel goes in a `FloatingPortal` to `document.body`. The top
+ * layer (`popover="manual"`) was reached for first — it needs no
+ * portal and no `z-index` — but it does not escape an
+ * `overflow: hidden` ancestor's *clipping* in every case the fleet
+ * hit, and a portal does. The objection a portal used to raise, that
+ * it moves the panel out of a scoped `canvas` query, is answered two
+ * ways: `useRole` writes `aria-controls` on the trigger pointing at
+ * the panel `id`, so trigger→panel stays followable across the
+ * boundary; and the story scopes panel queries to
+ * `within(document.body)` while the structural `expectAgentDrivable`
+ * needs no change. `strategy: "fixed"` keeps the coordinates
+ * viewport-relative.
  */
 export const Popover = ({
   children,
@@ -87,34 +73,19 @@ export const Popover = ({
   placement = "bottom-start",
   trigger,
 }: PopoverProps): ReactNode => {
-  const { context, floatingStyles, refs } = useFloating({
-    // Read-only. Charcuterie remains the sole owner; floating-ui
-    // is told what is true and never decides it.
-    open: isVisible,
-    onOpenChange: (isNextVisible) => {
-      if (!isNextVisible) {
-        onDismiss()
-      }
-    },
+  const {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating,
+  } = useAnchoredOverlay({
+    isVisible,
+    offsetValue: 8,
+    onDismiss,
     placement,
-    middleware: [offset(8), flip(), shift({ padding: 8 })],
-    strategy: "fixed",
-    whileElementsMounted: autoUpdate,
-  })
-
-  // `useRole` writes `aria-expanded`, `aria-haspopup`, and
-  // `aria-controls` on the trigger and `id` + `role="dialog"` on
-  // the panel, from one source. Hand-writing them alongside is how
-  // an `aria-controls` ends up pointing at an id that moved.
-  const { getFloatingProps, getReferenceProps } =
-    useInteractions([
-      useDismiss(context),
-      useRole(context, { role: "dialog" }),
-    ])
-
-  const clonedTrigger = useClonedChild(trigger, {
-    ...getReferenceProps(),
-    ref: refs.setReference,
+    role: "dialog",
+    trigger,
   })
 
   return (
@@ -122,42 +93,32 @@ export const Popover = ({
       {clonedTrigger}
 
       {isVisible ? (
-        <FloatingFocusManager
-          context={context}
-          modal={false}
-        >
-          <div
-            {...getFloatingProps()}
-            aria-label={heading}
-            className={toClassName(
-              "inset-auto m-0 max-w-xs rounded-md border border-border-default bg-surface-overlay p-3 text-content-primary text-sm shadow-medium",
-              className,
-            )}
-            popover="manual"
-            // Duplicated from `getFloatingProps()` on purpose, and
-            // the two cannot differ — `useRole(context, { role:
-            // "dialog" })` above is where it comes from. Stated
-            // here because a linter cannot see a role through a
-            // spread, and neither can the next reader.
-            role="dialog"
-            ref={(node) => {
-              refs.setFloating(node)
-
-              // In a ref callback rather than an effect, because a
-              // `[popover]` is `display: none` until it is shown —
-              // and `FloatingFocusManager` is a *child*, so its
-              // effect runs first and would be focusing into a
-              // hidden element. Refs are set during commit, before
-              // any of that.
-              if (node && !node.matches(":popover-open")) {
-                node.showPopover()
-              }
-            }}
-            style={floatingStyles}
+        <FloatingPortal>
+          <FloatingFocusManager
+            context={context}
+            modal={false}
           >
-            {children}
-          </div>
-        </FloatingFocusManager>
+            <div
+              {...getFloatingProps()}
+              aria-label={heading}
+              className={toClassName(
+                PANEL_SURFACE_CLASS,
+                "z-[var(--layer-modal)] max-w-xs p-3 text-content-primary text-sm",
+                className,
+              )}
+              ref={setFloating}
+              // Duplicated from `getFloatingProps()` on purpose, and
+              // the two cannot differ — `useRole(context, { role:
+              // "dialog" })` inside the hook is where it comes from.
+              // Stated here because a linter cannot see a role through
+              // a spread, and neither can the next reader.
+              role="dialog"
+              style={floatingStyles}
+            >
+              {children}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
       ) : null}
     </>
   )