@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.0

package/src/Component/CookieConsent/CookieConsent.tsx

@@ -0,0 +1,83 @@
+import { JSX, PropsWithChildren, useEffect, useId, useRef } from "react"
+import classNames from "classnames"
+import CookieCompliance from "../../Utility/Elements/cookie-compliance"
+
+type CookieConsentProps = PropsWithChildren & {
+  id?: string
+  acceptLabel?: string
+  rejectLabel?: string
+  moreLabel?: string
+  moreHref?: string
+  waitRemove?: number
+  className?: string
+}
+
+const CookieConsent = ({
+  id,
+  children,
+  acceptLabel = "Accept",
+  rejectLabel = "Reject",
+  moreLabel = "Learn more",
+  moreHref,
+  waitRemove = 0,
+  className,
+}: CookieConsentProps): JSX.Element => {
+  const rId = useId()
+  const uniqueId = id || rId
+  const ref = useRef<HTMLDivElement>(null)
+
+  // Delegates to the same CookieCompliance utility the Twig/Web Component
+  // stack uses — this component owns no consent logic itself.
+  useEffect(() => {
+    if (!ref.current) return undefined
+    const compliance = new CookieCompliance(ref.current)
+    compliance.init()
+    return () => compliance.destroy()
+  }, [])
+
+  const MoreTag = moreHref ? "a" : "button"
+
+  return (
+    <div
+      ref={ref}
+      id={uniqueId}
+      className={classNames("mx-cookie-consent", className)}
+      // eslint-disable-next-line jsx-a11y/prefer-tag-over-role
+      role="dialog"
+      aria-live="polite"
+      aria-label="Cookie consent"
+      data-wait-remove={waitRemove}
+      inert
+    >
+      <div className="mx-cookie-consent__inner">
+        <div className="mx-cookie-consent__content">{children}</div>
+        <div className="mx-cookie-consent__actions">
+          {moreLabel && (
+            <MoreTag
+              className="mx-button mx-button--light"
+              type={moreHref ? undefined : "button"}
+              href={moreHref}
+              target={moreHref ? "_blank" : undefined}
+              rel={moreHref ? "noopener noreferrer" : undefined}
+              data-cookie-more=""
+            >
+              {moreLabel}
+            </MoreTag>
+          )}
+          <button
+            className="mx-button mx-button--dark mx-button--outline"
+            type="button"
+            data-cookie-reject=""
+          >
+            {rejectLabel}
+          </button>
+          <button className="mx-button mx-button--dark" type="button" data-cookie-accept="">
+            {acceptLabel}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default CookieConsent

package/src/Component/CookieConsent/Elements/CookieConsent.ts

@@ -0,0 +1,38 @@
+/**
+ * CookieConsent
+ * @file Wires the markup up to the existing `CookieCompliance` utility
+ * (see `Utility/Elements/cookie-compliance.ts`) — this element owns no
+ * consent logic itself, it just instantiates and cleans up that class
+ * against its own DOM.
+ */
+
+import CookieCompliance from "../../../Utility/Elements/cookie-compliance"
+
+export default class CookieConsent extends HTMLElement {
+  internals_: ElementInternals
+  compliance: CookieCompliance
+
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+  }
+
+  connectedCallback(): void {
+    this.compliance = new CookieCompliance(this)
+    this.compliance.init()
+  }
+
+  disconnectedCallback(): void {
+    this.compliance?.destroy()
+  }
+}
+
+if (!customElements.get("mx-cookie-consent")) {
+  customElements.define("mx-cookie-consent", CookieConsent)
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "mx-cookie-consent": CookieConsent
+  }
+}

package/src/Component/CookieConsent/README.md

