@charcuterie/ui 1.1.0 → 2.0.1

package/src/Dialog/Dialog.test.tsx

@@ -0,0 +1,340 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import {
+  expectAgentDrivable,
+  expectHiddenFromAgents,
+} from "../testing/index.ts"
+import * as stories from "./Dialog.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  Default,
+  Interactive,
+  NoBody,
+  Responsive,
+  Stacked,
+} = composeStories(stories)
+
+test("a dialog with no body renders from heading and footer alone", async () => {
+  const { body, canvas } = await mountStory(NoBody)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Delete the file",
+      role: "button",
+    }),
+  )
+
+  // `children` is optional: the question is the accessible name and
+  // the answers are the footer, with nothing in between.
+  const dialog = expectAgentDrivable(body, {
+    name: "Delete this file? This cannot be undone.",
+    role: "dialog",
+  })
+
+  await expect(
+    expectAgentDrivable(body, {
+      name: "Delete",
+      role: "button",
+    }),
+  ).toBeInTheDocument()
+
+  await expectNoAxeViolations(dialog)
+})
+
+test("the dialog is reachable from a body-scoped query", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Show the read error",
+      role: "button",
+    }),
+  )
+
+  // Portalled now, so the panel is found through `body`; the trigger
+  // stays in the canvas.
+  const dialog = expectAgentDrivable(body, {
+    name: "Read error on title 4",
+    role: "dialog",
+  })
+
+  await expectNoAxeViolations(dialog)
+})
+
+test("size is a real width, not a class that happens to be there", async () => {
+  const { body, canvas } = await mountStory(AllVariants)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open lg",
+      role: "button",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(body, {
+    name: "Read error — lg",
+    role: "dialog",
+  })
+
+  await expect(
+    dialog.getBoundingClientRect().width,
+  ).toBeGreaterThan(400)
+})
+
+test("a non-dismissable dialog ignores Escape rather than closing", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Not dismissable",
+      role: "button",
+    }),
+  )
+
+  const _dialog = expectAgentDrivable(body, {
+    name: "This erases eight completed titles",
+    role: "dialog",
+  })
+
+  // There is no Close button, and Escape is disabled at the dismiss
+  // layer (`isDismissable={false}` → `useDismiss` escapeKey off), so
+  // the browser cannot close a dialog the app still owns.
+  await expect(
+    body.queryByRole("button", { name: "Close" }),
+  ).toBeNull()
+
+  await userEvent.keyboard("{Escape}")
+
+  const keepButton = await body.findByRole("button", {
+    name: "Keep the titles",
+  })
+
+  await expect(body.getByRole("dialog")).toBeInTheDocument()
+
+  // The differential half. Without it, "still open" would also be
+  // satisfied by a dialog nothing can close at all.
+  await userEvent.click(keepButton)
+
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+})
+
+test("a long body scrolls inside the clamp", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Long body" }),
+  )
+
+  const log = expectAgentDrivable(body, {
+    name: "MakeMKV log",
+    role: "dialog",
+  })
+
+  // 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 expect(
+    body.getByText(/title 24/),
+  ).toBeInTheDocument()
+
+  await expectNoAxeViolations(log)
+})
+
+test("the scrim is the token, rendered as the shared backdrop", async () => {
+  const { body, canvas } = await mountStory(Responsive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open full-bleed",
+      role: "button",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(body, {
+    name: "MakeMKV log — full",
+    role: "dialog",
+  })
+
+  await expect(
+    dialog.getBoundingClientRect().height,
+  ).toBeGreaterThan(globalThis.innerHeight * 0.95)
+
+  // The shared backdrop node renders while a modal is open, and its
+  // background really resolves the variant token — not "not
+  // transparent", which M4 learned stayed green against a token build
+  // where `bg-scrim` generated no CSS at all.
+  const scrim = document.body.querySelector(".bg-scrim")
+
+  await expect(scrim).not.toBeNull()
+
+  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(scrim as Element)
+      .backgroundColor,
+  ).toBe(expectedScrim)
+})
+
+/**
+ * The keyboard contract, driven — and Escape is pressable for real
+ * now, unlike the old native `<dialog>`. `useDismiss` listens for a
+ * keydown rather than relying on a UA default action, so
+ * `userEvent.keyboard("{Escape}")` is a real close request.
+ */
+test("focus is trapped inside, and Escape restores it to the trigger", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Stop the rip",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  const dialog = expectAgentDrivable(body, {
+    name: "Stop the rip?",
+    role: "dialog",
+  })
+
+  await waitFor(() => {
+    expect(dialog.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+
+  // Focus restored to what opened it — `FloatingFocusManager`'s
+  // `returnFocus`, the thing hand-rolled modals in the fleet lose.
+  await expect(document.activeElement).toBe(trigger)
+})
+
+/**
+ * Stacking: one scrim behind two dialogs, the lower one `inert`, and
+ * a top-first dismissal on both an outside press and Escape.
+ */
+test("stacked dialogs share one scrim and dismiss top-first", async () => {
+  const { body, canvas } = await mountStory(Stacked)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open the first dialog",
+      role: "button",
+    }),
+  )
+
+  // Captured while it is still the only dialog: once the second opens,
+  // the first goes `inert` and a role query no longer sees it.
+  const first = expectAgentDrivable(body, {
+    name: "First dialog",
+    role: "dialog",
+  })
+
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      name: "Open a second over it",
+      role: "button",
+    }),
+  )
+
+  const second = expectAgentDrivable(body, {
+    name: "Second dialog",
+    role: "dialog",
+  })
+
+  // One scrim for both — the whole point of the provider.
+  await expect(
+    document.body.querySelectorAll(".bg-scrim"),
+  ).toHaveLength(1)
+
+  // The lower dialog is hidden from assistive tech while the top is
+  // open, and focus is trapped in the top.
+  expectHiddenFromAgents(first)
+
+  await waitFor(() => {
+    expect(second.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
+
+  // The top dialog's own controls are actually **hittable** — the
+  // scrim sits a layer below the panels, so it does not intercept a
+  // real click. `userEvent` fires on the element directly and would
+  // miss this; `elementFromPoint` is the check that a covering scrim
+  // fails.
+  const closeButton = expectAgentDrivable(body, {
+    name: "Close this one",
+    role: "button",
+  })
+
+  const buttonRect = closeButton.getBoundingClientRect()
+
+  const atPoint = document.elementFromPoint(
+    buttonRect.left + buttonRect.width / 2,
+    buttonRect.top + buttonRect.height / 2,
+  )
+
+  await expect(
+    atPoint !== null && closeButton.contains(atPoint),
+  ).toBe(true)
+
+  // An outside press closes the top only.
+  await userEvent.click(document.body)
+
+  await waitFor(() => {
+    expect(
+      body.queryByRole("dialog", {
+        name: "Second dialog",
+      }),
+    ).toBeNull()
+  })
+
+  // The first is live again — no longer inert, and the scrim stays.
+  await expect(
+    document.body.querySelectorAll(".bg-scrim"),
+  ).toHaveLength(1)
+
+  const firstAgain = expectAgentDrivable(body, {
+    name: "First dialog",
+    role: "dialog",
+  })
+
+  // Escape closes the last one, and the scrim goes with it.
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+
+  await expect(firstAgain).not.toBeInTheDocument()
+
+  await expect(
+    document.body.querySelector(".bg-scrim"),
+  ).toBeNull()
+})

package/src/Dialog/Dialog.tsx

@@ -0,0 +1,133 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Modal } from "../Modal/Modal.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type DialogSize = "full" | "lg" | "md" | "sm" | "xl"
+
+export type DialogProps = {
+  /**
+   * The scrolling body. Optional: a confirm dialog whose question is
+   * its `heading` and whose answers are its `footer` has no body, and
+   * the old chrome `Modal` (which extended `<dialog>`'s DOM props)
+   * allowed that — `Dialog` keeps it.
+   */
+  children?: ReactNode
+  className?: string
+  /** 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.
+   */
+  isDismissable?: boolean
+  isVisible: boolean
+  /**
+   * Every route out lands here: the close button, Escape, a backdrop
+   * press. Wire it to a `useVisibility()`'s `hide`.
+   */
+  onClose: () => void
+  size?: DialogSize
+}
+
+/**
+ * `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<DialogSize, 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",
+}
+
+/**
+ * `Modal` plus the chrome — heading, a Close button, a scrolling body,
+ * an optional footer, and five sizes. This is what `Modal` *was*
+ * before the M8 rebuild renamed it: a dialog is one kind of modal, so
+ * it takes the specific name and hands the generic one back to the
+ * base layer.
+ *
+ * Everything modal — the portal, the scrim, Escape and outside-press
+ * dismiss, the focus trap, the scroll lock, the stacking — is `Modal`'s
+ * (via `OverlayPanel`), so this component is just the box's contents
+ * and the size class it wants that box to be. `SIZE_CLASS` is composed
+ * over `Modal`'s default surface, which is why `full` carries
+ * `rounded-none` to square off the base's `rounded-lg` at the viewport
+ * edge.
+ *
+ * ### The accessible name
+ *
+ * `heading` is required and is a string, not a `ReactNode`. It names
+ * both the visible header and — through `aria-labelledby` on the
+ * modal — the dialog itself. A dialog with no name is announced as
+ * "dialog" and nothing else, which is what every hand-rolled modal in
+ * the inventory does.
+ */
+export const Dialog = ({
+  children,
+  className,
+  footer,
+  heading,
+  headingLevel = 2,
+  isDismissable = true,
+  isVisible,
+  onClose,
+  size = "md",
+}: DialogProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    <Modal
+      aria-labelledby={headingId}
+      className={toClassName(SIZE_CLASS[size], className)}
+      isDismissable={isDismissable}
+      isVisible={isVisible}
+      onClose={onClose}
+    >
+      <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}
+    </Modal>
+  )
+}

