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

package/src/Component/Gallery/Gallery.tsx

@@ -0,0 +1,92 @@
+import {
+  JSX,
+  ReactNode,
+  PropsWithChildren,
+  Context,
+  createContext,
+  use,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import classNames from "classnames"
+import Dialog from "../Dialog/Dialog"
+import DialogContent from "../Dialog/Components/DialogContent"
+import DialogCloseButton from "../Dialog/Components/DialogCloseButton"
+
+type GalleryContextValues = {
+  openAt: (index: number) => void
+}
+
+const GalleryContext: Context<GalleryContextValues> = createContext<GalleryContextValues>(null)
+export const useGallery = () => use(GalleryContext)
+
+const findActiveSlide = (root: HTMLElement | null, index: number): HTMLElement | null =>
+  root?.querySelector<HTMLElement>(`.mx-carousel__scrollable > li[data-index="${index}"]`) ?? null
+
+type GalleryProps = PropsWithChildren & {
+  /**
+   * The modal body — a `<Carousel>` for multiple images, or a single
+   * image/element when there's only one. Gallery doesn't build this itself:
+   * bring whatever content fits the set.
+   */
+  content: ReactNode
+  id?: string
+  dialogLabel?: string
+  className?: string
+}
+
+const Gallery = ({
+  children,
+  content,
+  id,
+  dialogLabel = "Image gallery",
+  className,
+}: GalleryProps): JSX.Element => {
+  const rId = useId()
+  const uniqueId = id || rId
+  const [open, setOpen] = useState(false)
+  const [activeIndex, setActiveIndex] = useState(0)
+  const contentRef = useRef<HTMLDivElement>(null)
+
+  // Runs after Dialog's own effect has already called showModal() (child
+  // effects flush before the parent's), so the carousel is laid out and
+  // scrollIntoView measures correctly.
+  useEffect(() => {
+    if (!open) return
+    const slide = findActiveSlide(contentRef.current, activeIndex)
+    if (!slide) return
+    // Carousel marks off-screen slides `inert` via its own IntersectionObserver
+    // — scrollIntoView silently no-ops on an inert element, so clear it first;
+    // Carousel's observer recomputes the correct value once the scroll settles.
+    slide.removeAttribute("inert")
+    ;(slide.querySelector<HTMLElement>("img") ?? slide).scrollIntoView({
+      inline: "start",
+      block: "nearest",
+    })
+  }, [open, activeIndex])
+
+  const openAt = useCallback((index: number): void => {
+    setActiveIndex(index)
+    setOpen(true)
+  }, [])
+
+  const values = useMemo<GalleryContextValues>(() => ({ openAt }), [openAt])
+
+  return (
+    <GalleryContext value={values}>
+      <div className={classNames("mx-gallery", className)} id={uniqueId}>
+        <div className="mx-gallery__preview">{children}</div>
+        <Dialog open={open} fullscreen onClose={() => setOpen(false)} aria-label={dialogLabel}>
+          <DialogContent ref={contentRef}>{content}</DialogContent>
+          <DialogCloseButton />
+        </Dialog>
+      </div>
+    </GalleryContext>
+  )
+}
+
+export default Gallery

package/src/Component/Gallery/README.md

@@ -0,0 +1,221 @@
+# Gallery
+
+A flexible image preview that opens a fullscreen modal carousel of the full set. Gallery doesn't render the preview or the modal body itself — it's a thin composition over **[Dialog](../Dialog/)** and **[Carousel](../Carousel/)** that just wires "click a trigger → open at that index → focus/scroll return to the trigger on close."
+
+**The closed/preview state can be anything** — a grid of thumbnails, a single image, a card, even an embedded carousel — as long as each clickable trigger is a real focusable element (button or link). Gallery doesn't care how many triggers there are or how they're laid out.
+
+**The modal body is whatever you give it** — pass a `<Carousel>` (React) / `carousel.twig` output (Twig) when there's more than one image, or a single image/element when there's only one. Gallery doesn't build this for you: bring whatever fits the set.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Gallery/gallery.css";
+@import "@pnx-mixtape/mxds/src/Component/Dialog/dialog.css";
+@import "@pnx-mixtape/mxds/src/Component/Carousel/carousel.css"; /* only if the modal contains a carousel */
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Gallery/gallery.twig' with {
+  id: 'trip-photos',
+  preview: preview_markup,   {# your own trigger markup — see below #}
+  content: carousel_markup, {# Carousel's rendered output, or a single image #}
+} %}
+```
+
+**gallery.twig props:**
+
+| Prop          | Type     | Default           | Description                                                               |
+| ------------- | -------- | ----------------- | ------------------------------------------------------------------------- |
+| `id`          | `string` | `"gallery"`       | Element id — each preview trigger references it via `aria-controls`       |
+| `preview`     | `string` | —                 | Your own trigger markup (HTML string) — anything, as flexible as you need |
+| `content`     | `string` | —                 | Modal body (HTML string) — a rendered `Carousel`, or a single image       |
+| `dialogLabel` | `string` | `"Image gallery"` | `aria-label` on the `<dialog>`                                            |
+
+Build `preview` yourself, one trigger per image you want directly openable:
+
+```js
+import Gallery from "@mixtape/Component/Gallery/gallery.twig"
+import Carousel from "@mixtape/Component/Carousel/carousel.twig"
+import Image from "@mixtape/Atom/Image/image.twig"
+
+const photos = [
+  { src: "1.jpg", alt: "Photo 1" },
+  { src: "2.jpg", alt: "Photo 2" },
+]
+
+Gallery({
+  id: "trip-photos",
+  preview: photos
+    .map(
+      (photo, index) => `
+      <button type="button" class="mx-gallery__trigger" aria-controls="trip-photos" data-gallery-index="${index}">
+        ${Image(photo)}
+      </button>
+    `,
+    )
+    .join(""),
+  content:
+    photos.length > 1 ? Carousel({ items: photos.map(Image), counter: true }) : Image(photos[0]),
+})
+```
+
+- Each trigger needs `aria-controls="{{ id }}"` (or `href="#{{ id }}"`) — this is [Dialog](../Dialog/)'s own trigger contract, inherited unchanged.
+- `data-gallery-index="N"` tells Gallery which slide to scroll the carousel to when that trigger is clicked. Omit it (defaults to `0`) for a single representative trigger, e.g. a cover photo or card that opens the whole set at the start.
+
+Registers as `<mx-gallery>` — import the element to activate its behaviour:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Gallery/Elements/Gallery"
+```
+
+---
+
+## HTML + Web Component
+
+`<mx-gallery>` **extends** `<mx-dialog>` (see [Dialog](../Dialog/)) — it inherits `showModal()`/`close()`, the focus trap, outside-click-to-close, and Escape-to-close entirely unchanged. It only adds one thing: scrolling a nested `<mx-carousel>` to the clicked trigger's `data-gallery-index` once the dialog is open.
+
+```html
+<mx-gallery class="mx-gallery" id="trip-photos">
+  <div class="mx-gallery__preview">
+    <button
+      type="button"
+      class="mx-gallery__trigger"
+      aria-controls="trip-photos"
+      data-gallery-index="0"
+    >
+      <img src="1-thumb.jpg" alt="Photo 1" />
+    </button>
+    <button
+      type="button"
+      class="mx-gallery__trigger"
+      aria-controls="trip-photos"
+      data-gallery-index="1"
+    >
+      <img src="2-thumb.jpg" alt="Photo 2" />
+    </button>
+  </div>
+
+  <dialog class="mx-dialog mx-dialog--fullscreen" aria-label="Image gallery">
+    <button autofocus class="mx-button mx-button--icon-only mx-icon mx-icon--close" data-close>
+      Close dialog
+    </button>
+    <div class="mx-dialog__content">
+      <mx-carousel class="mx-carousel" role="group" counter>
+        <div class="mx-carousel__buttons" data-buttons hidden>
+          <button class="mx-carousel__prev mx-button mx-button--icon-only" type="button">
+            <span class="sr-only">previous</span>
+            <span class="mx-icon mx-icon--chevron-left"></span>
+          </button>
+          <button class="mx-carousel__next mx-button mx-button--icon-only" type="button">
+            <span class="sr-only">next</span>
+            <span class="mx-icon mx-icon--chevron-right"></span>
+          </button>
+        </div>
+        <ul class="mx-carousel__scrollable">
+          <li><img src="1.jpg" alt="Photo 1" /></li>
+          <li><img src="2.jpg" alt="Photo 2" /></li>
+        </ul>
+        <ol class="mx-carousel__pagination" data-pagination="counter" hidden></ol>
+      </mx-carousel>
+    </div>
+  </dialog>
+</mx-gallery>
+```
+
+**Import the JS** (Gallery + Carousel — Gallery pulls in Dialog automatically since it extends it):
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Carousel/Elements/Carousel"
+import "@pnx-mixtape/mxds/src/Component/Gallery/Elements/Gallery"
+```
+
+With only one image, skip `<mx-carousel>` entirely and put the single image straight in `.mx-dialog__content` — Gallery has nothing to scroll in that case and just opens on it.
+
+---
+
+## React
+
+```tsx
+import { useState } from "react"
+import { Gallery, GalleryTrigger, Carousel } from "@pnx-mixtape/mxds/react"
+
+const photos = [
+  { src: "1.jpg", alt: "Photo 1" },
+  { src: "2.jpg", alt: "Photo 2" },
+]
+
+<Gallery
+  content={<Carousel items={photos.map(photo => <img key={photo.src} {...photo} />)} counter />}
+>
+  {photos.map((photo, index) => (
+    <GalleryTrigger key={photo.src} index={index}>
+      <img src={photo.src} alt={photo.alt} />
+    </GalleryTrigger>
+  ))}
+</Gallery>
+
+// Single image — no carousel needed
+<Gallery content={<img src={photos[0].src} alt={photos[0].alt} />}>
+  <GalleryTrigger index={0}>
+    <img src={photos[0].src} alt={photos[0].alt} />
+  </GalleryTrigger>
+</Gallery>
+```
+
+**`Gallery` props:**
+
+| Prop          | Type        | Default            | Description                                                                       |
+| ------------- | ----------- | ------------------ | --------------------------------------------------------------------------------- |
+| `content`     | `ReactNode` | —                  | Modal body — a `<Carousel>`, or a single image/element                            |
+| `children`    | `ReactNode` | —                  | Preview content — anything; wire triggers with `GalleryTrigger` or `useGallery()` |
+| `id`          | `string`    | auto via `useId()` | Element id                                                                        |
+| `dialogLabel` | `string`    | `"Image gallery"`  | `aria-label` on the dialog                                                        |
+| `className`   | `string`    | —                  | Extra class on the root                                                           |
+
+**`GalleryTrigger` props:** `index: number` (required — which image this trigger opens the carousel at) plus any native `<button>` prop. A thin convenience wrapper around `useGallery().openAt(index)`.
+
+**`useGallery()`** — hook exposing `{ openAt: (index: number) => void }` from context. Use it directly (instead of `GalleryTrigger`) when the trigger needs to be something other than a plain button — e.g. wiring `onClick` onto an existing `Card`.
+
+### React ⇄ Twig parity
+
+- Both stacks are pure composition over Dialog + (optionally) Carousel — neither re-implements focus trapping, focus return, or outside-click/Escape-to-close; that's all inherited/reused unchanged.
+- Twig identifies which slide to open via `data-gallery-index` on the clicked trigger; React via the explicit `index` argument to `openAt`/`GalleryTrigger`. Same idea, idiomatic per stack.
+- In both stacks, scrolling to the target slide happens by querying `.mx-carousel__scrollable > li[data-index="N"]` after the dialog is open — Carousel itself isn't modified and has no "initial slide" concept of its own; it just always renders `data-index` on each `<li>` (see its README).
+- Gotcha worth knowing if you're touching this code: Carousel marks off-screen slides `inert` via its own `IntersectionObserver`, and `scrollIntoView()` silently no-ops on an `inert` element. Gallery clears `inert` on the target slide immediately before scrolling to it — Carousel's own observer recomputes the correct value once the new position settles, so this doesn't fight with Carousel's state.
+
+---
+
+## Modifiers
+
+This component has no BEM modifier classes of its own. Fullscreen styling comes from Dialog's `.mx-dialog--fullscreen`.
+
+---
+
+## Accessibility
+
+Because Gallery reuses Dialog's native `<dialog>` handling, most of this is free:
+
+- **Focus trap**: `showModal()` (used unconditionally by Gallery) traps focus inside the modal.
+- **Focus return + scroll into view**: the browser automatically returns focus to whichever trigger was focused when the dialog opened, and scrolls it back into view if the page scrolled while the dialog was open — this is native `<dialog>`/focus behaviour, not something Gallery implements itself. It only works if each trigger is a real focusable element (a `<button>` or `<a>`, not a `<div>` with a click handler).
+- **Initial focus**: the close button has `autofocus`.
+- **Escape / outside click**: both close the dialog (inherited from Dialog's Web Component; in React, wire `onClose` yourself same as any `Dialog`).
+- Give the modal an accessible name via `dialogLabel` (Twig/WC) or `aria-label`/`dialogLabel` (React) — there's no visible heading by default since the content is just images.
+
+---
+
+## Customisation
+
+Overridable custom properties (set on `.mx-gallery` or an ancestor) — these only affect the default `.mx-gallery__preview` grid layout; skip them entirely if you supply your own preview layout:
+
+| Property                   | Default        | Description                             |
+| -------------------------- | -------------- | --------------------------------------- |
+| `--gallery-item-min-width` | `8rem`         | Minimum width of each preview grid cell |
+| `--gallery-gap`            | `--spacing-xs` | Gap between preview grid cells          |
+
+Dialog and Carousel's own custom properties (`--dialog-background`, `--container-max-width`, etc.) apply to the modal as normal — see their READMEs.

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

@@ -0,0 +1,92 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Grid 1`] = `
+"
+<mx-gallery class="mx-gallery" id="unique-0">
+  <div class="mx-gallery__preview">
+    <button type="button" class="mx-gallery__trigger" aria-controls="unique-0" data-gallery-index="0"><picture>
+    <img src="https://picsum.photos/seed/gallery-0/800/600" alt="Photo 1">
+</picture>
+</button><button type="button" class="mx-gallery__trigger" aria-controls="unique-1" data-gallery-index="1"><picture>
+    <img src="https://picsum.photos/seed/gallery-1/800/600" alt="Photo 2">
+</picture>
+</button><button type="button" class="mx-gallery__trigger" aria-controls="unique-2" data-gallery-index="2"><picture>
+    <img src="https://picsum.photos/seed/gallery-2/800/600" alt="Photo 3">
+</picture>
+</button><button type="button" class="mx-gallery__trigger" aria-controls="unique-3" data-gallery-index="3"><picture>
+    <img src="https://picsum.photos/seed/gallery-3/800/600" alt="Photo 4">
+</picture>
+</button><button type="button" class="mx-gallery__trigger" aria-controls="unique-4" data-gallery-index="4"><picture>
+    <img src="https://picsum.photos/seed/gallery-4/800/600" alt="Photo 5">
+</picture>
+</button><button type="button" class="mx-gallery__trigger" aria-controls="unique-5" data-gallery-index="5"><picture>
+    <img src="https://picsum.photos/seed/gallery-5/800/600" alt="Photo 6">
+</picture>
+</button>
+  </div>
+  <dialog class="mx-dialog mx-dialog--fullscreen" aria-label="Image gallery">
+    <button autofocus="" class="mx-button mx-button--icon-only mx-icon mx-icon--close" data-close="">Close dialog</button>
+    <div class="mx-dialog__content">
+      
+<mx-carousel class="mx-carousel" role="region" aria-roledescription="carousel">
+  <div class="mx-carousel__buttons" data-buttons="" role="group" aria-label="Quick page controls">
+    <button class="mx-carousel__prev mx-button mx-button--icon-only" type="button" disabled="">
+      <span class="sr-only">previous page</span>
+      <span class="mx-icon mx-icon--chevron-left"></span>
+    </button>
+    <button class="mx-carousel__next mx-button mx-button--icon-only" type="button">
+      <span class="sr-only">next page</span>
+      <span class="mx-icon mx-icon--chevron-right"></span>
+    </button>
+  </div>
+  <div class="mx-carousel__scrollable" data-track="" aria-live="off">
+    <picture data-index="0" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-0/800/600" alt="Photo 1">
+</picture>
+<picture data-index="1" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-1/800/600" alt="Photo 2">
+</picture>
+<picture data-index="2" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-2/800/600" alt="Photo 3">
+</picture>
+<picture data-index="3" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-3/800/600" alt="Photo 4">
+</picture>
+<picture data-index="4" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-4/800/600" alt="Photo 5">
+</picture>
+<picture data-index="5" inert="" aria-hidden="true">
+    <img src="https://picsum.photos/seed/gallery-5/800/600" alt="Photo 6">
+</picture>
+
+  </div>
+          <div class="mx-carousel__pagination" data-pagination="counter" hidden="" role="group" aria-label="Page controls"></div>
+  </mx-carousel>
+
+    </div>
+  </dialog>
+</mx-gallery>
+"
+`;
+
+exports[`Single Image 1`] = `
+"
+<mx-gallery class="mx-gallery" id="unique-0">
+  <div class="mx-gallery__preview">
+    <button type="button" class="mx-gallery__trigger" aria-controls="unique-0"><picture>
+    <img src="https://picsum.photos/seed/gallery-0/800/600" alt="Photo 1">
+</picture>
+</button>
+  </div>
+  <dialog class="mx-dialog mx-dialog--fullscreen" aria-label="Image gallery">
+    <button autofocus="" class="mx-button mx-button--icon-only mx-icon mx-icon--close" data-close="">Close dialog</button>
+    <div class="mx-dialog__content">
+      <picture>
+    <img src="https://picsum.photos/seed/gallery-0/800/600" alt="Photo 1">
+</picture>
+
+    </div>
+  </dialog>
+</mx-gallery>
+"
+`;

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