@@ -0,0 +1,150 @@
+# Cookie Consent
+
+A site-wide banner asking visitors to accept or reject non-essential cookies. Fixed to the bottom of the viewport, rendered once per page.
+
+This component owns no consent logic itself — Twig/Web Component and React both delegate entirely to the existing **`CookieCompliance`** utility (`Utility/Elements/cookie-compliance.ts`, documented in `docs/API.md`). This component just renders markup that utility expects and wires it up, so there is exactly one implementation of the actual accept/reject/bot-detection/cookie logic shared by both stacks.
+
+**How `CookieCompliance` decides what to do on load:**
+
+- Bots and visitors with `DoNotTrack` enabled: the banner is removed from the DOM immediately, no cookie is set.
+- Consent already recorded (`has-cookie-consent` cookie is `"true"` or `"false"`): the banner stays `inert` and hidden — nothing changes.
+- Otherwise: the banner's `inert` attribute is removed, revealing it.
+
+Accepting or rejecting sets the `has-cookie-consent` cookie (`"true"`/`"false"`) and removes the banner from the DOM (after an optional delay). Rejecting also clears any existing analytics tracking cookies (`_ga`, `_gid`, `__utm*`, etc). Other scripts should check `window.CookieCompliance?.hasConsent()` before initialising tracking.
+
+**The "more info" button:** per the existing `CookieCompliance` implementation, clicking it clears the `has-cookie-consent` cookie (via `data-cookie-more`) rather than navigating anywhere — it does not accept, reject, or hide the banner. Pass `moreHref` to render it as a link to your cookie policy instead (opens in a new tab); the cookie-clearing click handler still fires either way, so returning to the tab shows the banner again if no explicit choice was made since.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/CookieConsent/cookie-consent.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/CookieConsent/cookie-consent.twig' with {
+  content: '<p>We use cookies to improve your experience and analyse site traffic.</p>',
+  moreHref: '/cookie-policy',
+} %}
+```
+
+**cookie-consent.twig props:**
+
+| Prop          | Type     | Default               | Description                                                                     |
+| ------------- | -------- | --------------------- | ------------------------------------------------------------------------------- |
+| `id`          | `string` | `"cookie-compliance"` | Element id. Leave as the default unless you have a reason to change it          |
+| `content`     | `string` | —                     | Main body content (HTML)                                                        |
+| `acceptLabel` | `string` | `"Accept"`            | Accept button text                                                              |
+| `rejectLabel` | `string` | `"Reject"`            | Reject button text                                                              |
+| `moreLabel`   | `string` | `"Learn more"`        | "More info" button/link text                                                    |
+| `moreHref`    | `string` | —                     | If set, renders "more info" as an `<a target="_blank">` instead of a `<button>` |
+| `waitRemove`  | `number` | —                     | Milliseconds to wait before removing the banner from the DOM after a choice     |
+
+Registers as `<mx-cookie-consent>` — import the element to activate its behaviour:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/CookieConsent/Elements/CookieConsent"
+```
+
+---
+
+## HTML + Web Component
+
+The Web Component just instantiates `CookieCompliance` against itself — no state of its own:
+
+```html
+<mx-cookie-consent
+  id="cookie-compliance"
+  class="mx-cookie-consent"
+  role="dialog"
+  aria-live="polite"
+  aria-label="Cookie consent"
+  inert
+>
+  <div class="mx-cookie-consent__inner">
+    <div class="mx-cookie-consent__content">
+      <p>We use cookies to improve your experience and analyse site traffic.</p>
+    </div>
+    <div class="mx-cookie-consent__actions">
+      <button class="mx-button mx-button--outline" type="button" data-cookie-more>
+        Learn more
+      </button>
+      <button class="mx-button mx-button--outline" type="button" data-cookie-reject>Reject</button>
+      <button class="mx-button" type="button" data-cookie-accept>Accept</button>
+    </div>
+  </div>
+</mx-cookie-consent>
+```
+
+`<mx-cookie-consent>` must be rendered with the `inert` attribute already present — `CookieCompliance.init()` removes it if (and only if) the banner should be shown. There is no default-visible state: without JS, the banner never appears (`.mx-cookie-consent[inert] { display: none }`).
+
+**Required attributes** (unchanged from `CookieCompliance`'s own contract — see `docs/API.md`):
+
+| Attribute            | Element     | Purpose                                            |
+| -------------------- | ----------- | -------------------------------------------------- |
+| `data-cookie-accept` | button/link | Accept button                                      |
+| `data-cookie-reject` | button/link | Reject button                                      |
+| `data-cookie-more`   | button/link | "More info" button (see behaviour note above)      |
+| `data-wait-remove`   | banner root | ms delay before the banner is removed from the DOM |
+
+---
+
+## React
+
+```tsx
+import { CookieConsent } from "@pnx-mixtape/mxds/react"
+
+;<CookieConsent moreHref="/cookie-policy">
+  We use cookies to improve your experience and analyse site traffic.
+</CookieConsent>
+```
+
+**`CookieConsent` props:**
+
+| Prop          | Type     | Default                      | Description                                                                     |
+| ------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------- |
+| `id`          | `string` | auto-generated via `useId()` | Element id, passed straight through to `CookieCompliance`                       |
+| `acceptLabel` | `string` | `"Accept"`                   | Accept button text                                                              |
+| `rejectLabel` | `string` | `"Reject"`                   | Reject button text                                                              |
+| `moreLabel`   | `string` | `"Learn more"`               | "More info" button/link text                                                    |
+| `moreHref`    | `string` | —                            | If set, renders "more info" as an `<a target="_blank">` instead of a `<button>` |
+| `waitRemove`  | `number` | `0`                          | Milliseconds to wait before removing the banner from the DOM after a choice     |
+| `className`   | `string` | —                            | Extra class on the root                                                         |
+
+### React ⇄ Twig parity
+
+- Both stacks are progressive-enhancement-only: `CookieCompliance` is instantiated against the rendered root (`connectedCallback` for the Web Component, a `useEffect` for React) and owns all behaviour from there. Neither stack re-implements the accept/reject/bot-detection logic.
+- React always mounts with `inert` for one tick, exactly like the server-rendered Twig markup, so there's no visible flash before `CookieCompliance.init()` decides whether to reveal it.
+
+---
+
+## Modifiers
+
+This component has no BEM modifier classes.
+
+---
+
+## Accessibility
+
+- The banner root has `role="dialog"` and `aria-live="polite"` so its appearance is announced, plus `aria-label="Cookie consent"`.
+- Before `CookieCompliance` decides to show it, the banner carries the `inert` attribute — removing it from the accessibility tree and tab order entirely (stronger than `aria-hidden`, since it also blocks focus/pointer events on descendants).
+- All three actions are real `<button type="button">` elements (or an `<a>` for "more info" when `moreHref` is set), so they're reachable via standard keyboard navigation without any custom key handling.
+- The banner is fixed to the bottom of the viewport — verify it doesn't obscure other fixed/sticky UI (e.g. a sticky footer nav) at your breakpoints.
+
+---
+
+## Customisation
+
+Overridable custom properties (set on `.mx-cookie-consent` or an ancestor):
+
+| Property                      | Default               | Description                  |
+| ----------------------------- | --------------------- | ---------------------------- |
+| `--cookie-consent-background` | `--colour-background` | Banner background            |
+| `--cookie-consent-foreground` | `--colour-foreground` | Banner text colour           |
+| `--cookie-consent-shadow`     | `--box-shadow`        | Drop shadow above the banner |
+| `--cookie-consent-z-index`    | `100`                 | Stacking order               |

package/src/Component/CookieConsent/__snapshots__/CookieConsent.stories.ts.snap

@@ -0,0 +1,34 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Cookie Consent 1`] = `
+"
+<mx-cookie-consent class="mx-cookie-consent" role="dialog" aria-live="polite" aria-label="Cookie consent" id="cookie-compliance">
+  <div class="mx-cookie-consent__inner">
+    <div class="mx-cookie-consent__content mx-rich-text mx-vertical-flow">
+      <p>We use cookies to improve your experience and analyse site traffic.</p>
+    </div>
+    <div class="mx-cookie-consent__actions">
+            <button class="mx-button mx-button--dark mx-button--outline" type="button" data-cookie-reject="">Reject</button>
+      <button class="mx-button mx-button--dark" type="button" data-cookie-accept="">Accept</button>
+    </div>
+  </div>
+</mx-cookie-consent>
+"
+`;
+
+exports[`With Policy Link 1`] = `
+"
+<mx-cookie-consent class="mx-cookie-consent" role="dialog" aria-live="polite" aria-label="Cookie consent" id="cookie-compliance">
+  <div class="mx-cookie-consent__inner">
+    <div class="mx-cookie-consent__content mx-rich-text mx-vertical-flow">
+      <p>We use cookies to improve your experience and analyse site traffic.</p>
+    </div>
+    <div class="mx-cookie-consent__actions">
+                        <a class="mx-button mx-button--light" href="/cookie-policy" target="_blank" rel="noopener noreferrer" data-cookie-more="">Learn more</a>
+                    <button class="mx-button mx-button--dark mx-button--outline" type="button" data-cookie-reject="">Reject</button>
+      <button class="mx-button mx-button--dark" type="button" data-cookie-accept="">Accept</button>
+    </div>
+  </div>
+</mx-cookie-consent>
+"
+`;

package/src/Component/CookieConsent/__snapshots__/CookieConsent.stories.tsx.snap

@@ -0,0 +1,5 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Cookie Consent 1`] = `"<div id="cookie-compliance" class="mx-cookie-consent" role="dialog" aria-live="polite" aria-label="Cookie consent" data-wait-remove="0"><div class="mx-cookie-consent__inner"><div class="mx-cookie-consent__content"><p>We use cookies to improve your experience and analyse site traffic.</p></div><div class="mx-cookie-consent__actions"><button class="mx-button mx-button--light" type="button" data-cookie-more="">Learn more</button><button class="mx-button mx-button--dark mx-button--outline" type="button" data-cookie-reject="">Reject</button><button class="mx-button mx-button--dark" type="button" data-cookie-accept="">Accept</button></div></div></div>"`;
+
+exports[`With Policy Link 1`] = `"<div id="cookie-compliance" class="mx-cookie-consent" role="dialog" aria-live="polite" aria-label="Cookie consent" data-wait-remove="0"><div class="mx-cookie-consent__inner"><div class="mx-cookie-consent__content"><p>We use cookies to improve your experience and analyse site traffic.</p></div><div class="mx-cookie-consent__actions"><a class="mx-button mx-button--light" href="/cookie-policy" target="_blank" rel="noopener noreferrer" data-cookie-more="">Learn more</a><button class="mx-button mx-button--dark mx-button--outline" type="button" data-cookie-reject="">Reject</button><button class="mx-button mx-button--dark" type="button" data-cookie-accept="">Accept</button></div></div></div>"`;

