@charcuterie/ui 1.0.1 → 2.0.0

package/src/Overlay/OverlayPanel.tsx

@@ -0,0 +1,195 @@
+import {
+  useLatestRef,
+  useUniqueId,
+} from "@charcuterie/logic"
+import {
+  FloatingFocusManager,
+  FloatingPortal,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react"
+import type { ReactNode } from "react"
+import { useCallback, useEffect } from "react"
+
+import { lockScrollBehind } from "./lockScrollBehind.ts"
+import { useOverlayStack } from "./OverlayStack.tsx"
+import { SharedBackdrop } from "./SharedBackdrop.tsx"
+
+/**
+ * The portalled, backdrop-backed, focus-trapping panel that `Modal`
+ * renders. No chrome — that is `Dialog`'s job — only the four things
+ * every backdrop overlay needs: it portals to `document.body`, a
+ * scrim stands behind it, focus is trapped inside it, and Escape or an
+ * outside press closes it.
+ *
+ * ### Portalled, and the top layer is gone on purpose
+ *
+ * This supersedes the `<dialog>.showModal()` top-layer approach. The
+ * top layer paints above everything but cannot escape an
+ * `overflow: hidden` ancestor's *clipping* in every case the fleet
+ * hit; a portal to `document.body` does. The objection the old
+ * decision raised — a portal moves the node out of a scoped query —
+ * is answered by `useRole` writing `aria-controls`/`aria-labelledby`
+ * so the trigger→panel link is followable across the boundary, and by
+ * the stories scoping panels to `within(document.body)` while the
+ * structural `expectAgentDrivable` needs no change.
+ *
+ * ### Only the top of the stack is live
+ *
+ * `useDismiss` (Escape + outside press) is enabled **only when this is
+ * the top** of the stack, so an outside press or Escape closes the
+ * innermost modal and nothing under it — the same rule the platform's
+ * nested `<dialog>` gave for free, without a hand-rolled document
+ * keydown racing the focus manager. Everything below the top is
+ * `inert`, which is what `expectHiddenFromAgents` asserts and what
+ * makes `FloatingFocusManager`'s trap unambiguous.
+ *
+ * ### One accessible name, required
+ *
+ * A `role="dialog"` takes no name from its content, so one of
+ * `aria-label` / `aria-labelledby` must be present. Missing both is a
+ * dev-time warning, not a throw — the lesson `Spinner`, `Popover`, and
+ * `Modal` each learned, applied without breaking a render.
+ */
+export type OverlayPanelProps = {
+  "aria-label"?: string
+  "aria-labelledby"?: string
+  children: ReactNode
+  className?: string
+  /** Escape and an outside press both close. */
+  isDismissable?: boolean
+  isVisible: boolean
+  onClose: () => void
+  role?: "alertdialog" | "dialog"
+}
+
+export const OverlayPanel = ({
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  children,
+  className,
+  isDismissable = true,
+  isVisible,
+  onClose,
+  role = "dialog",
+}: OverlayPanelProps): ReactNode => {
+  const stack = useOverlayStack()
+
+  const id = useUniqueId()
+
+  // A stable close, so registering it does not churn the stack as the
+  // caller's `onClose` closure changes identity between renders.
+  const onCloseRef = useLatestRef(onClose)
+
+  const stableOnClose = useCallback(() => {
+    onCloseRef.current()
+  }, [onCloseRef])
+
+  const isTop = !stack.isProvided || stack.topId === id
+
+  const { context, refs } = useFloating({
+    open: isVisible,
+    onOpenChange: (isNextVisible) => {
+      if (!isNextVisible) {
+        onClose()
+      }
+    },
+  })
+
+  const { getFloatingProps } = useInteractions([
+    useDismiss(context, {
+      escapeKey: isDismissable && isTop,
+      // The top's outside press is the backdrop click. A per-panel
+      // `outsidePress` on a *lower* modal would close it too, so it is
+      // scoped to the top — which is also why the scrim needs no click
+      // handler of its own.
+      outsidePress: isDismissable && isTop,
+    }),
+    useRole(context, { role }),
+  ])
+
+  const { register, unregister } = stack
+
+  useEffect(() => {
+    if (!isVisible) {
+      return
+    }
+
+    register({ id, onClose: stableOnClose })
+
+    return () => {
+      unregister(id)
+    }
+  }, [id, isVisible, register, stableOnClose, unregister])
+
+  // Ref-counted through `lockScrollBehind`'s module scope, so N
+  // stacked panels lock the page once and free it only when the last
+  // closes — with or without a provider.
+  useEffect(
+    () => (isVisible ? lockScrollBehind() : undefined),
+    [isVisible],
+  )
+
+  useEffect(() => {
+    if (
+      isVisible &&
+      ariaLabel === undefined &&
+      ariaLabelledBy === undefined
+    ) {
+      console.warn(
+        'OverlayPanel: a modal needs an accessible name. Pass `aria-label` or `aria-labelledby` — a `role="dialog"` takes none from its content and is announced as just "dialog".',
+      )
+    }
+  }, [ariaLabel, ariaLabelledBy, isVisible])
+
+  if (!isVisible) {
+    return null
+  }
+
+  return (
+    <>
+      {/* A self-hosting `Modal` renders its own scrim; under a
+          provider the shared one already stands behind every panel. */}
+      {stack.isProvided ? null : (
+        <SharedBackdrop isVisible />
+      )}
+
+      <FloatingPortal>
+        <div className="fixed inset-0 z-[var(--layer-modal)] flex items-center justify-center">
+          <FloatingFocusManager
+            context={context}
+            // Only the top traps focus; a lower panel is `inert`
+            // anyway, and two live traps fight over one caret.
+            disabled={!isTop}
+            modal
+          >
+            <div
+              {...getFloatingProps()}
+              // Spread rather than written as literal attributes:
+              // both `dialog` and `alertdialog` take a name, but the
+              // role arrives as a variable and a static a11y linter
+              // cannot confirm that through it. `useRole` supplies the
+              // role itself; these are the accessible name.
+              {...{
+                "aria-label": ariaLabel,
+                "aria-labelledby": ariaLabelledBy,
+              }}
+              className={className}
+              // The fallback the plan calls for: `inert` on every panel
+              // but the top, so a lower modal is unreachable across the
+              // portal boundary even where `FloatingFocusManager`'s
+              // outside-hiding does not reach a sibling portal.
+              inert={isTop ? undefined : true}
+              ref={refs.setFloating}
+              role={role}
+            >
+              {children}
+            </div>
+          </FloatingFocusManager>
+        </div>
+      </FloatingPortal>
+    </>
+  )
+}

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"