@@ -0,0 +1,5 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Grid 1`] = `"<div class="mx-gallery" id="_r_0_"><div class="mx-gallery__preview"><button type="button" class="mx-gallery__trigger"><img alt="Photo 1" src="https://picsum.photos/seed/gallery-0/800/600"></button><button type="button" class="mx-gallery__trigger"><img alt="Photo 2" src="https://picsum.photos/seed/gallery-1/800/600"></button><button type="button" class="mx-gallery__trigger"><img alt="Photo 3" src="https://picsum.photos/seed/gallery-2/800/600"></button><button type="button" class="mx-gallery__trigger"><img alt="Photo 4" src="https://picsum.photos/seed/gallery-3/800/600"></button><button type="button" class="mx-gallery__trigger"><img alt="Photo 5" src="https://picsum.photos/seed/gallery-4/800/600"></button><button type="button" class="mx-gallery__trigger"><img alt="Photo 6" src="https://picsum.photos/seed/gallery-5/800/600"></button></div><dialog class="mx-dialog mx-dialog--fullscreen" aria-label="Image gallery"><div class="mx-dialog__content mx-vertical-flow"><div class="mx-carousel" role="region" aria-roledescription="carousel" id="_r_1_"><div class="mx-carousel__buttons" hidden="" role="group" aria-label="Quick page controls"><button class="mx-button mx-button--icon-only mx-carousel__prev" type="button" disabled=""><span class="sr-only">previous page</span><span class="mx-icon mx-icon--chevron-left" aria-hidden="true"></span></button><button class="mx-button mx-button--icon-only mx-carousel__next" type="button"><span class="sr-only">next page</span><span class="mx-icon mx-icon--chevron-right" aria-hidden="true"></span></button></div><ul class="mx-carousel__scrollable" aria-live="off"><li data-index="0" inert="" aria-hidden="true"><img alt="Photo 1" src="https://picsum.photos/seed/gallery-0/800/600"></li><li data-index="1" inert="" aria-hidden="true"><img alt="Photo 2" src="https://picsum.photos/seed/gallery-1/800/600"></li><li data-index="2" inert="" aria-hidden="true"><img alt="Photo 3" src="https://picsum.photos/seed/gallery-2/800/600"></li><li data-index="3" inert="" aria-hidden="true"><img alt="Photo 4" src="https://picsum.photos/seed/gallery-3/800/600"></li><li data-index="4" inert="" aria-hidden="true"><img alt="Photo 5" src="https://picsum.photos/seed/gallery-4/800/600"></li><li data-index="5" inert="" aria-hidden="true"><img alt="Photo 6" src="https://picsum.photos/seed/gallery-5/800/600"></li></ul></div></div><button class="mx-button mx-button--icon-only mx-icon mx-icon--close" type="button">Close dialog</button></dialog></div>"`;
+
+exports[`Single Image 1`] = `"<div class="mx-gallery" id="_r_2_"><div class="mx-gallery__preview"><button type="button" class="mx-gallery__trigger"><img alt="Photo 1" src="https://picsum.photos/seed/gallery-0/800/600"></button></div><dialog class="mx-dialog mx-dialog--fullscreen" aria-label="Image gallery"><div class="mx-dialog__content mx-vertical-flow"><img alt="Photo 1" src="https://picsum.photos/seed/gallery-0/800/600"></div><button class="mx-button mx-button--icon-only mx-icon mx-icon--close" type="button">Close dialog</button></dialog></div>"`;

