@charcuterie/ui 1.1.0 → 2.0.0

package/src/Modal/Modal.tsx

@@ -1,228 +1,78 @@
-import { useUniqueId } from "@charcuterie/logic"
-import type {
-  ComponentPropsWithRef,
-  ReactNode,
-} from "react"
-import { useEffect, useRef } from "react"
+import type { ReactNode } from "react"
 
-import { Button } from "../Button/Button.tsx"
+import { OverlayPanel } from "../Overlay/OverlayPanel.tsx"
 import { toClassName } from "../toClassName.ts"
-import { lockScrollBehind } from "./lockScrollBehind.ts"
 
-export type ModalSize = "full" | "lg" | "md" | "sm" | "xl"
-
-export type ModalProps = Omit<
-  ComponentPropsWithRef<"dialog">,
-  "onClose" | "open"
-> & {
-  /** The footer row. Buttons, usually. */
-  footer?: ReactNode
-  heading: string
-  headingLevel?: 2 | 3 | 4
-  /**
-   * Escape and a backdrop press both close. Off for the one
-   * honest case — a destructive confirm the user has to answer —
-   * and off means Escape is *cancelled* rather than ignored, so
-   * the browser cannot close a dialog the app still owns.
-   */
+export type ModalProps = {
+  "aria-label"?: string
+  "aria-labelledby"?: string
+  children: ReactNode
+  className?: string
+  /** Escape and a backdrop press both close. */
   isDismissable?: boolean
   isVisible: boolean
   /**
-   * Every route out lands here: the close button, Escape, a
-   * backdrop press. Wire it to a `useVisibility()`'s `hide`.
+   * Every route out lands here: Escape, a backdrop press. Wire it to a
+   * `useVisibility()`'s `hide`.
    */
   onClose: () => void
-  size?: ModalSize
+  role?: "alertdialog" | "dialog"
 }
 
 /**
- * `85dvh` rather than `85vh` — on a phone the two differ by the
- * address bar, and a dialog whose footer is under it is a dialog
- * with no buttons.
- */
-const SIZE_CLASS: Record<ModalSize, string> = {
-  sm: "max-h-[85dvh] w-full max-w-sm",
-  md: "max-h-[85dvh] w-full max-w-md",
-  lg: "max-h-[85dvh] w-full max-w-2xl",
-  // M5 added this, because the scale jumped from 42rem straight to
-  // the whole viewport and rip-deck's capture tail lands in the
-  // gap: a MakeMKV robot log is fixed-width `MSG:5072,0,1,"…"`
-  // lines that wrap badly at 42rem, and a full-screen dialog over a
-  // nine-bay dashboard hides the thing being diagnosed. 56rem is
-  // what that app's hand-rolled `<dialog>` used before the swap.
-  xl: "max-h-[85dvh] w-full max-w-4xl",
-  full: "h-[100dvh] max-h-[100dvh] w-full max-w-full rounded-none",
-}
-
-/**
- * Four repos, and **plex-channels and ripdeck independently
- * converged on native `<dialog>`** — which is the design here
- * rather than 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.
- *
- * What is not free — and the reason a component exists at all —
- * is that 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 in this library: **`isVisible` is the truth, and an effect
- * makes the element agree with it.** Nothing here reads
- * `dialogElement.open` as state; it is read only to avoid calling
- * a method that would throw.
+ * The base layer. Backdrop, dismiss, and portal — and no chrome.
  *
- * ### Why it is not portalled
+ * This is the generic modal the library never had while `Modal` was
+ * secretly a *dialog*. A dialog is one kind of modal; so are a
+ * confirmation, a media lightbox, and anything else that wants a
+ * scrim, an Escape, and a click-outside. `Modal` is that foundation,
+ * and `Dialog` is `Modal` plus the heading/Close/footer/size chrome
+ * the old component shipped.
  *
- * 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, because 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 one. It would not find a
- * portalled one, and the story would have to reach for `screen`
- * and lose its scoping.
+ * It renders an `OverlayPanel`: portalled to `document.body` (escaping
+ * `overflow: hidden` the top layer could not), focus-trapped, stacked
+ * by portal append order, and dismissible only when it is the top of
+ * the stack. All `Modal` adds is a sensible surface — a bordered,
+ * rounded, elevated box clamped to `85dvh` — that a caller composes
+ * over with `className`. `Dialog` replaces the width and layout; a
+ * bare `Modal` sizes to its content.
  *
- * ### `open:flex`, not `flex`
+ * ### One accessible name, required
  *
- * A closed `<dialog>` is hidden by a UA rule that any
- * `display: flex` of ours would beat — so the modal would render
- * permanently, in the page flow, with no error. The layout is
- * therefore behind Tailwind's `open:` variant, which is the
- * `[open]` attribute the browser manages.
+ * A `role="dialog"` takes no name from its content, so pass exactly
+ * one of `aria-label` / `aria-labelledby`. Missing both is a dev-time
+ * warning from `OverlayPanel`, not a throw — the lesson `Spinner`,
+ * `Popover`, and the old `Modal` each learned.
  *
- * ### The accessible name
+ * ### Stacking is zero-config, until it is not
  *
- * `heading` is required and is a string, not a `ReactNode`. A
- * dialog with no name is announced as "dialog" and nothing else,
- * which is what every hand-rolled modal in the inventory does.
+ * 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
+ * and dismiss top-first.
  */
+const MODAL_BOX_CLASS =
+  "flex max-h-[85dvh] flex-col overflow-hidden rounded-lg border border-border-default bg-surface-overlay text-content-primary shadow-high"
+
 export const Modal = ({
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
   children,
   className,
-  footer,
-  heading,
-  headingLevel = 2,
   isDismissable = true,
   isVisible,
   onClose,
-  size = "md",
-  ...dialogProps
-}: ModalProps): ReactNode => {
-  const dialogRef = useRef<HTMLDialogElement>(null)
-
-  const headingId = useUniqueId()
-
-  const Heading = `h${headingLevel}` as const
-
-  useEffect(() => {
-    const dialogElement = dialogRef.current
-
-    if (!dialogElement) {
-      return
-    }
-
-    // Guarded both ways. `showModal()` on an already-open dialog
-    // throws `InvalidStateError`, and `close()` on a closed one
-    // fires a spurious `close` event — either turns a re-render
-    // into a bug.
-    if (isVisible && !dialogElement.open) {
-      dialogElement.showModal()
-    }
-
-    if (!isVisible && dialogElement.open) {
-      dialogElement.close()
-    }
-  }, [isVisible])
-
-  useEffect(
-    () => (isVisible ? lockScrollBehind() : undefined),
-    [isVisible],
-  )
-
-  return (
-    /*
-     * The one suppression in this package, and the rule really is
-     * wrong here rather than inconvenient.
-     *
-     * `useKeyWithClickEvents` looks for a click handler on
-     * something a keyboard user cannot reach. This one is on the
-     * **backdrop** — which is not an element, has no keyboard
-     * equivalent to give it, and whose keyboard counterpart is the
-     * `onCancel` directly above: Escape, from the platform, which
-     * is the entire reason this is built on `<dialog>`. Biome
-     * cannot see `onCancel` as a keyboard route.
-     *
-     * Pairing the click with an `onKeyDown` to satisfy the rule
-     * would duplicate a close request the browser already routes
-     * correctly — including deciding which of two stacked dialogs
-     * it belongs to — which is a worse component in exchange for a
-     * green linter.
-     */
-    // biome-ignore lint/a11y/useKeyWithClickEvents: Escape is handled by `onCancel`, which this rule cannot see.
-    <dialog
-      {...dialogProps}
-      aria-labelledby={headingId}
-      className={toClassName(
-        // `m-auto` and `p-0` undo the UA stylesheet, which centres
-        // by margin and adds padding of its own.
-        "m-auto flex-col overflow-hidden rounded-lg border border-border-default bg-surface-overlay p-0 text-content-primary shadow-high backdrop:bg-scrim open:flex",
-        SIZE_CLASS[size],
-        className,
-      )}
-      onCancel={(cancelEvent) => {
-        // Escape. Cancelled rather than ignored when the dialog is
-        // not dismissable: letting the browser close it would
-        // leave `isVisible` true and the element shut, which is
-        // precisely the desync this component exists to prevent.
-        cancelEvent.preventDefault()
-
-        if (isDismissable) {
-          onClose()
-        }
-      }}
-      onClick={(clickEvent) => {
-        // The backdrop is not an element — a press on it targets
-        // the `<dialog>` itself, while a press on the content
-        // targets something inside. Comparing target to
-        // currentTarget is the whole test.
-        if (
-          isDismissable &&
-          clickEvent.target === clickEvent.currentTarget
-        ) {
-          onClose()
-        }
-      }}
-      ref={dialogRef}
-    >
-      <header className="flex shrink-0 items-start justify-between gap-3 border-b border-border-subtle p-4">
-        <Heading
-          className="font-semibold text-lg leading-tight"
-          id={headingId}
-        >
-          {heading}
-        </Heading>
-
-        {isDismissable ? (
-          <Button
-            appearance="ghost"
-            intent="neutral"
-            onClick={onClose}
-            size="sm"
-          >
-            Close
-          </Button>
-        ) : null}
-      </header>
-
-      <div className="min-h-0 flex-1 overflow-auto p-4">
-        {children}
-      </div>
-
-      {footer ? (
-        <footer className="flex shrink-0 flex-wrap justify-end gap-2 border-t border-border-subtle p-4">
-          {footer}
-        </footer>
-      ) : null}
-    </dialog>
-  )
-}
+  role = "dialog",
+}: ModalProps): ReactNode => (
+  <OverlayPanel
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledBy}
+    className={toClassName(MODAL_BOX_CLASS, className)}
+    isDismissable={isDismissable}
+    isVisible={isVisible}
+    onClose={onClose}
+    role={role}
+  >
+    {children}
+  </OverlayPanel>
+)

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