package/src/Field/Field.test.tsx

@@ -180,7 +180,7 @@ test("a slot forwards what an outer slot gave it", async () => {
  * ref and the attribute to have all three arrived.
  */
 test("a slot forwards what an outer slot gave it, in the other order", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Archive path",
@@ -192,8 +192,10 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
   // only have been wired to the `<input>`.
   control.focus()
 
+  // The tip portals to the body now; the `aria-describedby` link still
+  // resolves across the boundary, asserted below.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "Where finished rips are moved.",
     )
   })
@@ -224,7 +226,7 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
  * tip.
  */
 test("a tip is described alongside the field's own text, not instead of it", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Rename pattern",
@@ -237,7 +239,7 @@ test("a tip is described alongside the field's own text, not instead of it", asy
   // tip is missing, and the reason this is testable without a
   // pointer at all.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "A JavaScript regular expression.",
     )
   })

package/src/Lightbox/Lightbox.mdx

@@ -10,10 +10,11 @@ A thumbnail that opens its own full-size view. Three apps hand-roll this — a p
 a still, a scan the operator wants to read — and none get the focus trap or the scroll
 lock right, because the interesting part is not the overlay, it is the dialog underneath.
 
-So a `Lightbox` is a **skin over `Modal`**, not a second dialog. `Modal` owns
-`showModal()`, the top layer, Escape, the `::backdrop` scrim and `lockScrollBehind`;
-this adds the image-specific part — a `cursor-zoom-in` trigger and an `object-contain`
-image clamped to the viewport, so a 2:3 poster and a 16:9 still both land whole.
+So a `Lightbox` is a **skin over `Dialog`**, not a second dialog. `Dialog` (through
+`Modal`/`OverlayPanel`) owns the portal, the scrim, Escape, the focus trap and
+`lockScrollBehind`; this adds the image-specific part — a `cursor-zoom-in` trigger and an
+`object-contain` image clamped to the viewport, so a 2:3 poster and a 16:9 still both land
+whole.
 
 <Canvas of={LightboxStories.Default} />
 
