@charcuterie/ui 1.1.0 → 2.0.0

package/src/Overlay/OverlayStack.test.tsx

@@ -0,0 +1,235 @@
+import type { ReactNode } from "react"
+import { act } from "react"
+import { createRoot } from "react-dom/client"
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  expect,
+  test,
+} from "vitest"
+
+import { OverlayPanel } from "./OverlayPanel.tsx"
+import type { OverlayStackValue } from "./OverlayStack.tsx"
+import {
+  OverlayStackProvider,
+  useOverlayStack,
+} from "./OverlayStack.tsx"
+
+/**
+ * The stack's bookkeeping, driven directly rather than through a
+ * component's chrome — this is infrastructure with no story, so it
+ * mounts its own root and drives it with `act`, which flushes the
+ * passive effects the scroll lock and `requestCloseTop`'s live-top ref
+ * both ride on. The act environment is turned on for this file only;
+ * ui-dom isolates test files, so it never reaches the story-driven
+ * suites next door.
+ */
+// Typed as a string-keyed record so the React flag's own
+// SCREAMING_CASE name never has to be *declared* as a property (the
+// boolean-naming rule wants `is`/`has`); it is only assigned.
+const reactEnvironment = globalThis as unknown as Record<
+  string,
+  boolean
+>
+
+beforeAll(() => {
+  reactEnvironment.IS_REACT_ACT_ENVIRONMENT = true
+})
+
+afterAll(() => {
+  reactEnvironment.IS_REACT_ACT_ENVIRONMENT = false
+})
+
+const roots: {
+  container: HTMLElement
+  root: ReturnType<typeof createRoot>
+}[] = []
+
+const mount = async (ui: ReactNode) => {
+  const container = document.createElement("div")
+
+  document.body.append(container)
+
+  const root = createRoot(container)
+
+  await act(async () => {
+    root.render(ui)
+  })
+
+  roots.push({ container, root })
+
+  return root
+}
+
+afterEach(async () => {
+  for (const { container, root } of roots.splice(0)) {
+    await act(async () => {
+      root.unmount()
+    })
+
+    container.remove()
+  }
+})
+
+/**
+ * The one component this file declares: it reports the live stack up
+ * through `onStack` and renders two panels whose visibility the test
+ * drives. `OverlayStackProvider` is rendered by the tests around it,
+ * so this stays a single component (the `no-multi-comp` rule) while
+ * still being a real consumer of the context.
+ */
+const Harness = ({
+  isAVisible = false,
+  isBVisible = false,
+  onStack,
+}: {
+  isAVisible?: boolean
+  isBVisible?: boolean
+  onStack?: (stack: OverlayStackValue) => void
+}): ReactNode => {
+  onStack?.(useOverlayStack())
+
+  return (
+    <>
+      <OverlayPanel
+        aria-label="A"
+        isVisible={isAVisible}
+        onClose={() => {}}
+      >
+        first
+      </OverlayPanel>
+
+      <OverlayPanel
+        aria-label="B"
+        isVisible={isBVisible}
+        onClose={() => {}}
+      >
+        second
+      </OverlayPanel>
+    </>
+  )
+}
+
+test("registers in order, closes the top, and toggles the scrim with depth", async () => {
+  const probe: { current: OverlayStackValue | null } = {
+    current: null,
+  }
+
+  await mount(
+    <OverlayStackProvider>
+      <Harness
+        onStack={(next) => {
+          probe.current = next
+        }}
+      />
+    </OverlayStackProvider>,
+  )
+
+  const stack = () => {
+    if (!probe.current) {
+      throw new Error("probe never rendered")
+    }
+
+    return probe.current
+  }
+
+  const scrim = () =>
+    document.body.querySelector(".bg-scrim")
+
+  expect(stack().depth).toBe(0)
+  expect(scrim()).toBeNull()
+
+  let closedTop = ""
+
+  await act(async () => {
+    stack().register({
+      id: "a",
+      onClose: () => {
+        closedTop = "a"
+      },
+    })
+  })
+
+  expect(stack().depth).toBe(1)
+  expect(stack().topId).toBe("a")
+  // The scrim renders as long as at least one modal is open.
+  expect(scrim()).not.toBeNull()
+
+  await act(async () => {
+    stack().register({
+      id: "b",
+      onClose: () => {
+        closedTop = "b"
+      },
+    })
+  })
+
+  expect(stack().depth).toBe(2)
+  // Last registered is the top.
+  expect(stack().topId).toBe("b")
+
+  // `requestCloseTop` targets the last, not the first.
+  await act(async () => {
+    stack().requestCloseTop()
+  })
+
+  expect(closedTop).toBe("b")
+
+  await act(async () => {
+    stack().unregister("b")
+  })
+
+  // The next one down becomes the top, and the scrim stays.
+  expect(stack().topId).toBe("a")
+  expect(scrim()).not.toBeNull()
+
+  await act(async () => {
+    stack().unregister("a")
+  })
+
+  // Empty, so the scrim goes.
+  expect(stack().depth).toBe(0)
+  expect(scrim()).toBeNull()
+})
+
+test("the scroll lock frees the page only when the last modal closes", async () => {
+  const original = document.documentElement.style.overflow
+
+  const root = await mount(
+    <OverlayStackProvider>
+      <Harness isAVisible isBVisible />
+    </OverlayStackProvider>,
+  )
+
+  // Two open, one lock.
+  expect(document.documentElement.style.overflow).toBe(
+    "hidden",
+  )
+
+  await act(async () => {
+    root.render(
+      <OverlayStackProvider>
+        <Harness isAVisible isBVisible={false} />
+      </OverlayStackProvider>,
+    )
+  })
+
+  // One still open — the ref count has not reached zero.
+  expect(document.documentElement.style.overflow).toBe(
+    "hidden",
+  )
+
+  await act(async () => {
+    root.render(
+      <OverlayStackProvider>
+        <Harness isAVisible={false} isBVisible={false} />
+      </OverlayStackProvider>,
+    )
+  })
+
+  // Empty, so the page is restored to exactly what it was.
+  expect(document.documentElement.style.overflow).toBe(
+    original,
+  )
+})