package/src/Component/Gallery/gallery.css

@@ -0,0 +1,53 @@
+/**
+ * Gallery
+ */
+
+@layer design-system.defaults {
+  mx-gallery {
+    display: block;
+  }
+}
+
+@layer design-system.components {
+  /* @public --gallery-item-min-width --gallery-gap */
+  .mx-gallery__preview {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(var(--gallery-item-min-width, 8rem), 1fr));
+    gap: var(--gallery-gap, var(--spacing-xs));
+  }
+
+  /* Optional convenience class for a preview trigger — entirely optional,
+     the preview content can be styled however the consumer likes. */
+  .mx-gallery__trigger {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+    padding: 0;
+    border: 0;
+    background-color: transparent;
+    cursor: pointer;
+
+    & img {
+      display: block;
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+    }
+
+    &:focus-visible {
+      outline: var(--outline-size, 2px) solid var(--outline-color, currentcolor);
+      outline-offset: 2px;
+    }
+  }
+
+  .mx-gallery .mx-dialog .mx-carousel {
+    --inline-size: var(--gallery-dialog-carousel-size, 100%);
+
+    & img {
+      inline-size: 100%;
+      max-inline-size: 100dvw;
+      max-block-size: var(--gallery-dialog-max-height, calc(100dvh - 180px));
+      object-fit: contain;
+    }
+  }
+}

