@charcuterie/ui 0.1.0

package/src/Modal/Modal.mdx

@@ -0,0 +1,113 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ModalStories from "./Modal.stories";
+
+<Meta of={ModalStories} />
+
+# Modal
+
+Four repos, and **plex-channels and ripdeck arrived at native `<dialog>` independently**
+before this library existed. That is the design, not 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 on.
+
+<Canvas of={ModalStories.Default} />
+
+## Props
+
+<Controls />
+
+## The one thing a component has to add
+
+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
+here — `isVisible` is the truth, and an effect makes the element agree with it. Nothing
+reads `dialogElement.open` as state; it is read only to avoid calling a method that would
+throw.
+
+```tsx
+const { hide, isVisible, show } = useVisibility()
+
+<Button onClick={show}>Stop the rip</Button>
+
+<Modal heading="Stop the rip?" isVisible={isVisible} onClose={hide}>
+  …
+</Modal>
+```
+
+`onClose` is every route out — the close button, Escape, a backdrop press — so there is
+one place to wire and no way to end up with the element shut and the state still open.
+
+## No portal, and that is load-bearing
+
+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:
+
+> 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 modal. It would not find
+> a portalled one, and every story here would have to reach for `screen` and give up its
+> scoping.
+
+The same reasoning is why `Popover` uses `popover="manual"` rather than a portal.
+
+## `open:flex`, not `flex`
+
+A closed `<dialog>` is hidden by a UA rule, and any `display: flex` of ours beats it — so
+a modal laid out with a plain `flex` renders permanently, in the page flow, with no error
+anywhere. The layout is therefore behind Tailwind's `open:` variant, keyed on the `[open]`
+attribute the browser manages.
+
+<Canvas of={ModalStories.AllVariants} />
+
+## What a story cannot press
+
+`play`'s `userEvent` is `@testing-library/user-event`, which dispatches **untrusted**
+events, and a browser runs a default action only for trusted input. So a synthetic Escape
+does not make a native `<dialog>` fire `cancel` — it does nothing at all, and a story
+asserting "Escape did not close the non-dismissable dialog" would pass for the wrong
+reason forever.
+
+The stories dispatch the close request where the browser would raise it instead, which
+splits the contract honestly: keystroke → `cancel` is the platform's and is not ours to
+test; everything downstream of `cancel` is ours and is asserted. `AllStates` pairs it with
+a differential — the dialog that refuses the close request is then closed by its own
+button — because "still open" is also true of a dialog nothing can close at all.
+
+<Canvas of={ModalStories.AllStates} />
+
+## `isDismissable={false}` cancels, it does not ignore
+
+Escape is `preventDefault`ed rather than dropped. Letting the browser close a dialog the
+app said was not dismissable would leave `isVisible` true and the element shut — the exact
+desync this component exists to prevent.
+
+## Scroll behind it is locked, and the count is why
+
+`showModal()` makes the page `inert` and then lets you scroll it anyway. The lock is a
+counted module-level one rather than a hook, because nested dialogs are legal and a naive
+lock/unlock pair has the inner dialog's cleanup unlock the page while the outer is still
+open. The release is idempotent, because StrictMode runs an effect's cleanup twice.
+
+## `dvh`, and the scrim
+
+Every size clamps at `85dvh`; `full` takes the lot. `dvh` rather than `vh` because on a
+phone the two differ by the address bar, and a dialog whose footer is under it is a dialog
+with no buttons.
+
+`::backdrop` reads `--color-scrim`, which is a **variant** token: `legible` dims at 0.84
+and `daylight` at 0.66, because how hard a direction separates a dialog from the page is
+exactly the sort of thing a visual direction decides. ePaper's is `transparent` — a panel
+with no opacity cannot dim, so it says so instead of faking it. The `Responsive` story
+asserts the computed `::backdrop` colour is really there, since a `var()` that failed to
+inherit would just look like a design choice.
+
+<Canvas of={ModalStories.Responsive} />
+
+## A modal is not a container-query citizen
+
+It gets no `ContainerBoard`. Its size is measured against the viewport by definition — it
+is the thing covering the viewport — so boarding it at three container widths would be
+measuring something with no bearing on it.
+
+<Canvas of={ModalStories.Interactive} />

