@charcuterie/ui 1.0.1 → 2.0.0

package/src/Modal/Modal.mdx

@@ -6,10 +6,11 @@ import * as ModalStories from "./Modal.stories";
 
 # 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.
+The **base layer**: a backdrop, a focus trap, Escape, and an outside press — and no
+chrome. A dialog is one kind of modal; so is a confirmation, a media lightbox, and
+anything else that wants a scrim over the page. `Modal` is that foundation, and
+[`Dialog`](?path=/docs/components-dialog--docs) is `Modal` plus the
+heading/Close/footer/size chrome the component shipped with before the M8 rebuild.
 
 <Canvas of={ModalStories.Default} />
 
@@ -17,97 +18,43 @@ from the platform, correctly, in every browser the fleet runs on.
 
 <Controls />
 
-## The one thing a component has to add
+## Portalled, not the top layer
 
-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.
+`Modal` renders an `OverlayPanel`, which portals to `document.body`. The old `Modal` rode
+the platform top layer (`<dialog>.showModal()`); this one supersedes that
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)),
+because the top layer cannot escape an `overflow: hidden` ancestor's clipping in every
+case the fleet hit, and a portal does. The objection a portal used to raise — that it
+moves the node out of a scoped query — is answered by `useRole` writing `aria-controls` /
+`aria-labelledby` across the boundary, and by stories scoping panel queries to
+`within(document.body)`.
 
 ```tsx
 const { hide, isVisible, show } = useVisibility()
 
-<Button onClick={show}>Stop the rip</Button>
+<Button onClick={show}>Open</Button>
 
-<Modal heading="Stop the rip?" isVisible={isVisible} onClose={hide}>
-  …
+<Modal aria-label="Read error on title 4" isVisible={isVisible} onClose={hide}>
+  …your own markup…
 </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.
+`onClose` is every route out — 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
+## One accessible name, required
 
-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 `role="dialog"` takes no name from its content, so pass exactly one of `aria-label` or
+`aria-labelledby`. Missing both is a dev-time warning, not a throw.
 
-> 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.
+<Canvas of={ModalStories.Alert} />
 
-The same reasoning is why `Popover` uses `popover="manual"` rather than a portal.
+## Stacking is zero-config, until it is not
 
-## `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.
+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, keep the top live, mark the rest `inert`, and dismiss
+top-first. The scroll lock is ref-counted through the stack, so the page frees only when
+the last modal closes.
 
 <Canvas of={ModalStories.Interactive} />

package/src/Modal/Modal.stories.tsx

@@ -2,29 +2,16 @@ 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",
+    role: "dialog",
   },
 } satisfies Meta<typeof Modal>
 
@@ -33,32 +20,21 @@ 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.
+ * The base layer has no chrome, so a demo supplies its own — the
+ * point being that `Modal` is the backdrop-plus-dismiss-plus-portal
+ * foundation and the content is entirely the caller's. `Dialog` is
+ * the batteries-included version of exactly this.
  */
 const ModalDemo = ({
   buttonLabel,
   children,
-  footer,
-  heading,
-  isDismissable = true,
-  size,
+  label,
+  role,
 }: {
   buttonLabel: string
   children?: ReactNode
-  footer?: (hide: () => void) => ReactNode
-  heading: string
-  isDismissable?: boolean
-  size?: ModalSize
+  label: string
+  role?: "alertdialog" | "dialog"
 }): ReactNode => {
   const { hide, isVisible, show } = useVisibility()
 
@@ -69,21 +45,29 @@ const ModalDemo = ({
       </Button>
 
       <Modal
-        footer={footer?.(hide)}
-        heading={heading}
-        isDismissable={isDismissable}
+        aria-label={label}
         isVisible={isVisible}
         onClose={hide}
-        size={size}
+        role={role}
       >
-        {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>
-        )}
+        <div className="flex flex-col gap-3 p-4">
+          {children ?? (
+            <p className="text-content-secondary text-sm">
+              A bare `Modal`: a scrim, a focus trap, Escape,
+              and an outside press. Everything you see
+              inside is the caller's own markup.
+            </p>
+          )}
+
+          <Button
+            appearance="soft"
+            intent="neutral"
+            onClick={hide}
+            size="sm"
+          >
+            Close
+          </Button>
+        </div>
       </Modal>
     </>
   )
@@ -91,182 +75,65 @@ const ModalDemo = ({
 
 export const Default: Story = {
   args: {
-    heading: "Bay 3",
+    "aria-label": "Read error on title 4",
+    children: null,
     isVisible: false,
     onClose: () => {},
   },
   render: () => (
     <ModalDemo
-      buttonLabel="Show the read error"
-      heading="Read error on title 4"
+      buttonLabel="Open the base modal"
+      label="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.
+ * `role="alertdialog"` is the one configuration the base exposes that
+ * `Dialog` does not surface directly — an interruption the user has
+ * to answer, announced as an alert rather than a plain dialog.
  */
-export const Responsive: Story = {
+export const Alert: Story = {
   args: {
-    heading: "Bay 3",
+    "aria-label": "Confirm erase",
+    children: null,
     isVisible: false,
     onClose: () => {},
   },
   render: () => (
     <ModalDemo
-      buttonLabel="Open full-bleed"
-      heading="MakeMKV log — full"
-      size="full"
+      buttonLabel="Open an alertdialog"
+      label="Confirm erase"
+      role="alertdialog"
     >
       <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.
+        This erases eight completed titles.
       </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.
+ * The keyboard contract, driven. `OverlayPanel`'s
+ * `FloatingFocusManager` traps focus and restores it to the trigger;
+ * `useDismiss` routes Escape and an outside press through `onClose`.
  */
 export const Interactive: Story = {
   args: {
-    heading: "Bay 3",
+    "aria-label": "Stop the rip?",
+    children: null,
     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?"
-    />
+      label="Stop the rip?"
+    >
+      <p className="text-content-secondary text-sm">
+        Escape, an outside press, or the button below all
+        land on the same `onClose`.
+      </p>
+    </ModalDemo>
   ),
 }