package/src/Component/Gallery/gallery.entry.js

@@ -0,0 +1,2 @@
+import "../Carousel/Elements/Carousel"
+import "./Elements/Gallery"

package/src/Component/Gallery/gallery.twig

@@ -0,0 +1,13 @@
+{% set id = id|default('gallery') %}
+
+<mx-gallery class="mx-gallery" id="{{ id }}">
+  <div class="mx-gallery__preview">
+    {{ preview }}
+  </div>
+  <dialog class="mx-dialog mx-dialog--fullscreen" aria-label="{{ dialogLabel|default('Image gallery') }}">
+    <button autofocus class="mx-button mx-button--icon-only mx-icon mx-icon--close" data-close>Close dialog</button>
+    <div class="mx-dialog__content">
+      {{ content }}
+    </div>
+  </dialog>
+</mx-gallery>

package/src/Component/GlobalAlert/Elements/ClosableAlert.ts

@@ -42,6 +42,8 @@ export default class GlobalAlert extends HTMLElement {
     this.controller.abort()
     this.remove()
     this.localStorage = "true"
+    // Move focus to body so the close-button removal doesn't strand AT users.
+    document.body?.focus?.()
     const newEvent: CustomEvent<{ id: string; target: GlobalAlert }> = new CustomEvent(
       "GlobalAlert-close",
       {

package/src/Component/GlobalAlert/GlobalAlert.figma.ts

@@ -0,0 +1,31 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=64-24
+// source=src/Component/GlobalAlert/GlobalAlert.tsx
+// component=GlobalAlert
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const type = instance.getEnum("Type", {
+  Light: "GlobalAlertTypes.LIGHT",
+  Critical: "GlobalAlertTypes.CRITICAL",
+})
+const dismissible = instance.getEnum("Dismissible", { Off: false, On: true })
+
+// Real children — a proper Content SLOT (not a fixed text layer).
+const content = instance.getSlot("Content")
+
+const dismissibleProp = dismissible ? " dismissible" : ""
+// `type` defaults to LIGHT in code, but always emitted explicitly here for clarity.
+const typeProp = ` type={${type}}`
+
+export default {
+  example: figma.code`<GlobalAlert${typeProp}${dismissibleProp}>${content}</GlobalAlert>`,
+  imports: [
+    'import { GlobalAlert } from "@pnx-mixtape/mxds/react"',
+    'import { GlobalAlertTypes } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "global-alert",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/GlobalAlert/GlobalAlert.tsx

@@ -15,17 +15,31 @@ const GlobalAlert = ({
   type = GlobalAlertTypes.LIGHT,
   dismissible,
 }: GlobalAlertProps): JSX.Element => {
-  const uniqueId: string = id || useId()
+  const rId = useId()
+  const uniqueId: string = id || rId
   const [messageVisible, setMessageVisible] = useLocalStorage({
     key: uniqueId,
     initialValue: true,
   })
 
+  const isCritical: boolean = type === GlobalAlertTypes.CRITICAL
+
+  const handleDismiss = (): void => {
+    setMessageVisible(false)
+    // Return focus to body so AT users don't end up on a removed element.
+    if (typeof document !== "undefined") {
+      document.body.focus?.()
+    }
+  }
+
   return (
     <>
       {messageVisible && (
         <div
           id={uniqueId}
+          role={isCritical ? "alert" : "status"}
+          aria-live={isCritical ? "assertive" : "polite"}
+          aria-atomic="true"
           className={classNames("mx-global-alert", {
             [`mx-global-alert--${type}`]: type,
           })}
@@ -35,7 +49,7 @@ const GlobalAlert = ({
             {dismissible && (
               <button
                 className={classNames("mx-icon", "mx-icon--close")}
-                onClick={() => setMessageVisible(false)}
+                onClick={handleDismiss}
                 aria-label={`Close ${type} message`}
                 type="button"
               ></button>