package/src/Overlay/OverlayStack.tsx

@@ -0,0 +1,132 @@
+import { useLatestRef } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react"
+
+import { SharedBackdrop } from "./SharedBackdrop.tsx"
+
+/**
+ * The ordered stack of open **backdrop** modals, and the one shared
+ * scrim that stands behind all of them.
+ *
+ * ### Why a stack at all
+ *
+ * A modal must know two things it cannot see for itself: whether it is
+ * the **top** of the stack (only the top traps focus and answers
+ * Escape / an outside press; everything under it is `inert`), and how
+ * **deep** the stack is (the scrim shows while at least one modal is
+ * open and hides when the last closes). An `OverlayPanel` registers on
+ * open and unregisters on close, and reads `topId`/`depth` back.
+ *
+ * ### The provider is optional
+ *
+ * `useOverlayStack()` has a self-hosting default — `isProvided:
+ * false`, a no-op register, `depth: 0` — so a lone `Modal` needs no
+ * setup: it sees it is unprovided and renders its own scrim, treating
+ * itself as the top. Only *stacking* needs `OverlayStackProvider` at
+ * the app root, where a single shared scrim and real top-of-stack
+ * bookkeeping replace N self-hosted scrims fighting for the same
+ * corner.
+ */
+export type OverlayStackEntry = {
+  id: string
+  onClose: () => void
+}
+
+export type OverlayStackValue = {
+  depth: number
+  /**
+   * `false` in the context default. An `OverlayPanel` reads this to
+   * decide whether to render its own scrim (unprovided) or defer to
+   * the provider's shared one.
+   */
+  isProvided: boolean
+  register: (entry: OverlayStackEntry) => void
+  /** Closes the top entry — the imperative twin of an outside press. */
+  requestCloseTop: () => void
+  topId: null | string
+  unregister: (id: string) => void
+}
+
+const DEFAULT_STACK: OverlayStackValue = {
+  depth: 0,
+  isProvided: false,
+  register: () => {},
+  requestCloseTop: () => {},
+  topId: null,
+  unregister: () => {},
+}
+
+const OverlayStackContext =
+  createContext<OverlayStackValue>(DEFAULT_STACK)
+
+export const useOverlayStack = (): OverlayStackValue =>
+  useContext(OverlayStackContext)
+
+export const OverlayStackProvider = ({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode => {
+  const [entries, setEntries] = useState<
+    OverlayStackEntry[]
+  >([])
+
+  // Read through a ref so `requestCloseTop` stays stable while still
+  // seeing the live top.
+  const entriesRef = useLatestRef(entries)
+
+  const register = useCallback(
+    (entry: OverlayStackEntry) => {
+      setEntries((previous) =>
+        // In place when the id is already present — an `onClose`
+        // update must not reorder the stack, or a re-render would
+        // shuffle which modal is "top". New ids append, which is what
+        // makes the last-registered one the top.
+        previous.some((one) => one.id === entry.id)
+          ? previous.map((one) =>
+              one.id === entry.id ? entry : one,
+            )
+          : [...previous, entry],
+      )
+    },
+    [],
+  )
+
+  const unregister = useCallback((id: string) => {
+    setEntries((previous) =>
+      previous.filter((one) => one.id !== id),
+    )
+  }, [])
+
+  const requestCloseTop = useCallback(() => {
+    entriesRef.current.at(-1)?.onClose()
+  }, [entriesRef])
+
+  const value = useMemo<OverlayStackValue>(
+    () => ({
+      depth: entries.length,
+      isProvided: true,
+      register,
+      requestCloseTop,
+      topId: entries.at(-1)?.id ?? null,
+      unregister,
+    }),
+    [entries, register, requestCloseTop, unregister],
+  )
+
+  return (
+    <OverlayStackContext.Provider value={value}>
+      {/* First, so it mounts its portal before the panels and paints
+          beneath them at an equal z-index. */}
+      <SharedBackdrop isVisible={entries.length > 0} />
+
+      {children}
+    </OverlayStackContext.Provider>
+  )
+}

package/src/Overlay/SharedBackdrop.tsx

@@ -0,0 +1,40 @@
+import { FloatingPortal } from "@floating-ui/react"
+import type { ReactNode } from "react"
+
+/**
+ * The scrim, and there is exactly one of it however many backdrop
+ * modals are stacked.
+ *
+ * Purely visual: `aria-hidden`, no handlers. Dismissal — a press
+ * anywhere off the top panel — is the top panel's own
+ * `useDismiss({ outsidePress })`, not a click on this node, which is
+ * what lets the whole package drop the `useKeyWithClickEvents`
+ * suppression the `<dialog>` backdrop needed. A press lands on the
+ * top panel's full-viewport centring layer (which sits above this),
+ * so this element never has to be the click target.
+ *
+ * Portalled to `document.body` on `--layer-overlay`, one step **below**
+ * the panels' `--layer-modal`, so it always paints behind every open
+ * modal and never intercepts a click meant for the dialog on top of it
+ * — a real bug a same-z-plus-DOM-order scheme has, because a
+ * later-mounted scrim then covers the panel. Stacking *between* panels
+ * still falls out of append order at the one `--layer-modal`.
+ */
+export const SharedBackdrop = ({
+  isVisible,
+}: {
+  isVisible: boolean
+}): ReactNode => {
+  if (!isVisible) {
+    return null
+  }
+
+  return (
+    <FloatingPortal>
+      <div
+        aria-hidden="true"
+        className="fixed inset-0 z-[var(--layer-overlay)] bg-scrim"
+      />
+    </FloatingPortal>
+  )
+}

package/src/Overlay/overlayPanelClass.ts

@@ -0,0 +1,17 @@
+/**
+ * The surface an anchored overlay's panel is drawn on — the four
+ * tokens `Popover` and `Menu` wrote out byte-identically, and that
+ * `Listbox` and `Combobox` are about to write a third and fourth
+ * time.
+ *
+ * Only the *surface* lives here: the raised background, the hairline
+ * border, the corner radius, and the elevation. Everything a panel
+ * does with that surface — a popover's `max-w-xs p-3`, a menu's
+ * `min-w-48 flex flex-col`, a listbox's scroll clamp — is the panel's
+ * own and stays at the call site, composed after this with
+ * `toClassName`. Pulling the shared half out is what keeps a change
+ * to the overlay surface (a new elevation token, say) from having to
+ * be made in four places and kept in agreement by hand.
+ */
+export const PANEL_SURFACE_CLASS =
+  "rounded-md border border-border-default bg-surface-overlay shadow-medium"

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