package/src/Component/CookieConsent/cookie-consent.css

@@ -0,0 +1,44 @@
+/**
+ * CookieConsent
+ */
+
+@layer design-system.defaults {
+  mx-cookie-consent {
+    display: block;
+  }
+}
+
+@layer design-system.components {
+  /* @public --cookie-consent-background --cookie-consent-foreground --cookie-consent-shadow --cookie-consent-z-index */
+  .mx-cookie-consent {
+    position: fixed;
+    inset-block-end: 0;
+    inset-inline: 0;
+    z-index: var(--cookie-consent-z-index, 100);
+    background-color: var(--cookie-consent-background, var(--colour-background));
+    color: var(--cookie-consent-foreground, var(--colour-foreground));
+    box-shadow: var(--cookie-consent-shadow, var(--box-shadow));
+
+    &[inert] {
+      display: none;
+    }
+  }
+
+  .mx-cookie-consent__inner {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--gap-s);
+    margin-inline: auto;
+    padding-block: var(--spacing-s);
+    padding-inline: var(--spacing-m);
+  }
+
+  .mx-cookie-consent__actions {
+    display: flex;
+    flex-wrap: wrap;
+    flex-shrink: 0;
+    gap: var(--spacing-xs);
+  }
+}

package/src/Component/CookieConsent/cookie-consent.entry.js