package/src/Modal/Modal.stories.tsx

@@ -0,0 +1,272 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import { StoryRow } from "../board.storyHelpers.tsx"
+import type { ModalSize } from "./Modal.tsx"
+import { Modal } from "./Modal.tsx"
+
+const meta = {
+  title: "Components/Modal",
+  component: Modal,
+  parameters: { layout: "padded" },
+  argTypes: {
+    size: toStoryChoice([
+      "sm",
+      "md",
+      "lg",
+      "xl",
+      "full",
+    ] as const),
+  },
+  args: {
+    headingLevel: 2,
+    isDismissable: true,
+    size: "md",
+  },
+} satisfies Meta<typeof Modal>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Every board here is triggers-plus-one-open-dialog rather than a
+ * grid, and that is the component rather than the stories being
+ * awkward: `showModal()` puts a dialog in the **top layer**, so two
+ * of them side by side is not a thing the platform can do. What the
+ * boards show instead is the real arrangement — a page, a scrim,
+ * and one dialog over both.
+ *
+ * `footer` is a function of `hide` because a dialog's own buttons
+ * are the normal way out of it, and they need the same `hide` the
+ * close button gets. One `useVisibility` per demo, no second source
+ * of truth.
+ */
+const ModalDemo = ({
+  buttonLabel,
+  children,
+  footer,
+  heading,
+  isDismissable = true,
+  size,
+}: {
+  buttonLabel: string
+  children?: ReactNode
+  footer?: (hide: () => void) => ReactNode
+  heading: string
+  isDismissable?: boolean
+  size?: ModalSize
+}): ReactNode => {
+  const { hide, isVisible, show } = useVisibility()
+
+  return (
+    <>
+      <Button appearance="soft" onClick={show} size="sm">
+        {buttonLabel}
+      </Button>
+
+      <Modal
+        footer={footer?.(hide)}
+        heading={heading}
+        isDismissable={isDismissable}
+        isVisible={isVisible}
+        onClose={hide}
+        size={size}
+      >
+        {children ?? (
+          <p className="text-content-secondary text-sm">
+            MakeMKV reported a read error on title 4. The
+            rip can continue with the remaining eight
+            titles, or stop here and keep what has
+            completed.
+          </p>
+        )}
+      </Modal>
+    </>
+  )
+}
+
+export const Default: Story = {
+  args: {
+    heading: "Bay 3",
+    isVisible: false,
+    onClose: () => {},
+  },
+  render: () => (
+    <ModalDemo
+      buttonLabel="Show the read error"
+      heading="Read error on title 4"
+    />
+  ),
+}
+
+const SIZES: ModalSize[] = ["sm", "md", "lg", "xl", "full"]
+
+export const AllVariants: Story = {
+  args: {
+    heading: "Bay 3",
+    isVisible: false,
+    onClose: () => {},
+  },
+  render: () => (
+    <StoryRow>
+      {SIZES.map((size) => (
+        <ModalDemo
+          buttonLabel={`Open ${size}`}
+          heading={`Read error — ${size}`}
+          key={size}
+          size={size}
+        />
+      ))}
+    </StoryRow>
+  ),
+}
+
+export const AllStates: Story = {
+  args: {
+    heading: "Bay 3",
+    isVisible: false,
+    onClose: () => {},
+  },
+  render: () => (
+    <StoryRow>
+      <ModalDemo
+        buttonLabel="With a footer"
+        footer={(hide) => (
+          <>
+            <Button
+              appearance="soft"
+              intent="neutral"
+              onClick={hide}
+              size="sm"
+            >
+              Keep going
+            </Button>
+
+            <Button intent="danger" size="sm">
+              Stop the rip
+            </Button>
+          </>
+        )}
+        heading="Stop the rip?"
+      />
+
+      <ModalDemo
+        buttonLabel="Not dismissable"
+        footer={(hide) => (
+          <>
+            <Button
+              appearance="soft"
+              intent="neutral"
+              onClick={hide}
+              size="sm"
+            >
+              Keep the titles
+            </Button>
+
+            <Button intent="danger" size="sm">
+              Erase and re-rip
+            </Button>
+          </>
+        )}
+        heading="This erases eight completed titles"
+        isDismissable={false}
+      />
+
+      <ModalDemo
+        buttonLabel="Long body"
+        heading="MakeMKV log"
+      >
+        <div className="flex flex-col gap-2">
+          {Array.from(
+            { length: 24 },
+            (_, index) =>
+              `14:0${index % 10}:22  title ${
+                index + 1
+              }  AACS handshake complete, reading…`,
+          ).map((line) => (
+            <p
+              className="font-mono text-content-secondary text-xs"
+              key={line}
+            >
+              {line}
+            </p>
+          ))}
+        </div>
+      </ModalDemo>
+    </StoryRow>
+  ),
+}
+
+/**
+ * A modal is the one surface in this library that is **not** a
+ * container-query citizen, so it gets no `ContainerBoard`. Its size
+ * is measured against the viewport by definition — it is the thing
+ * covering the viewport — and boarding it at three container widths
+ * would be measuring something that has no bearing on it.
+ *
+ * What does vary is the clamp: every size caps at `85dvh`, and
+ * `full` takes the lot. `dvh` rather than `vh` because on a phone
+ * the two differ by the address bar, and a dialog whose footer is
+ * underneath it is a dialog with no buttons.
+ */
+export const Responsive: Story = {
+  args: {
+    heading: "Bay 3",
+    isVisible: false,
+    onClose: () => {},
+  },
+  render: () => (
+    <ModalDemo
+      buttonLabel="Open full-bleed"
+      heading="MakeMKV log — full"
+      size="full"
+    >
+      <p className="text-content-secondary text-sm">
+        `full` is the kiosk and phone case: the dialog is
+        the screen, so there is nothing behind it worth
+        showing.
+      </p>
+    </ModalDemo>
+  ),
+}
+
+/**
+ * The keyboard contract, driven. `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.
+ */
+export const Interactive: Story = {
+  args: {
+    heading: "Bay 3",
+    isVisible: false,
+    onClose: () => {},
+  },
+  render: () => (
+    <ModalDemo
+      buttonLabel="Stop the rip"
+      footer={(hide) => (
+        <>
+          <Button
+            appearance="soft"
+            intent="neutral"
+            onClick={hide}
+            size="sm"
+          >
+            Keep going
+          </Button>
+
+          <Button intent="danger" size="sm">
+            Stop it now
+          </Button>
+        </>
+      )}
+      heading="Stop the rip?"
+    />
+  ),
+}

package/src/Modal/Modal.test.tsx

@@ -0,0 +1,248 @@
+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 } 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 }),
+  )
+}
+
+test("the dialog is reachable from a scoped query", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Show the read error",
+      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, {
+    name: "Read error on title 4",
+    role: "dialog",
+  })
+
+  await expect(dialog).toHaveAttribute("open")
+
+  // The addon's own axe pass fired before any of this was clicked,
+  // so the *open* dialog audits itself.
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("size is a real width, not a class that happens to be there", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open lg",
+      role: "button",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(canvas, {
+    name: "Read error — lg",
+    role: "dialog",
+  })
+
+  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",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(canvas, {
+    name: "This erases eight completed titles",
+    role: "dialog",
+  })
+
+  // 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 expect(dialog).toHaveAttribute("open")
+
+  // 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 waitFor(() => {
+    expect(canvas.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" }),
+  )
+
+  const log = expectAgentDrivable(canvas, {
+    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(
+    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 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 trigger = expectAgentDrivable(canvas, {
+    name: "Stop the rip",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  const dialog = expectAgentDrivable(canvas, {
+    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,
+  )
+
+  requestClose(dialog)
+
+  await waitFor(() => {
+    expect(canvas.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)
+})