@charcuterie/ui 1.1.0 → 2.0.0

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

package/src/Modal/Modal.mdx

@@ -6,10 +6,11 @@ import * as ModalStories from "./Modal.stories";
 
 # Modal
 
-Four repos, and **plex-channels and ripdeck arrived at native `<dialog>` independently**
-before this library existed. That is the design, not a shortcut: `showModal()` gives a
-focus trap, Escape, `::backdrop`, `inert` on everything behind it, and the top layer —
-from the platform, correctly, in every browser the fleet runs on.
+The **base layer**: a backdrop, a focus trap, Escape, and an outside press — and no
+chrome. A dialog is one kind of modal; so is a confirmation, a media lightbox, and
+anything else that wants a scrim over the page. `Modal` is that foundation, and
+[`Dialog`](?path=/docs/components-dialog--docs) is `Modal` plus the
+heading/Close/footer/size chrome the component shipped with before the M8 rebuild.
 
 <Canvas of={ModalStories.Default} />
 
@@ -17,97 +18,43 @@ from the platform, correctly, in every browser the fleet runs on.
 
 <Controls />
 
-## The one thing a component has to add
+## Portalled, not the top layer
 
-A native `<dialog>` is a **self-owning** control: call `showModal()` and it decides it is
-open. That is the same conflict Radix has, and it gets the same answer as everywhere else
-here — `isVisible` is the truth, and an effect makes the element agree with it. Nothing
-reads `dialogElement.open` as state; it is read only to avoid calling a method that would
-throw.
+`Modal` renders an `OverlayPanel`, which portals to `document.body`. The old `Modal` rode
+the platform top layer (`<dialog>.showModal()`); this one supersedes that
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)),
+because the top layer cannot 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 node out of a scoped query — is answered by `useRole` writing `aria-controls` /
+`aria-labelledby` across the boundary, and by stories scoping panel queries to
+`within(document.body)`.
 
 ```tsx
 const { hide, isVisible, show } = useVisibility()
 
-<Button onClick={show}>Stop the rip</Button>
+<Button onClick={show}>Open</Button>
 
-<Modal heading="Stop the rip?" isVisible={isVisible} onClose={hide}>
-  …
+<Modal aria-label="Read error on title 4" isVisible={isVisible} onClose={hide}>
+  …your own markup…
 </Modal>
 ```
 
-`onClose` is every route out — the close button, Escape, a backdrop press — so there is
-one place to wire and no way to end up with the element shut and the state still open.
+`onClose` is every route out — Escape, a backdrop press — so there is one place to wire
+and no way to end up with the element shut and the state still open.
 
-## No portal, and that is load-bearing
+## One accessible name, required
 
-The top layer is a **paint** concept. A `<dialog>` renders above everything while staying
-exactly where it is in the DOM, so it needs no portal — and that matters well past
-tidiness:
+A `role="dialog"` takes no name from its content, so pass exactly one of `aria-label` or
+`aria-labelledby`. Missing both is a dev-time warning, not a throw.
 
-> A portal moves the node to `document.body`, **out of whatever element a test or an agent
-> scoped its queries to.** `canvas.getByRole("dialog")` finds this modal. It would not find
-> a portalled one, and every story here would have to reach for `screen` and give up its
-> scoping.
+<Canvas of={ModalStories.Alert} />
 
-The same reasoning is why `Popover` uses `popover="manual"` rather than a portal.
+## Stacking is zero-config, until it is not
 
-## `open:flex`, not `flex`
-
-A closed `<dialog>` is hidden by a UA rule, and any `display: flex` of ours beats it — so
-a modal laid out with a plain `flex` renders permanently, in the page flow, with no error
-anywhere. The layout is therefore behind Tailwind's `open:` variant, keyed on the `[open]`
-attribute the browser manages.
-
-<Canvas of={ModalStories.AllVariants} />
-
-## What a story cannot press
-
-`play`'s `userEvent` is `@testing-library/user-event`, which dispatches **untrusted**
-events, and a browser runs a default action only for trusted input. So a synthetic Escape
-does not make a native `<dialog>` fire `cancel` — it does nothing at all, and a story
-asserting "Escape did not close the non-dismissable dialog" would pass for the wrong
-reason forever.
-
-The stories dispatch the close request where the browser would raise it instead, which
-splits the contract honestly: keystroke → `cancel` is the platform's and is not ours to
-test; everything downstream of `cancel` is ours and is asserted. `AllStates` pairs it with
-a differential — the dialog that refuses the close request is then closed by its own
-button — because "still open" is also true of a dialog nothing can close at all.
-
-<Canvas of={ModalStories.AllStates} />
-
-## `isDismissable={false}` cancels, it does not ignore
-
-Escape is `preventDefault`ed rather than dropped. Letting the browser close a dialog the
-app said was not dismissable would leave `isVisible` true and the element shut — the exact
-desync this component exists to prevent.
-
-## Scroll behind it is locked, and the count is why
-
-`showModal()` makes the page `inert` and then lets you scroll it anyway. The lock is a
-counted module-level one rather than a hook, because nested dialogs are legal and a naive
-lock/unlock pair has the inner dialog's cleanup unlock the page while the outer is still
-open. The release is idempotent, because StrictMode runs an effect's cleanup twice.
-
-## `dvh`, and the scrim
-
-Every size clamps at `85dvh`; `full` takes the lot. `dvh` rather than `vh` because on a
-phone the two differ by the address bar, and a dialog whose footer is under it is a dialog
-with no buttons.
-
-`::backdrop` reads `--color-scrim`, which is a **variant** token: `legible` dims at 0.84
-and `daylight` at 0.66, because how hard a direction separates a dialog from the page is
-exactly the sort of thing a visual direction decides. ePaper's is `transparent` — a panel
-with no opacity cannot dim, so it says so instead of faking it. The `Responsive` story
-asserts the computed `::backdrop` colour is really there, since a `var()` that failed to
-inherit would just look like a design choice.
-
-<Canvas of={ModalStories.Responsive} />
-
-## A modal is not a container-query citizen
-
-It gets no `ContainerBoard`. Its size is measured against the viewport by definition — it
-is the thing covering the viewport — so boarding it at three container widths would be
-measuring something with no bearing on it.
+A lone `Modal` renders its own scrim with no setup. Only when modals **stack** — one
+opened from inside another — does the app need an `OverlayStackProvider` at its root, so
+the N of them share **one** scrim, keep the top live, mark the rest `inert`, and dismiss
+top-first. The scroll lock is ref-counted through the stack, so the page frees only when
+the last modal closes.
 
 <Canvas of={ModalStories.Interactive} />