@@ -0,0 +1 @@
+import "./Elements/CookieConsent"

package/src/Component/CookieConsent/cookie-consent.twig

@@ -0,0 +1,27 @@
+{% set attributes = (attributes ?? create_attribute())
+  .addClass('mx-cookie-consent')
+  .setAttribute('role', 'dialog')
+  .setAttribute('aria-live', 'polite')
+  .setAttribute('aria-label', label|default('Cookie consent')) %}
+{% if waitRemove is not empty %}
+  {% set attributes = attributes.setAttribute('data-wait-remove', waitRemove) %}
+{% endif %}
+
+<mx-cookie-consent{{ attributes }} id="{{ id|default('cookie-compliance') }}" inert>
+  <div class="mx-cookie-consent__inner">
+    <div class="mx-cookie-consent__content mx-rich-text mx-vertical-flow">
+      {{ content }}
+    </div>
+    <div class="mx-cookie-consent__actions">
+      {% if moreLabel %}
+        {% if moreHref %}
+          <a class="mx-button mx-button--light" href="{{ moreHref }}" target="_blank" rel="noopener noreferrer" data-cookie-more>{{ moreLabel }}</a>
+        {% else %}
+          <button class="mx-button mx-button--light" type="button" data-cookie-more>{{ moreLabel }}</button>
+        {% endif %}
+      {% endif %}
+      <button class="mx-button mx-button--dark mx-button--outline" type="button" data-cookie-reject>{{ rejectLabel|default('Reject') }}</button>
+      <button class="mx-button mx-button--dark" type="button" data-cookie-accept>{{ acceptLabel|default('Accept') }}</button>
+    </div>
+  </div>
+</mx-cookie-consent>

