@charcuterie/ui 1.1.0 → 2.0.0

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}
     </>
   )

package/src/Tooltip/Tooltip.mdx

@@ -45,15 +45,18 @@ instead of falling out of it.** Here `useRole` writes `aria-describedby` on the
 An `IconButton` under a tooltip still carries its own `aria-label`. `AllVariants` proves the
 button stays findable by the same query whether or not the tip is open.
 
-## No `popover` and no focus manager
-
-Unlike `Popover`, which is in the top layer and traps nothing. Focus never enters a tooltip
-— moving it there is what makes one inescapable — so there is no `FloatingFocusManager` and
-no `popover="manual"`.
-
-The trade is real and worth stating: a tooltip is therefore **not** in the top layer and can
-be clipped by an `overflow: hidden` ancestor. `strategy: "fixed"` keeps that to ancestors
-which actually clip fixed descendants.
+## Portalled, and no focus manager
+
+The tip renders in a `FloatingPortal` at `document.body` — the same reversal as the other
+overlays
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)):
+`strategy: "fixed"` alone still let an `overflow: hidden` ancestor clip it, and a portal
+does not. `--layer-tooltip` keeps it above a modal.
+
+There is no `FloatingFocusManager`, unlike `Popover`. Focus never enters a tooltip — moving
+it there is what would make one inescapable — so the tip stays out of the focus manager and
+the overlay stack. A scoped query for the tip now reaches for `body`; `useRole` writes
+`aria-describedby` on the trigger, so the link survives the boundary.
 
 <Canvas of={TooltipStories.AllStates} />
 

package/src/Tooltip/Tooltip.test.tsx

@@ -11,7 +11,7 @@ const { AllVariants, Default, Interactive } =
   composeStories(stories)
 
 test("nothing is shown until something asks", async () => {
-  const { canvas, canvasElement } =
+  const { body, canvas, canvasElement } =
     await mountStory(Default)
 
   expectAgentDrivable(canvas, {
@@ -19,9 +19,9 @@ test("nothing is shown until something asks", async () => {
     role: "button",
   })
 
-  await expect(
-    canvas.queryAllByRole("tooltip"),
-  ).toHaveLength(0)
+  await expect(body.queryAllByRole("tooltip")).toHaveLength(
+    0,
+  )
 
   await expectNoAxeViolations(canvasElement)
 })
@@ -34,8 +34,7 @@ test("nothing is shown until something asks", async () => {
  * floating node nobody is pointed at.
  */
 test("the trigger is described by the tip that opened", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Keyboard tip",
@@ -52,8 +51,10 @@ test("the trigger is described by the tip that opened", async () => {
     expect(trigger).toHaveFocus()
   })
 
+  // Portalled now, so found through `body`; the `aria-describedby`
+  // link survives the boundary.
   const tip = await waitFor(() =>
-    expectAgentDrivable(canvas, { role: "tooltip" }),
+    expectAgentDrivable(body, { role: "tooltip" }),
   )
 
   await expect(trigger).toHaveAttribute(
@@ -65,10 +66,7 @@ test("the trigger is described by the tip that opened", async () => {
     "Opened by focus, closed by Escape.",
   )
 
-  // Audited in the *driven* state, not at mount. The a11y addon
-  // runs axe once, when `run()` resolves — before anything has been
-  // focused — so an open tip would never be seen by it.
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(tip)
 })
 
 /**
@@ -77,28 +75,28 @@ test("the trigger is described by the tip that opened", async () => {
  * failure on the one control whose explanation lives there.
  */
 test("focus opens it and blur closes it", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body } = await mountStory(Interactive)
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+    expect(body.queryAllByRole("tooltip")).toHaveLength(0)
   })
 })
 
 test("Escape dismisses it", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body } = await mountStory(Interactive)
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   // WCAG 1.4.13 requires content shown on hover or focus to be
@@ -106,7 +104,7 @@ test("Escape dismisses it", async () => {
   await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+    expect(body.queryAllByRole("tooltip")).toHaveLength(0)
   })
 })
 
@@ -117,7 +115,7 @@ test("Escape dismisses it", async () => {
  * whether or not the tip is open.
  */
 test("the tip does not become the control's name", async () => {
-  const { canvas } = await mountStory(AllVariants)
+  const { body, canvas } = await mountStory(AllVariants)
 
   const iconButton = expectAgentDrivable(canvas, {
     name: "Bay settings",
@@ -127,7 +125,7 @@ test("the tip does not become the control's name", async () => {
   await userEvent.hover(iconButton)
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   // Still "Bay settings", not "Opens the bay's rip settings."

package/src/Tooltip/Tooltip.tsx

@@ -5,6 +5,7 @@ import {
 import type { Placement } from "@floating-ui/react"
 import {
   autoUpdate,
+  FloatingPortal,
   flip,
   offset,
   shift,
@@ -155,38 +156,40 @@ export const Tooltip = ({
       {clonedTrigger}
 
       {isVisible ? (
-        <div
-          {...getFloatingProps()}
-          className={toClassName(
-            // `intent-neutral-solid` + its own `on-solid`, rather
-            // than `surface-inverse` + `content-on-accent`. The
-            // second pair looks like the obvious one and is not a
-            // *pair* at all — nothing in the token set promises those
-            // two contrast, and in `daylight` dark they land at
-            // 2.9:1. The `solid`/`on-solid` roles exist precisely to
-            // be a guaranteed couple, and the contrast gate checks
-            // them as one.
-            "inset-auto m-0 max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
-            className,
-          )}
-          // No `popover="manual"` and no `FloatingFocusManager`,
-          // unlike `Popover`. Both exist to manage focus, and focus
-          // never enters a tooltip — moving it here is what makes
-          // one unescapable. The trade is that a tooltip is not in
-          // the top layer, so it can be clipped by an
-          // `overflow: hidden` ancestor; `strategy: "fixed"` keeps
-          // that to ancestors that actually clip fixed descendants.
-          ref={refs.setFloating}
-          // Duplicated from `getFloatingProps()` deliberately, and
-          // the two cannot differ — `useRole(context, { role:
-          // "tooltip" })` 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="tooltip"
-          style={floatingStyles}
-        >
-          {label}
-        </div>
+        <FloatingPortal>
+          <div
+            {...getFloatingProps()}
+            className={toClassName(
+              // `intent-neutral-solid` + its own `on-solid`, rather
+              // than `surface-inverse` + `content-on-accent`. The
+              // second pair looks like the obvious one and is not a
+              // *pair* at all — nothing in the token set promises those
+              // two contrast, and in `daylight` dark they land at
+              // 2.9:1. The `solid`/`on-solid` roles exist precisely to
+              // be a guaranteed couple, and the contrast gate checks
+              // them as one.
+              "z-[var(--layer-tooltip)] max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
+              className,
+            )}
+            // Portalled to `document.body`, the same reversal as the
+            // other overlays: `strategy: "fixed"` alone still let an
+            // `overflow: hidden` ancestor clip the tip, and a portal
+            // does not. No `FloatingFocusManager`, unlike `Popover` —
+            // focus never enters a tooltip, and moving it here is what
+            // would make one unescapable. `--layer-tooltip` keeps it
+            // above a modal.
+            ref={refs.setFloating}
+            // Duplicated from `getFloatingProps()` deliberately, and
+            // the two cannot differ — `useRole(context, { role:
+            // "tooltip" })` 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="tooltip"
+            style={floatingStyles}
+          >
+            {label}
+          </div>
+        </FloatingPortal>
       ) : null}
     </>
   )