@@ -54,9 +55,9 @@ unread; the caller is the one truth.
 ## What it inherits, and does not re-test
 
 Escape, the focus trap, focus restore to the trigger, the scrim and the scroll lock are
-all `Modal`'s, asserted in `Modal`'s own tests. The lightbox's tests assert only the skin:
-that the thumbnail opens the enlarged image, that the caption rides along, and that the
-contract `Modal` guarantees is not quietly dropped by the wrapper — Escape → `onClose`,
-and focus back to the thumbnail.
+all `Dialog`'s (via `Modal`), asserted in their own tests. The lightbox's tests assert only
+the skin: that the thumbnail opens the enlarged image, that the caption rides along, and
+that the contract `Dialog` guarantees is not quietly dropped by the wrapper — Escape →
+`onClose`, and focus back to the thumbnail.
 
 <Canvas of={LightboxStories.Interactive} />

package/src/Lightbox/Lightbox.stories.tsx

@@ -66,8 +66,8 @@ export const WithCaption: Story = {
 
 /**
  * Boards here are a trigger plus one open overlay, not a grid — a
- * lightbox is a `Modal` underneath, and two dialogs in the top layer
- * side by side is not a thing the platform can do.
+ * lightbox is a `Dialog` underneath, and a dialog covers the viewport,
+ * so two side by side is not the real arrangement.
  */
 export const AllStates: Story = {
   render: () => (
@@ -106,8 +106,8 @@ const ControlledDemo = (): ReactNode => {
         alt="THE OUTFIT poster"
         caption="Opened from a button, not the image"
         isOpen={isVisible}
-        onOpenChange={(isOpen) => {
-          if (!isOpen) {
+        onOpenChange={(isNextOpen) => {
+          if (!isNextOpen) {
             hide()
           }
         }}
@@ -122,7 +122,7 @@ export const Controlled: Story = {
 }
 
 /**
- * The keyboard contract, inherited from `Modal` and asserted here so
+ * The keyboard contract, inherited from `Dialog` and asserted here so
  * the skin cannot quietly drop it: the trigger opens, Escape routes
  * through `onClose`, and focus returns to the thumbnail button.
  */