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

package/src/Component/Dialog/README.md

@@ -1,29 +1,203 @@
 # Dialog
 
-### How to use
+Wraps the native HTML `<dialog>` element. Supports non-modal (`show()`), modal (`showModal()` with backdrop), and fullscreen variants. Use for confirmations, short forms, notifications, and interruptive flows. Modal and fullscreen dialogs block interaction with the rest of the page; non-modal dialogs sit above content but allow interaction outside.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/Dialog/dialog.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Dialog/dialog.css";
+```
 
-**Twig**
+---
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+## Twig
 
-- Eg: `{% extends '@mixtape/Component/Dialog/dialog.twig' %}`
+```twig
+{% include '@mixtape/Component/Dialog/dialog.twig' with {
+  id: 'example-dialog',
+  modal: true,
+  title: heading_component,
+  content: '<p>Body content…</p>',
+  link: button_component_with_data_close,
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+**dialog.twig props** (`Dialog` type from `ids-shape` extends `WayfindingBlock`):
 
-**JS Custom Element**
+| Prop         | Type             | Required | Description                                                                            |
+| ------------ | ---------------- | -------- | -------------------------------------------------------------------------------------- |
+| `id`         | `string`         | yes      | Dialog id — trigger must reference via `href="#id"` or `aria-controls="id"`            |
+| `open`       | `boolean`        | —        | Adds the `open` attribute on render (default `false`)                                  |
+| `modal`      | `boolean`        | —        | Adds `data-modal` to `<mx-dialog>` → `showModal()` with backdrop                       |
+| `fullscreen` | `boolean`        | —        | Adds `mx-dialog--fullscreen` class. Implies modal                                      |
+| `title`      | `Heading`        | —        | Rendered Heading component string                                                      |
+| `content`    | `WysiwygText`    | yes      | Body content (HTML string)                                                             |
+| `link`       | `Link \| Button` | —        | Optional action. Pass `data-close` attribute on buttons that should dismiss the dialog |
 
-Custom Elements are self defined, simply import the desired feature.
-These do not use the Shadow DOM and are not typical Web Components.
-External CSS applies.
-No Polyfills or frameworks are required.
+The template always renders an `autofocus` icon close button with `data-close`.
 
-- Dialog import: `import '@pnx-mixtape/mxds/src/Component/Dialog/Elements/Dialog';` and be sure to include `<mx-dialog>` around the `<dialog />` tag.
-- The triggering element should either have `aria-controls="[id]"` or `href="#[id]"` where the ID matches the dialog (required).
-- Use the `[data-modal]` attribute to trigger `HTMLDialogElement.showModal()` on open. When omitted `HTMLDialogElement.show()` is used.
-- Add `[data-close]` to any button that should call `HTMLDialogElement.close()`
+---
 
-See twig files for all HTML examples.
+## HTML
+
+Uses the native `<dialog>` element wrapped in the `<mx-dialog>` custom element, which wires up open/close behaviour from external triggers.
+
+```html
+<!-- Trigger: link with matching #id OR button with aria-controls -->
+<a class="mx-button mx-button--dark" href="#example-dialog">Open dialog</a>
+
+<mx-dialog id="example-dialog" data-modal>
+  <dialog class="mx-dialog">
+    <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-vertical-flow">
+      <h2>Dialog heading</h2>
+      <p>Content…</p>
+      <button class="mx-button mx-button--dark" data-close>Let's go</button>
+    </div>
+  </dialog>
+</mx-dialog>
+```
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Dialog/Elements/Dialog"
+```
+
+### `<mx-dialog>` behaviour
+
+- Trigger elements must reference the dialog via `href="#[id]"` or `aria-controls="[id]"` — the custom element searches the whole document for these.
+- Triggers automatically receive `aria-expanded` (toggled true/false) and `aria-controls` (if missing).
+- `data-modal` attribute on `<mx-dialog>` → opens via `showModal()` and applies a body scroll lock (`body--scroll-lock` class). Omit for non-modal.
+- `data-close` on any button inside the dialog → closes it.
+- Clicking outside the dialog bounds closes it.
+- ESC key closes it (handled manually for Safari compatibility until `closedby` is supported).
+- Fullscreen: add the `mx-dialog--fullscreen` class to the `<dialog>` and `data-modal` to the `<mx-dialog>`.
+
+```html
+<mx-dialog id="example-fullscreen" data-modal>
+  <dialog class="mx-dialog mx-dialog--fullscreen">…</dialog>
+</mx-dialog>
+```
+
+---
+
+## React
+
+Uses a Context-based composition pattern. Place `DialogContent` and `DialogCloseButton` as children inside `Dialog`. The `Dialog` component manages a ref to the underlying `<dialog>` element and calls `showModal()` / `show()` / `close()` in response to the `open` prop.
+
+```tsx
+import { Dialog, DialogContent, DialogCloseButton, Button, Heading, Text } from "@pnx-mixtape/mxds/react"
+import { HeadingTypes } from "@pnx-mixtape/ids-shape"
+import { useState } from "react"
+
+// Non-modal (default) — sits above the page but doesn't block interaction
+const [open, setOpen] = useState(false)
+
+<>
+  <Button onClick={() => setOpen(true)}>Open dialog</Button>
+  <Dialog open={open} onClose={() => setOpen(false)}>
+    <DialogContent>…</DialogContent>
+    <DialogCloseButton />
+  </Dialog>
+</>
+
+// Modal — opt in with `modal` for backdrop + focus trap + scroll lock
+<Dialog open={open} modal onClose={() => setOpen(false)}>
+  <DialogContent>
+    <Heading as={HeadingTypes.THREE}>Thanks, you're almost done!</Heading>
+    <Text>To finish the process, upload a few more documents.</Text>
+    <form method="dialog">
+      <div className="mx-form-actions">
+        <button className="mx-button mx-button--primary" type="submit">
+          Let's get started
+        </button>
+      </div>
+    </form>
+  </DialogContent>
+  <DialogCloseButton />
+</Dialog>
+
+// Fullscreen (always triggers modal behaviour)
+<Dialog open={open} fullscreen onClose={() => setOpen(false)}>
+  <DialogContent>…</DialogContent>
+  <DialogCloseButton />
+</Dialog>
+```
+
+**`Dialog` props:**
+
+| Prop         | Type         | Default | Description                                                                                                        |
+| ------------ | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
+| `open`       | `boolean`    | `false` | Controls whether the dialog is open. Toggling calls `showModal()` / `show()` / `close()` on the underlying element |
+| `modal`      | `boolean`    | `false` | When `true`, opens via `showModal()` (top layer + backdrop + scroll lock). When `false`, opens via `show()`        |
+| `fullscreen` | `boolean`    | `false` | Full-viewport modal. Forces modal behaviour regardless of the `modal` prop                                         |
+| `onClose`    | `() => void` | no-op   | Called when the dialog closes (ESC, close button, or `open` set to `false`). Use this to sync parent state         |
+| `className`  | `string`     | —       | Extra class on the `<dialog>` element                                                                              |
+
+All other props are forwarded to the `<dialog>` element.
+
+**`DialogContent`** — renders `<div class="mx-dialog__content mx-vertical-flow">`. Wrap title, body, and form actions in this.
+
+**`DialogCloseButton`** — renders an `autoFocus` icon-only close button wired to the context's `handleClose`. No props.
+
+**`useDialog()`** — hook exposing `{ handleClose, ref, open }` from context, for custom close controls inside the dialog.
+
+---
+
+## Modifiers
+
+| Class                   | Enum / flag        | Visual intent                                                                        |
+| ----------------------- | ------------------ | ------------------------------------------------------------------------------------ |
+| `mx-dialog`             | base               | Centered dialog, max 90vh tall, `container-max-width` wide, with backdrop when modal |
+| `mx-dialog--fullscreen` | `fullscreen: true` | Full viewport, no border, content centered in a `container-max-width` column         |
+
+Modal vs non-modal is not a CSS modifier — it's determined by which DOM method is called (`showModal()` vs `show()`), controlled by the `modal`/`fullscreen` props (React) or the `data-modal` attribute (HTML/Twig).
+
+---
+
+## Accessibility
+
+Because this component uses the native `<dialog>` element, the browser provides most a11y behaviour for free when opened via `showModal()`:
+
+- **Role**: native `<dialog>` has implicit `role="dialog"` — do not add it manually. (Use `role="alertdialog"` only if you need the stricter alert semantics; this component does not set that.)
+- **Focus trap**: `showModal()` traps focus inside the dialog automatically. Non-modal `show()` does **not** trap focus — keyboard users can Tab out to the rest of the page.
+- **Focus return**: the browser returns focus to the previously focused element on close.
+- **Initial focus**: the close button has `autofocus` so it receives focus on open. Override by giving another interior element `autofocus`.
+- **ESC to close**: native behaviour in modal mode. The `<mx-dialog>` custom element also wires a manual ESC handler (for Safari, and to support non-modal mode).
+- **Scroll lock**: adds `body--scroll-lock` to `<body>` when a modal opens and removes it on close.
+- **Backdrop click**: the Web Component closes on clicks outside the dialog bounds. Native `<dialog>` does not do this by default.
+- **Labelling**:
+  - **Twig**: when a `title` slot is provided, `dialog.twig` automatically wraps it in `<div id="{id}-title">` and adds `aria-labelledby="{id}-title"` on the `<dialog>`. No manual wiring required.
+  - **React**: there is no automatic wiring — pass `aria-labelledby` (and optionally `aria-describedby`) on `<Dialog>`, and matching `id`s on the heading / description inside `DialogContent`:
+    ```tsx
+    <Dialog open={open} aria-labelledby="dlg-title" aria-describedby="dlg-desc">
+      <DialogContent>
+        <Heading id="dlg-title" as={HeadingTypes.THREE}>
+          …
+        </Heading>
+        <Text id="dlg-desc">…</Text>
+      </DialogContent>
+      <DialogCloseButton />
+    </Dialog>
+    ```
+
+- **Close button label**: the icon-only button has visible text "Close dialog" (picked up as its accessible name); the `mx-icon--close` class applies the icon visually.
+- **Form dismissal**: a `<form method="dialog">` inside the dialog closes it on submit and fires the `close` event — used in the example to provide a primary action.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-dialog {
+  --dialog-background: var(--colour-background); /* dialog fill colour */
+  --line-width: 1px; /* border thickness */
+  --line-colour: var(--colour-border); /* border colour */
+  --container-max-width: …; /* controls dialog width */
+}
+```
+
+The backdrop is styled via `.mx-dialog::backdrop` (white at 75% opacity, animated to 80% via `@starting-style`) and is not themable through custom properties out of the box.

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

@@ -3,24 +3,24 @@
 exports[`Dialog 1`] = `
 "
     
-<a href="#example-dialog" aria-controls="unique-0">
+<a href="#example-dialog" aria-controls="unique-0" aria-expanded="false">
   
   <span>Open dialog</span>
     
 </a>
 
-    
+      
 <mx-dialog id="unique-0">
-  <dialog class="mx-dialog">
+  <dialog class="mx-dialog" aria-labelledby="unique-1">
     <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-vertical-flow">
-      
+              <div id="unique-1">
 <h2>Dialog heading</h2>
-
-      <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
+</div>
+            <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
       
         
-  <button class="mx-button mx-button--dark" type="button">
+  <button data-close="data-close" class="mx-button mx-button--dark" type="button">
     
     <span>Let's go</span>
     
@@ -42,18 +42,18 @@ exports[`Fullscreen 1`] = `
     
   </button>
 
-    
+      
 <mx-dialog id="unique-0" data-modal="">
-  <dialog class="mx-dialog mx-dialog--fullscreen">
+  <dialog class="mx-dialog mx-dialog--fullscreen" aria-labelledby="unique-1">
     <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-vertical-flow">
-      
+              <div id="unique-1">
 <h2>Dialog heading</h2>
-
-      <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
+</div>
+            <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
       
         
-  <button class="mx-button mx-button--dark" type="button">
+  <button data-close="data-close" class="mx-button mx-button--dark" type="button">
     
     <span>Let's go</span>
     
@@ -75,18 +75,18 @@ exports[`Modal 1`] = `
     
   </button>
 
-    
+      
 <mx-dialog id="unique-0" data-modal="">
-  <dialog class="mx-dialog">
+  <dialog class="mx-dialog" aria-labelledby="unique-1">
     <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-vertical-flow">
-      
+              <div id="unique-1">
 <h2>Dialog heading</h2>
-
-      <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
+</div>
+            <p>I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</p>
       
         
-  <button class="mx-button mx-button--dark" type="button">
+  <button data-close="data-close" class="mx-button mx-button--dark" type="button">
     
     <span>Let's go</span>
     

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Dialog 1`] = `"<dialog class="mx-dialog" open=""><div class="mx-dialog__content mx-vertical-flow"><h3 class="" id="thanks-youre-almost-d">Thanks, you're almost done!</h3><p class="">To finish the process, you will need to upload a few more documents. Please have your confirmation email ready before starting. Are you ready?</p><form method="dialog"><div class="mx-form-actions"><button class="mx-button mx-button--primary" type="submit">Let's get started</button></div></form></div><button class="mx-button mx-button--icon-only mx-icon mx-icon--close" type="button">Close dialog</button></dialog>"`;
+exports[`Dialog 1`] = `"<dialog class="mx-dialog" open=""><div class="mx-dialog__content mx-vertical-flow"><h3 class="" id="thanks-youre-almost-">Thanks, you're almost done!</h3><p class="">To finish the process, you will need to upload a few more documents. Please have your confirmation email ready before starting. Are you ready?</p><form method="dialog"><div class="mx-form-actions"><button class="mx-button mx-button--primary" type="submit">Let's get started</button></div></form></div><button class="mx-button mx-button--icon-only mx-icon mx-icon--close" type="button">Close dialog</button></dialog>"`;

package/src/Component/Dialog/dialog.css

@@ -79,10 +79,5 @@
     &[open] {
       display: grid;
     }
-
-    & .mx-dialog__content {
-      inline-size: min(100%, var(--container-max-width));
-      place-self: center;
-    }
   }
 }

