@charcuterie/ui 1.0.1 → 2.0.0

package/src/Modal/Modal.test.tsx

@@ -7,216 +7,85 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Modal.stories.tsx"
 
-const {
-  AllStates,
-  AllVariants,
-  Default,
-  Interactive,
-  Responsive,
-} = composeStories(stories)
-
-/**
- * Escape, as far as a test can press it — and the limit is worth
- * stating rather than working around quietly.
- *
- * `userEvent` is `@testing-library/user-event`, which dispatches
- * **untrusted** events. The browser runs a default action only for
- * trusted input, so a synthetic Escape keydown does not make a
- * native `<dialog>` fire `cancel` — it does nothing at all. A test
- * asserting "Escape did not close the non-dismissable dialog"
- * against a synthetic keypress therefore passes for the wrong
- * reason, forever, which is worse than not testing it.
- *
- * So the close request is dispatched where the browser would raise
- * it. That splits the contract honestly: the keystroke → `cancel`
- * half is the platform's and is not ours to test, and everything
- * downstream of `cancel` — `preventDefault`, `hide()`, the effect,
- * `close()`, focus restore — is ours and is asserted here.
- */
-const requestClose = (dialog: HTMLElement) => {
-  dialog.dispatchEvent(
-    new Event("cancel", { cancelable: true }),
-  )
-}
+const { Alert, Default, Interactive } =
+  composeStories(stories)
 