package/src/Component/Dialog/Components/DialogCloseButton.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-210
+// source=src/Component/Dialog/Components/DialogCloseButton.tsx
+// component=DialogCloseButton
+import figma from "figma"
+
+// No props — reads handleClose from useDialog() context.
+export default {
+  example: figma.code`<DialogCloseButton />`,
+  imports: ['import { DialogCloseButton } from "@pnx-mixtape/mxds/react"'],
+  id: "dialog-close-button",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Dialog/Components/DialogCloseButton.tsx

@@ -5,7 +5,6 @@ const DialogCloseButton = (): JSX.Element => {
   const { handleClose } = useDialog()
   return (
     <button
-      autoFocus
       onClick={handleClose}
       className="mx-button mx-button--icon-only mx-icon mx-icon--close"
       type="button"

package/src/Component/Dialog/Components/DialogContent.figma.ts

@@ -0,0 +1,19 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-212
+// source=src/Component/Dialog/Components/DialogContent.tsx
+// component=DialogContent
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+// The old fixed "Content" text layer was replaced with a real SLOT property of the
+// same name — read via getSlot(), not findText()/getString().
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<DialogContent>${content}</DialogContent>`,
+  imports: ['import { DialogContent } from "@pnx-mixtape/mxds/react"'],
+  id: "dialog-content",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Dialog/Components/DialogContent.tsx

@@ -1,7 +1,15 @@
-import { JSX, PropsWithChildren } from "react"
+import { JSX, PropsWithChildren, Ref } from "react"
 
-const DialogContent = ({ children }: PropsWithChildren): JSX.Element => {
-  return <div className="mx-dialog__content mx-vertical-flow">{children}</div>
+type DialogContentProps = PropsWithChildren & {
+  ref?: Ref<HTMLDivElement>
+}
+
+const DialogContent = ({ children, ref }: DialogContentProps): JSX.Element => {
+  return (
+    <div className="mx-dialog__content mx-vertical-flow" ref={ref}>
+      {children}
+    </div>
+  )
 }
 
 export default DialogContent

package/src/Component/Dialog/Dialog.figma.ts

@@ -0,0 +1,40 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-230
+// source=src/Component/Dialog/Dialog.tsx
+// component=Dialog
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const fullscreen = instance.getEnum("Fullscreen", { Off: false, On: true })
+
+const closeButton = instance.findConnectedInstances(
+  node => node.codeConnectId() === "dialog-close-button",
+)[0]
+const content = instance.findConnectedInstances(
+  node => node.codeConnectId() === "dialog-content",
+)[0]
+const closeButtonCode = closeButton
+  ? closeButton.executeTemplate().example
+  : figma.code`<DialogCloseButton />`
+const contentCode = content
+  ? content.executeTemplate().example
+  : figma.code`<DialogContent>Dialog content goes here.</DialogContent>`
+
+const fullscreenProp = fullscreen ? " fullscreen" : ""
+
+// `open` (controls native show()/showModal()) isn't modelled — a Figma frame is
+// inherently "shown". `modal` has NO visual difference from the default state (JS-only:
+// showModal() + native backdrop + body scroll-lock vs show()) — real finding from
+// building this, not representable in a static design, so it's omitted rather than
+// guessed. `onClose` isn't applicable to a static design either.
+export default {
+  example: figma.code`<Dialog${fullscreenProp}>
+  ${closeButtonCode}
+  ${contentCode}
+</Dialog>`,
+  imports: ['import { Dialog, DialogCloseButton, DialogContent } from "@pnx-mixtape/mxds/react"'],
+  id: "dialog",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Dialog/Dialog.stories.ts

@@ -1,5 +1,6 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
-import DrupalAttribute from "drupal-attribute"
+import { expect, waitFor } from "storybook/test"
+import { DrupalAttribute } from "drupal-attribute"
 import Component from "./dialog.twig"
 import "./dialog.css"
 import "./Elements/Dialog"
@@ -37,7 +38,7 @@ const meta: Meta<MxDialogType> = {
     link: Button({
       title: "Let's go",
       modifiers: [ButtonModifiers.DARK],
-      attributes: new DrupalAttribute()?.setAttribute("data-close", ""),
+      attributes: new DrupalAttribute()?.setAttribute("data-close", true),
     }),
   },
   argTypes: {
@@ -114,7 +115,42 @@ type Story = StoryObj<MxDialogType>
 /**
  * Non-modal dialog, that allows interaction outside of it. See [show()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/show)
  */
-export const Dialog: Story = {}
+export const Dialog: Story = {
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const trigger = canvas.getByRole("link", { name: "Open dialog" })
+    const dialogEl = canvasElement.querySelector("dialog") as HTMLDialogElement
+
+    await step("Starts closed", async () => {
+      await expect(dialogEl.open).toBe(false)
+    })
+
+    await step("Opens on trigger click", async () => {
+      await userEvent.click(trigger)
+      await expect(dialogEl.open).toBe(true)
+    })
+
+    await step("Closes on Escape", async () => {
+      await userEvent.keyboard("{Escape}")
+      await expect(dialogEl.open).toBe(false)
+    })
+
+    await step("Opens again; closes on outside click", async () => {
+      await userEvent.click(trigger)
+      await expect(dialogEl.open).toBe(true)
+      await userEvent.click(canvasElement)
+      // The outside-click check runs via a one-shot IntersectionObserver
+      // callback, not synchronously - poll for it to fire.
+      await waitFor(() => expect(dialogEl.open).toBe(false), { timeout: 2000 })
+    })
+
+    await step("Opens again; the [data-close] content button also closes it", async () => {
+      await userEvent.click(trigger)
+      await expect(dialogEl.open).toBe(true)
+      await userEvent.click(canvas.getByRole("button", { name: "Let's go" }))
+      await expect(dialogEl.open).toBe(false)
+    })
+  },
+}
 
 /**
  * Modals display in the top layer and cover all other content (with backdrop). See [showModal()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)

package/src/Component/Dialog/Dialog.stories.tsx

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
 import Component from "./Dialog"
 import DialogContent from "./Components/DialogContent"
 import DialogCloseButton from "./Components/DialogCloseButton"
@@ -38,4 +39,27 @@ const meta: Meta<typeof Component> = {
 
 export default meta
 
-export const Dialog: StoryObj<typeof Component> = {}
+export const Dialog: StoryObj<typeof Component> = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const dialog = canvasElement.querySelector("dialog") as HTMLDialogElement
+    const closeButton = canvas.getByRole("button", { name: "Close dialog" })
+
+    await step("Starts open", async () => {
+      await expect(dialog.open).toBe(true)
+    })
+
+    await step("Close button closes it", async () => {
+      await userEvent.click(closeButton)
+      await expect(dialog.open).toBe(false)
+    })
+
+    await step("Escape does not close a non-modal dialog (native behavior)", async () => {
+      // Reopen directly via the native API - there's no trigger button in
+      // this story, since `open` is normally driven by the parent app.
+      dialog.show()
+      await expect(dialog.open).toBe(true)
+      await userEvent.keyboard("{Escape}")
+      await expect(dialog.open).toBe(true)
+    })
+  },
+}

package/src/Component/Dialog/Dialog.tsx

@@ -35,31 +35,37 @@ const Dialog = ({
   children,
   open = false,
   onClose = defaultOnClose,
-  modal = true,
+  modal = false,
   fullscreen = false,
   ...props
 }: DialogProps): JSX.Element => {
   const dialogRef: RefObject<HTMLDialogElement> = useRef(null)
 
   const handleClose = useCallback(() => {
-    if (!dialogRef.current) return
-    onClose()
-    dialogRef.current.close()
+    dialogRef.current?.close()
   }, [dialogRef])
 
   useEffect(() => {
     if (!dialogRef.current) return
+    const isModal: boolean = modal || fullscreen
 
     if (open) {
-      if (modal || fullscreen) {
+      if (isModal) {
         dialogRef.current.showModal()
+        document.body.classList.add("body--scroll-lock")
       } else {
         dialogRef.current.show()
       }
     } else {
       dialogRef.current.close()
+      if (isModal) document.body.classList.remove("body--scroll-lock")
+    }
+
+    return () => {
+      // Defensive cleanup in case the component unmounts while open.
+      if (isModal) document.body.classList.remove("body--scroll-lock")
     }
-  }, [open, dialogRef])
+  }, [open, modal, fullscreen, dialogRef])
 
   const values = useMemo(
     () => ({ handleClose, ref: dialogRef, open }),
@@ -70,7 +76,7 @@ const Dialog = ({
     <DialogContext value={values}>
       <dialog
         ref={dialogRef}
-        onClose={handleClose}
+        onClose={onClose}
         className={classNames("mx-dialog", {
           "mx-dialog--fullscreen": fullscreen,
         })}