package/src/Component/Dialog/dialog.twig

@@ -1,15 +1,21 @@
 {% set baseClass = 'mx-dialog' %}
+{% set titleId = id ? id ~ '-title' : 'mx-dialog-title' %}
 {% set classes = [
   baseClass,
   fullscreen ? baseClass~'--fullscreen' : null
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% if title is not empty %}
+  {% set attributes = attributes.setAttribute('aria-labelledby', titleId) %}
+{% endif %}
 
 <mx-dialog id="{{ id }}"{% if modal or fullscreen %} data-modal{% endif %}>
   <dialog{{ attributes }}{% if open %} open{% endif %}>
     <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-vertical-flow">
-      {{ title }}
+      {% if title is not empty %}
+        <div id="{{ titleId }}">{{ title }}</div>
+      {% endif %}
       {{ content }}
       {# Pass in the [data-close] attribute if it's a button that should close the dialog. #}
       {{ link }}

package/src/Component/DropMenu/Components/DropMenuContext.tsx

@@ -1,4 +1,4 @@
-/* eslint-disable no-console, consistent-return, @eslint-react/web-api/no-leaked-event-listener */
+/* eslint-disable no-console, consistent-return, @eslint-react/web-api/no-leaked-event-listener eslint-plugin-react-hooks/exhaustive-deps */
 /**
  * @file Drop Menu hook.
  */
@@ -6,6 +6,7 @@ import {
   RefObject,
   MouseEvent,
   KeyboardEvent,
+  useCallback,
   useEffect,
   useRef,
   useState,
@@ -18,8 +19,7 @@ import {
   useMemo,
   PropsWithChildren,
 } from "react"
-import { Keyboard } from "../../../Utility/utilities"
-import useToggle from "../../../Utility/Hooks/useToggle"
+import { useDisclosureState } from "react-stately"
 
 type DropMenuContextValues = {
   selected?: string[]
@@ -27,10 +27,10 @@ type DropMenuContextValues = {
   dropMenuId?: string
   triggerId?: string
   descriptionId?: string
-  on?: boolean
+  isExpanded?: boolean
   popoverRef?: RefObject<HTMLDivElement>
   handleClick?: (event: MouseEvent | KeyboardEvent, key: string) => void
-  handleKeydown?: (event: KeyboardEvent, key: string) => void
+  handleKeyDown?: (event: KeyboardEvent, key: string) => void
 }
 
 type DropMenuProviderProps = PropsWithChildren & {
@@ -57,123 +57,114 @@ const DropMenuProvider = ({
   selectedItem = defaultSelected,
   focusRef,
 }: DropMenuProviderProps): JSX.Element => {
-  const polyfilled = useRef<boolean>(false)
+  const polyfillsInstance = useRef<any>(null)
   const popoverRef = useRef<HTMLDivElement>(null)
-  const dropMenuId = id || useId()
+  const rId = useId()
+  const dropMenuId = id || rId
   const triggerId = `${dropMenuId}-target`
   const descriptionId = `${dropMenuId}-description`
-  const [on, toggle] = useToggle(false)
+  const { isExpanded, toggle } = useDisclosureState({ defaultExpanded: false })
   const [selected, setSelected] = useState<string[]>(selectedItem)
-  const keyboard = new Keyboard()
-  const controller = new AbortController()
-  const { signal } = controller
 
   // Polyfill anchor and popover APIs
   useEffect(() => {
-    if (!popoverRef.current || polyfilled.current) return
+    if (!popoverRef.current || polyfillsInstance.current) return
     const polyfill = async () => {
-      if (!("anchorName" in document.documentElement.style)) {
+      if (
+        !("anchorName" in document.documentElement.style) ||
+        !("popover" in HTMLElement.prototype)
+      ) {
         const { default: Polyfills } = await import("../../Popover/polyfills")
-        new Polyfills(popoverRef.current)
-        polyfilled.current = true
-      }
-      if (!Object.hasOwn(HTMLElement, "popover")) {
-        await import("@oddbird/popover-polyfill")
+        polyfillsInstance.current = new Polyfills(popoverRef.current)
       }
     }
-    polyfill().catch(error => console.warn(error))
-  }, [popoverRef, polyfilled])
+    polyfill().catch(error => {
+      if (process.env.NODE_ENV !== "production") console.warn(error)
+    })
 
-  const handleToggle = ({ newState }: ToggleEvent): void => {
-    toggle()
-    const handleClose = (): void => {
-      popoverRef.current?.togglePopover()
-    }
-    if (newState === "open") {
-      keyboard.attachPopup(popoverRef.current?.id, handleClose)
-    } else {
-      keyboard.detachPopup(popoverRef.current?.id)
+    return () => {
+      // Clean up polyfills event listener
+      polyfillsInstance.current?.destroy()
     }
+  }, [popoverRef])
+
+  // Escape/click-outside dismissal is handled natively by the Popover API
+  // for popover="auto" - no need to register this in the shared Keyboard
+  // class's popup stack.
+  const handleToggle = (): void => {
+    toggle()
   }
 
   // Toggle on state when popover toggle event occurs.
   useEffect(() => {
     if (!popoverRef.current) return
+    const controller = new AbortController()
     popoverRef.current.addEventListener("toggle", handleToggle, {
-      signal,
-    })
-    return () => {
-      if (!popoverRef.current) return
-      controller.abort()
-    }
-  }, [popoverRef])
-
-  // Attach keyboard when popover is open.
-  useEffect(() => {
-    if (!popoverRef.current || !on) return
-    const items: NodeListOf<HTMLButtonElement> =
-      popoverRef.current.querySelectorAll(":scope > button")
-    if (!items) return
-
-    const attachKeyboardMenu = () => keyboard.attachMenu(popoverRef.current, items)
-    popoverRef.current.addEventListener("focusin", attachKeyboardMenu, {
-      signal,
+      signal: controller.signal,
     })
-    popoverRef.current.addEventListener("focusout", keyboard.detachMenu, {
-      signal,
-    })
-    keyboard.attachEventListeners(signal)
-
     return () => {
-      if (!popoverRef.current) return
       controller.abort()
-      keyboard.detachMenu()
     }
-  }, [on, popoverRef])
+  }, [popoverRef, handleToggle])
 
   // Handle item click events.
-  const handleClick = (event: MouseEvent | KeyboardEvent, key: string): void => {
-    event.preventDefault()
-    let updated: string[] = []
-    if (selected.includes(key)) {
-      // Unselect
-      updated = selected.filter(item => item !== key)
-    } else if (multiple) {
-      // Add to selection.
-      updated = [...selected, key]
-    } else {
-      // Replace selection.
-      updated = [key]
-    }
-    setSelected(updated)
-    onClick(event, key, updated)
-    if (closeOnClick) {
-      popoverRef.current.togglePopover()
-    }
-  }
+  const handleClick = useCallback(
+    (event: MouseEvent | KeyboardEvent, key: string): void => {
+      event.preventDefault()
+      let updated: string[] = []
+      if (selected.includes(key)) {
+        // Unselect
+        updated = selected.filter(item => item !== key)
+      } else if (multiple) {
+        // Add to selection.
+        updated = [...selected, key]
+      } else {
+        // Replace selection.
+        updated = [key]
+      }
+      setSelected(updated)
+      onClick(event, key, updated)
+      if (closeOnClick) {
+        popoverRef.current.togglePopover()
+      }
+    },
+    [selected, multiple, onClick, closeOnClick],
+  )
 
   // Handle item keyboard events.
-  const handleKeyDown = (event: KeyboardEvent, key: string): void => {
-    if (event.key !== "Enter") return
-    handleClick(event, key)
-    if (focusRef && focusRef.current) {
-      focusRef.current.focus()
-    }
-  }
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent, key: string): void => {
+      if (event.key !== "Enter") return
+      handleClick(event, key)
+      if (focusRef && focusRef.current) {
+        focusRef.current.focus()
+      }
+    },
+    [handleClick, focusRef],
+  )
 
   const values = useMemo<DropMenuContextValues>(
     () => ({
       dropMenuId,
       triggerId,
       descriptionId,
-      on,
+      isExpanded,
       popoverRef,
       selected,
       setSelected,
       handleClick,
       handleKeyDown,
     }),
-    [dropMenuId, triggerId, descriptionId, on, popoverRef, selected],
+    [
+      dropMenuId,
+      triggerId,
+      descriptionId,
+      isExpanded,
+      popoverRef,
+      selected,
+      handleClick,
+      handleKeyDown,
+    ],
   )
 
   return <DropMenuContext value={values}>{children}</DropMenuContext>

package/src/Component/DropMenu/Components/DropMenuItem.figma.ts

@@ -0,0 +1,20 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=8-17
+// source=src/Component/DropMenu/Components/DropMenuItem.tsx
+// component=DropMenuItem
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const label = instance.getString("Label")
+
+// `selected` is not a prop on DropMenuItem — in code it's derived internally from the
+// parent DropMenuProvider's `selectedItem` array matching this item's `id`. The Figma
+// "Selected" variant only controls the underline visual here; it isn't a settable prop.
+export default {
+  example: figma.code`<DropMenuItem id="item-id" label="${label}" />`,
+  imports: ['import { DropMenuItem } from "@pnx-mixtape/mxds/react"'],
+  id: "drop-menu-item",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/DropMenu/Components/DropMenuItem.tsx

@@ -1,4 +1,5 @@
-import { JSX, ComponentPropsWithoutRef } from "react"
+import { JSX, ComponentPropsWithoutRef, KeyboardEvent } from "react"
+import { useFocusManager } from "react-aria"
 import { useDropMenuContext } from "./DropMenuContext"
 
 export type DropMenuItemProps = ComponentPropsWithoutRef<"button"> & {
@@ -14,9 +15,31 @@ const DropMenuItem = ({
   role = "menuitemradio",
   ...props
 }: DropMenuItemProps): JSX.Element => {
-  const { selected, handleClick, handleKeydown } = useDropMenuContext()
+  const { selected, handleClick, handleKeyDown } = useDropMenuContext()
+  const focusManager = useFocusManager()
   const isSelected: boolean = selected?.includes(id)
 
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>): void => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        event.preventDefault()
+        // `tabbable: true` matches the old Keyboard class's behavior of
+        // skipping items with tabindex="-1" (e.g. hidden/disabled items) -
+        // the default "focusable" mode would otherwise still focus them.
+        focusManager?.focusNext({ wrap: true, tabbable: true })
+        break
+      case "ArrowUp":
+      case "ArrowLeft":
+        event.preventDefault()
+        focusManager?.focusPrevious({ wrap: true, tabbable: true })
+        break
+      default:
+        handleKeyDown(event, id)
+        break
+    }
+  }
+
   return (
     <button
       type="button"
@@ -24,7 +47,7 @@ const DropMenuItem = ({
       aria-checked={isSelected}
       role={role}
       onClick={event => handleClick(event, id)}
-      onKeyDown={event => handleKeydown(event, id)}
+      onKeyDown={onKeyDown}
       {...props}
     >
       {label}