-test("the dialog is reachable from a scoped query", async () => {
-  const { canvas, canvasElement } =
+test("the base modal portals to the body, named by its aria-label", async () => {
+  const { body, canvas, canvasElement } =
     await mountStory(Default)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
-      name: "Show the read error",
+      name: "Open the base modal",
       role: "button",
     }),
   )
 
-  // Scoped to `canvas`, and that is the point of not portalling:
-  // the dialog paints in the top layer while staying inside the
-  // story root, so an agent's scoped query still reaches it.
-  const dialog = expectAgentDrivable(canvas, {
+  const modal = expectAgentDrivable(body, {
     name: "Read error on title 4",
     role: "dialog",
   })
 
-  await expect(dialog).toHaveAttribute("open")
+  // Portalled out of the canvas — the whole point over the top layer.
+  await expect(canvasElement).not.toContainElement(modal)
 
-  // The addon's own axe pass fired before any of this was clicked,
-  // so the *open* dialog audits itself.
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(modal)
 })
 
-test("size is a real width, not a class that happens to be there", async () => {
-  const { canvas } = await mountStory(AllVariants)
+test("an alertdialog role is carried through", async () => {
+  const { body, canvas } = await mountStory(Alert)
 
   await userEvent.click(
     expectAgentDrivable(canvas, {
-      name: "Open lg",
+      name: "Open an alertdialog",
       role: "button",
     }),
   )
 
-  const dialog = expectAgentDrivable(canvas, {
-    name: "Read error — lg",
-    role: "dialog",
+  // The one configuration the base surfaces that `Dialog` does not.
+  expectAgentDrivable(body, {
+    name: "Confirm erase",
+    role: "alertdialog",
   })
-
-  await expect(
-    dialog.getBoundingClientRect().width,
-  ).toBeGreaterThan(400)
 })
 
-test("a non-dismissable dialog cancels the close rather than ignoring it", async () => {
-  const { canvas } = await mountStory(AllStates)
-
-  await userEvent.click(
-    expectAgentDrivable(canvas, {
-      name: "Not dismissable",
-      role: "button",
-    }),
-  )
+test("Escape and an outside press both close through onClose", async () => {
+  const { body, canvas } = await mountStory(Default)
 
-  const dialog = expectAgentDrivable(canvas, {
-    name: "This erases eight completed titles",
-    role: "dialog",
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Open the base modal",
+    role: "button",
   })
 
-  // There is no Close button, and the close request is *cancelled*
-  // rather than ignored — letting the browser close it would leave
-  // `isVisible` true and the element shut, which is the desync the
-  // component exists to prevent.
-  await expect(
-    canvas.queryByRole("button", { name: "Close" }),
-  ).toBeNull()
-
-  requestClose(dialog)
-
-  // `find*` is async, which is what gives React's update from that
-  // dispatch a chance to flush. If the request *had* got through,
-  // this query would fail rather than the assertion below passing by
-  // being too quick.
-  const keepButton = await canvas.findByRole("button", {
-    name: "Keep the titles",
-  })
+  await userEvent.click(trigger)
 
-  await expect(dialog).toHaveAttribute("open")
+  expectAgentDrivable(body, {
+    name: "Read error on title 4",
+    role: "dialog",
+  })
 
-  // The differential half. Without it, "still open" would also be
-  // satisfied by a dialog nothing can close at all — a green
-  // assertion about a component that does not work.
-  await userEvent.click(keepButton)
+  await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
   })
-})
 
-test("a long body scrolls inside the clamp", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(AllStates)
-
-  await userEvent.click(
-    canvas.getByRole("button", { name: "Long body" }),
-  )
+  // Reopened, then dismissed by pressing the page behind it.
+  await userEvent.click(trigger)
 
-  const log = expectAgentDrivable(canvas, {
-    name: "MakeMKV log",
-    role: "dialog",
+  await waitFor(() => {
+    expect(body.getByRole("dialog")).toBeInTheDocument()
   })
 
-  // The body scrolls, the header and footer do not, and the dialog
-  // stops at `85dvh` rather than running off the screen.
-  await expect(
-    log.getBoundingClientRect().height,
-  ).toBeLessThan(globalThis.innerHeight)
+  await userEvent.click(document.body)
 
-  await expect(
-    canvas.getByText(/title 24/),
-  ).toBeInTheDocument()
-
-  // The case that would trip `scrollable-region-focusable` if the
-  // body scrolled with nothing inside it to focus.
-  await expectNoAxeViolations(canvasElement)
-})
-
-test("the scrim is the token, not Chromium's default backdrop", async () => {
-  const { canvas } = await mountStory(Responsive)
-
-  await userEvent.click(
-    expectAgentDrivable(canvas, {
-      name: "Open full-bleed",
-      role: "button",
-    }),
-  )
-
-  const dialog = expectAgentDrivable(canvas, {
-    name: "MakeMKV log — full",
-    role: "dialog",
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
   })
-
-  await expect(
-    dialog.getBoundingClientRect().height,
-  ).toBeGreaterThan(globalThis.innerHeight * 0.95)
-
-  // `::backdrop` inheriting custom properties from its originating
-  // element is the half that could silently not work.
-  //
-  // Compared against the token's *resolved* value rather than
-  // against "not transparent", which M4 learned the hard way:
-  // Chromium's own `::backdrop` is `rgba(0, 0, 0, 0.1)`, so the
-  // loose version of this assertion stayed green against a token
-  // build where `bg-scrim` generated no CSS at all.
-  //
-  // The probe is how the two become comparable — the same `var()`
-  // put through `background-color` comes back in the identical
-  // serialisation the backdrop uses.
-  const probe = document.createElement("div")
-
-  probe.style.backgroundColor = "var(--color-scrim)"
-
-  document.body.append(probe)
-
-  const expectedScrim =
-    globalThis.getComputedStyle(probe).backgroundColor
-
-  probe.remove()
-
-  await expect(expectedScrim).not.toBe("rgba(0, 0, 0, 0)")
-
-  await expect(
-    globalThis.getComputedStyle(dialog, "::backdrop")
-      .backgroundColor,
-  ).toBe(expectedScrim)
 })
 
-/**
- * `showModal()` supplies the focus trap and the focus restore; what
- * this asserts is that the state layer never disagrees with the
- * element — Escape routes through `onCancel` → `hide()` → the
- * effect → `close()`, rather than the browser closing the dialog
- * behind the app's back.
- */
 test("focus is trapped inside, and restored to the trigger on close", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Stop the rip",
@@ -225,24 +94,22 @@ test("focus is trapped inside, and restored to the trigger on close", async () =
 
   await userEvent.click(trigger)
 
-  const dialog = expectAgentDrivable(canvas, {
+  const modal = expectAgentDrivable(body, {
     name: "Stop the rip?",
     role: "dialog",
   })
 
-  // The trap, from the platform: focus is inside the dialog, and the
-  // trigger behind it is `inert` and unreachable.
-  await expect(dialog).toContainElement(
-    document.activeElement as HTMLElement,
-  )
+  await waitFor(() => {
+    expect(modal.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
 
-  requestClose(dialog)
+  await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryByRole("dialog")).toBeNull()
+    expect(body.queryByRole("dialog")).toBeNull()
   })
 
-  // Focus restored to what opened it — also the platform's, and the
-  // thing hand-rolled modals in the fleet lose.
   await expect(document.activeElement).toBe(trigger)
 })

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