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

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

@@ -0,0 +1,22 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=8-5
+// source=src/Component/DropMenu/DropMenu.tsx
+// component=DropMenu
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const label = instance.getString("Filter")
+
+// Trigger and Panel are split into two Figma components for clarity, but they
+// compose into ONE code component (<DropMenu>). This mapping — on the Trigger node —
+// shows the label prop only; the icon is CSS-driven (mx-icon--chevron-down), not a
+// swappable component in code. See DropMenu.figma.ts (the Panel mapping) for the full
+// composition including real DropMenuItem children.
+export default {
+  example: figma.code`<DropMenu label="${label}">{/* DropMenuItem children — see DropMenu Panel mapping */}</DropMenu>`,
+  imports: ['import { DropMenu } from "@pnx-mixtape/mxds/react"'],
+  id: "drop-menu-trigger",
+  metadata: {
+    nestable: true,
+  },
+}

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

@@ -0,0 +1,28 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=8-18
+// source=src/Component/DropMenu/DropMenu.tsx
+// component=DropMenu
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const item0 = instance.findInstance("item-0")
+const item1 = instance.findInstance("item-1")
+const item2 = instance.findInstance("item-2")
+let item0Code, item1Code, item2Code
+if (item0 && item0.type === "INSTANCE") item0Code = item0.executeTemplate().example
+if (item1 && item1.type === "INSTANCE") item1Code = item1.executeTemplate().example
+if (item2 && item2.type === "INSTANCE") item2Code = item2.executeTemplate().example
+
+// DropMenu Trigger and DropMenu Panel are split into two Figma components for
+// clarity, but in code they're rendered by ONE composite <DropMenu> component
+// (trigger button + popover panel together). This mapping — on the Panel node —
+// renders the full composition with real DropMenuItem children. The Trigger node's
+// own mapping shows the label-only, partial view of the same component.
+export default {
+  example: figma.code`<DropMenu label="Filter">${item0Code}${item1Code}${item2Code}</DropMenu>`,
+  imports: ['import { DropMenu } from "@pnx-mixtape/mxds/react"'],
+  id: "drop-menu",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/DropMenu/DropMenu.stories.ts

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect } from "storybook/test"
 import Component from "./drop-menu.twig"
 import "./drop-menu.css"
 import "./Elements/DropMenu"
@@ -92,4 +93,53 @@ export const Buttons: Story = {
       { label: "Stories", id: "stories" },
     ],
   },
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    const trigger = canvas.getByRole("button", { name: "Categories" })
+    const menu = canvas.getByRole("menu", { hidden: true })
+    const news = canvas.getByRole("menuitemradio", { name: "News", hidden: true })
+    const events = canvas.getByRole("menuitemradio", { name: "Events", hidden: true })
+    const stories = canvas.getByRole("menuitemradio", { name: "Stories", hidden: true })
+
+    await step("Starts closed", async () => {
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+
+    await step("Opens on click", async () => {
+      await userEvent.click(trigger)
+      await expect(menu.matches(":popover-open")).toBe(true)
+    })
+
+    await step("ArrowDown/ArrowUp move focus between items, with wraparound", async () => {
+      news.focus()
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(events).toHaveFocus()
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(stories).toHaveFocus()
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(news).toHaveFocus()
+      await userEvent.keyboard("{ArrowUp}")
+      await expect(stories).toHaveFocus()
+    })
+
+    // Escape does close this natively for real users (confirmed manually) -
+    // native popover light-dismiss just doesn't reliably fire in response to
+    // automated/synthetic keyboard events in this test environment, so it's
+    // not asserted here. Clicking the trigger again is used instead as a
+    // reliable way to close it without selecting an item.
+    await step("Clicking the trigger again closes it", async () => {
+      await userEvent.click(trigger)
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+
+    await step("Selecting an item checks it and closes (closeonclick)", async () => {
+      await userEvent.click(trigger)
+      await expect(events).toHaveAttribute("aria-checked", "false")
+      await userEvent.click(events)
+      await expect(events).toHaveAttribute("aria-checked", "true")
+      await expect(menu.matches(":popover-open")).toBe(false)
+      // Remove focus. There's no way to unselect an item via this widget, so
+      // this story is left with "Events" selected once this test has run.
+      await userEvent.click(canvasElement)
+    })
+  },
 }

package/src/Component/DropMenu/DropMenu.stories.tsx

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
 import Component from "./Components/DropMenuContext"
 import DropMenuContainer from "./DropMenu"
 import DropMenuItem from "./Components/DropMenuItem"
@@ -23,4 +24,51 @@ const meta: Meta<typeof Component> = {
   },
 }
 export default meta
-export const DropMenu: StoryObj<typeof Component> = {}
+export const DropMenu: StoryObj<typeof Component> = {
+  play: async ({ canvas, userEvent, step }) => {
+    const trigger = canvas.getByRole("button", { name: "Categories" })
+    const menu = canvas.getByRole("menu", { hidden: true })
+    const news = canvas.getByRole("menuitemradio", { name: "News", hidden: true })
+    const events = canvas.getByRole("menuitemradio", { name: "Events", hidden: true })
+
+    await step("Starts closed", async () => {
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+
+    await step("Opens on click", async () => {
+      await userEvent.click(trigger)
+      await expect(menu.matches(":popover-open")).toBe(true)
+    })
+
+    await step("Arrow keys move focus between items", async () => {
+      news.focus()
+      await userEvent.keyboard("{ArrowDown}")
+      await expect(events).toHaveFocus()
+    })
+
+    await step("Enter selects the focused item and closes (closeOnClick)", async () => {
+      await expect(events).toHaveAttribute("aria-checked", "false")
+      await userEvent.keyboard("{Enter}")
+      await expect(events).toHaveAttribute("aria-checked", "true")
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+
+    // Escape does close this natively for real users (confirmed manually) -
+    // native popover light-dismiss just doesn't reliably fire in response to
+    // automated/synthetic keyboard events in this test environment (same as
+    // the Twig DropMenu), so it's not asserted here.
+    await step("Reopens; clicking the trigger again closes it", async () => {
+      await userEvent.click(trigger)
+      await expect(menu.matches(":popover-open")).toBe(true)
+      await userEvent.click(trigger)
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+
+    await step("Reset: reopen and unselect Events", async () => {
+      await userEvent.click(trigger)
+      await userEvent.click(events)
+      await expect(events).toHaveAttribute("aria-checked", "false")
+      await expect(menu.matches(":popover-open")).toBe(false)
+    })
+  },
+}

package/src/Component/DropMenu/DropMenu.tsx

@@ -1,4 +1,5 @@
-import { ComponentPropsWithoutRef, JSX, PropsWithChildren } from "react"
+import { ComponentPropsWithoutRef, JSX, PropsWithChildren, useMemo } from "react"
+import { FocusScope } from "react-aria"
 import classNames from "classnames"
 import { useDropMenuContext } from "./Components/DropMenuContext"
 
@@ -40,22 +41,28 @@ const DropMenu = ({
 }: DropMenuProps): JSX.Element => {
   const { dropMenuId, triggerId, descriptionId, popoverRef } = useDropMenuContext()
 
+  const triggerStyle = useMemo(() => ({ anchorName: `--drop-menu-${dropMenuId}` }), [dropMenuId])
+  const popoverStyle = useMemo(
+    () => ({ positionAnchor: `--drop-menu-${dropMenuId}` }),
+    [dropMenuId],
+  )
+
   return (
     <Container className={classNames(className)} condition={!!className}>
       <button
         id={triggerId}
         type="button"
-        className={classNames([...triggerClassNames, "mx-drop-menu__trigger"])}
+        className={classNames([...triggerClassNames, "mx-popover__trigger"])}
         popoverTarget={dropMenuId}
-        style={{ anchorName: `--drop-menu-${dropMenuId}` }}
+        style={triggerStyle}
       >
         {label}
       </button>
       <div
         id={dropMenuId}
-        className={classNames("mx-drop-menu", popoverClassName)}
+        className={classNames("mx-popover mx-drop-menu", popoverClassName)}
         popover=""
-        style={{ positionAnchor: `--drop-menu-${dropMenuId}` }}
+        style={popoverStyle}
         ref={popoverRef}
         aria-labelledby={ariaLabel ? null : triggerId}
         aria-label={ariaLabel}
@@ -65,7 +72,7 @@ const DropMenu = ({
         <div id={descriptionId} className="sr-only">
           {description}
         </div>
-        {children}
+        <FocusScope>{children}</FocusScope>
       </div>
     </Container>
   )

package/src/Component/DropMenu/Elements/DropMenu.ts

@@ -57,8 +57,29 @@ export default class DropMenu extends Popover {
           ![...this.items].includes(target as HTMLButtonElement | HTMLAnchorElement)
         )
           return
-        if (key === "Enter") this.handleSelect(event)
-        event.preventDefault()
+
+        switch (key) {
+          case "Enter":
+            event.preventDefault()
+            this.handleSelect(event)
+            break
+          case "ArrowDown":
+          case "ArrowRight":
+            event.preventDefault()
+            this.moveFocus(target as HTMLButtonElement | HTMLAnchorElement, 1)
+            break
+          case "ArrowUp":
+          case "ArrowLeft":
+            event.preventDefault()
+            this.moveFocus(target as HTMLButtonElement | HTMLAnchorElement, -1)
+            break
+          default:
+            // Let every other key (Tab, Escape, Space, ...) through - this
+            // used to preventDefault unconditionally, which suppressed Tab
+            // navigation out of the menu and native Escape/Space handling
+            // whenever focus was on an item.
+            break
+        }
       },
       {
         signal,
@@ -88,6 +109,22 @@ export default class DropMenu extends Popover {
     if (this.closeOnClick) this.container.togglePopover()
   }
 
+  // Roving focus between items, wrapping at either end. Items with
+  // tabindex="-1" (e.g. hidden/disabled) are skipped, matching React's
+  // `useFocusManager({ tabbable: true })` behavior.
+  moveFocus = (current: HTMLButtonElement | HTMLAnchorElement, step: 1 | -1): void => {
+    const items = [...this.items]
+    const currentIndex = items.indexOf(current)
+    if (currentIndex === -1) return
+
+    let nextIndex = currentIndex
+    for (let i = 0; i < items.length; i += 1) {
+      nextIndex = (nextIndex + step + items.length) % items.length
+      if (items[nextIndex].getAttribute("tabindex") !== "-1") break
+    }
+    items[nextIndex]?.focus()
+  }
+
   get items(): NodeListOf<HTMLButtonElement | HTMLAnchorElement> | null {
     return this.container.querySelectorAll("a, button")
   }

package/src/Component/DropMenu/README.md

@@ -1,26 +1,260 @@
-# Drop Menu
+# DropMenu
 
-### How to use
+A button that toggles a popover menu of selectable items, built on the CSS Anchor Positioning and Popover APIs (with JS polyfills). Used on its own for filter/sort menus, and wrapped by `TabDropMenu` to provide the mobile trigger for the `Tabs` component.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/DropMenu/drop-menu.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/DropMenu/drop-menu.css";
+```
 
-**Twig**
+> **Note:** DropMenu extends Popover, so you also need Popover's CSS:
+>
+> ```css
+> @import "@pnx-mixtape/mxds/src/Component/Popover/popover.css";
+> ```
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+---
 
-- Eg: `{% extends '@mixtape/Component/DropMenu/drop-menu.twig' %}`
+## Twig
 
-Alternatively copy/paste the file for more control.
+```twig
+{% include '@mixtape/Component/DropMenu/drop-menu.twig' with {
+  id: 'categories',
+  label: 'Categories',
+  role: 'menu',
+  placement: 'bottom-start',
+  items: [
+    { id: 'news', label: 'News' },
+    { id: 'events', label: 'Events' },
+    { id: 'stories', label: 'Stories' },
+  ],
+} %}
 
-**JS Custom Element**
+{# Link-based variant — no role attribute, items use href #}
+{% include '@mixtape/Component/DropMenu/drop-menu.twig' with {
+  id: 'go-to',
+  label: 'Jump to',
+  items: [
+    { label: 'News', href: '#news' },
+    { label: 'Events', href: '#events' },
+  ],
+} %}
+```
 
-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 renders inside `<mx-dropmenu closeonclick>`, so `drop-menu.entry.js` (or a direct import of `Elements/DropMenu`) must be loaded.
 
-- Dialog import: `import '@pnx-mixtape/mxds/src/Component/DropMenu/Elements/DropMenu';` and be sure to include `<mx-dropmenu>` around the content.
+**drop-menu.twig props:**
 
-See twig files for all HTML examples.
+| Prop        | Type                       | Default           | Description                                                                                                    |
+| ----------- | -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `id`        | `string`                   | `"dropdown-menu"` | Unique id for the popover anchor                                                                               |
+| `label`     | `string`                   | —                 | Trigger button text                                                                                            |
+| `items`     | `DropMenuItem[]`           | —                 | Array of `{ label, id? }` (button) or `{ label, href }` (link) objects                                         |
+| `role`      | `"menu" \| "tablist"`      | —                 | Only rendered on the popover if set. When `"menu"`, button items use `menuitemradio`; otherwise they use `tab` |
+| `placement` | `PopoverPlacementModifier` | `"bottom-start"`  | Position of the popover relative to the trigger (written to `data-placement`)                                  |
+
+> There is no `DropMenu` type exported from `@pnx-mixtape/ids-shape`; the item shape is defined locally in `DropMenu.stories.ts`.
+
+---
+
+## HTML + Web Component
+
+The `<mx-dropmenu>` custom element wires up item-click handling, selection state (`aria-checked`), and close-on-click behaviour. It extends the base `<mx-popover>`.
+
+```html
+<mx-dropmenu closeonclick>
+  <button
+    id="dropdown-menu-target"
+    class="mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end"
+    popovertarget="dropdown-menu"
+    style="anchor-name: --dropdown-menu"
+  >
+    Categories
+  </button>
+  <div
+    class="mx-popover mx-drop-menu"
+    id="dropdown-menu"
+    aria-describedby="dropdown-menu-target"
+    style="position-anchor: --dropdown-menu"
+    data-placement="bottom-start"
+    popover
+    role="menu"
+  >
+    <button type="button" data-id="news" role="menuitemradio" aria-checked="false">News</button>
+    <button type="button" data-id="events" role="menuitemradio" aria-checked="false">Events</button>
+    <button type="button" data-id="stories" role="menuitemradio" aria-checked="false">
+      Stories
+    </button>
+  </div>
+</mx-dropmenu>
+```
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/DropMenu/Elements/DropMenu"
+```
+
+**Attributes on `<mx-dropmenu>`:**
+
+| Attribute      | Description                                                              |
+| -------------- | ------------------------------------------------------------------------ |
+| `closeonclick` | Presence of this attribute closes the popover after an item is activated |
+
+**Items:** Children of the popover `<div>` can be `<button data-id="{id}">` items (for selection) or plain `<a href="...">` links (for navigation). Buttons receive `aria-checked="true"` on the last-activated item; all others get `aria-checked="false"`.
+
+**Custom event:** `drop-menu-select` — dispatched on the popover when an item is activated. `event.detail` is `{ event, target }` where `target` is the clicked `<button>` or `<a>`.
+
+---
+
+## React
+
+DropMenu uses a context-based composition pattern. Always wrap `DropMenu` (the trigger + popover) in a `DropMenuProvider` — it owns the selection state, ids, popover ref, and keyboard handling. Children of `DropMenu` are typically `DropMenuItem` buttons, or anchors/buttons you author yourself.
+
+```tsx
+import { DropMenuProvider, DropMenu, DropMenuItem } from "@pnx-mixtape/mxds/react"
+
+// Single-select menu (default role="menu")
+<DropMenuProvider id="categories">
+  <DropMenu label="Categories">
+    <DropMenuItem id="news" label="News" />
+    <DropMenuItem id="events" label="Events" />
+    <DropMenuItem id="stories" label="Stories" />
+  </DropMenu>
+</DropMenuProvider>
+
+// Multi-select, stays open after click
+<DropMenuProvider
+  id="tags"
+  multiple
+  closeOnClick={false}
+  selectedItem={["news"]}
+  onClick={(_event, key, updated) => console.log("now selected:", updated)}
+>
+  <DropMenu label="Tags">
+    <DropMenuItem id="news" label="News" role="menuitemcheckbox" />
+    <DropMenuItem id="events" label="Events" role="menuitemcheckbox" />
+  </DropMenu>
+</DropMenuProvider>
+
+// Used as a tablist trigger (this is what TabDropMenu does)
+<DropMenuProvider id="mobile-tabs">
+  <DropMenu label="Funk" role="tablist" className="mobile-only">
+    <DropMenuItem id="tab-1" label="Funk" role="tab" aria-controls="tab-1" />
+    <DropMenuItem id="tab-2" label="Soul" role="tab" aria-controls="tab-2" />
+  </DropMenu>
+</DropMenuProvider>
+```
+
+**`DropMenuProvider` props:**
+
+| Prop           | Type                            | Default   | Description                                                                                      |
+| -------------- | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `id`           | `string`                        | `useId()` | Unique id — used for the popover element, `{id}-target` trigger, `{id}-description` sr-only hint |
+| `multiple`     | `boolean`                       | `false`   | Allow multiple items selected at once                                                            |
+| `closeOnClick` | `boolean`                       | `true`    | Close the popover after an item is activated                                                     |
+| `selectedItem` | `string[]`                      | `[]`      | Initially selected item ids                                                                      |
+| `onClick`      | `(event, key, updated) => void` | noop      | Called whenever an item is activated, with the new selected array                                |
+| `focusRef`     | `RefObject<HTMLElement>`        | —         | Element to return focus to after an Enter-key activation                                         |
+
+**`DropMenu` props:**
+
+| Prop                | Type                  | Default                                                                   | Description                                                                               |
+| ------------------- | --------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `label`             | `string`              | —                                                                         | Text shown inside the trigger button (required)                                           |
+| `role`              | `"menu" \| "tablist"` | `"menu"`                                                                  | ARIA role on the popover — use `"tablist"` when items are tabs                            |
+| `ariaLabel`         | `string`              | —                                                                         | Overrides `aria-labelledby`; use when the trigger label isn't appropriate for the popover |
+| `description`       | `string`              | `"Results will update when you make a selection. Press escape to close."` | Visually hidden `aria-describedby` text inside the popover                                |
+| `className`         | `string`              | —                                                                         | Wraps the trigger + popover in a `<div>` with this class (used for `mobile-only` etc.)    |
+| `triggerClassNames` | `string[]`            | `["mx-button", "mx-icon", "mx-icon--chevron-down", "mx-icon--end"]`       | Classes applied to the trigger `<button>`. `mx-drop-menu__trigger` is always appended     |
+| `popoverClassName`  | `string`              | —                                                                         | Extra class on the popover `<div>`                                                        |
+
+**`DropMenuItem` props** (extends `<button>` props):
+
+| Prop       | Type                                             | Default           | Description                                                                                   |
+| ---------- | ------------------------------------------------ | ----------------- | --------------------------------------------------------------------------------------------- |
+| `id`       | `string`                                         | —                 | Item id, used as the key in the selection array (required)                                    |
+| `label`    | `string`                                         | —                 | Button text (required)                                                                        |
+| `role`     | `"menuitemradio" \| "menuitemcheckbox" \| "tab"` | `"menuitemradio"` | ARIA role. Use `menuitemcheckbox` with `multiple`, or `tab` inside a `role="tablist"` popover |
+| `selected` | `boolean`                                        | —                 | (Declared on the prop type; selected state is actually driven by context via `aria-checked`)  |
+
+---
+
+### React ⇄ Twig parity
+
+| Feature              | React                         | Twig                                                                                                          |
+| -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Custom trigger class | ✅ (`triggerClassNames` prop) | ❌ — `mx-popover__trigger mx-button mx-icon mx-icon--chevron-down mx-icon--end` is hard-coded in the template |
+
+Until a `triggerClass` Twig prop is added, fork `drop-menu.twig` if you need a different trigger appearance.
+
+---
+
+## Placement modifiers (`PopoverPlacementModifier` enum from `ids-shape`)
+
+Applied via the `data-placement` attribute on the popover element. Twig default is `bottom-start`; React default is set by the Popover CSS.
+
+| `PopoverPlacementModifier` value        | `data-placement` |
+| --------------------------------------- | ---------------- |
+| `PopoverPlacementModifier.TOP`          | `"top"`          |
+| `PopoverPlacementModifier.TOP_START`    | `"top-start"`    |
+| `PopoverPlacementModifier.TOP_END`      | `"top-end"`      |
+| `PopoverPlacementModifier.BOTTOM`       | `"bottom"`       |
+| `PopoverPlacementModifier.BOTTOM_START` | `"bottom-start"` |
+| `PopoverPlacementModifier.BOTTOM_END`   | `"bottom-end"`   |
+| `PopoverPlacementModifier.LEFT`         | `"left"`         |
+| `PopoverPlacementModifier.LEFT_START`   | `"left-start"`   |
+| `PopoverPlacementModifier.LEFT_END`     | `"left-end"`     |
+| `PopoverPlacementModifier.RIGHT`        | `"right"`        |
+| `PopoverPlacementModifier.RIGHT_START`  | `"right-start"`  |
+| `PopoverPlacementModifier.RIGHT_END`    | `"right-end"`    |
+
+---
+
+## Role modifiers
+
+DropMenu's `role` prop (React) / `role` attribute (Twig/HTML) flips the ARIA semantics of the popover and its items.
+
+| `role` value       | Popover role | Item role (default)                                     | When to use                                                                                                                       |
+| ------------------ | ------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `"menu"` (default) | `menu`       | `menuitemradio` (or `menuitemcheckbox` when `multiple`) | A choice menu (filter, sort, category picker)                                                                                     |
+| `"tablist"`        | `tablist`    | `tab`                                                   | Mobile/compact replacement for a tab strip. Each item must also have `aria-controls="{panelId}"`. This is what `TabDropMenu` uses |
+
+---
+
+## Accessibility
+
+- **Trigger button** — a native `<button>` with `popovertarget="{popoverId}"`. The browser Popover API automatically manages `aria-expanded` and `aria-controls` on it.
+- **Popover** — `<div popover>` with `role="menu"` (default) or `role="tablist"`. Labelled by the trigger via `aria-labelledby` (auto), or override with `ariaLabel`.
+- **Screen-reader description** — visually hidden text inside the popover, referenced by `aria-describedby`. React default: _"Results will update when you make a selection. Press escape to close."_
+- **Items** — use `role="menuitemradio"` (single-select), `role="menuitemcheckbox"` (multi-select), or `role="tab"` (tablist). Selection state is exposed via `aria-checked="true" | "false"`.
+- **Keyboard:**
+  - `ArrowDown` / `ArrowRight` — focus next item, wraps to first at end
+  - `ArrowUp` / `ArrowLeft` — focus previous item, wraps to last at start
+  - `Enter` — activate focused item (and return focus to `focusRef` if provided)
+  - `Escape` — close the active popover
+  - Click outside the popover also closes it
+  - **React:** arrow-key roving is implemented with react-aria's `useFocusManager` inside a `FocusScope` wrapping the popover's children. `Escape`/click-outside close via the native Popover API — nothing custom is needed for those.
+  - **Web component (`<mx-dropmenu>`):** arrow-key roving is a small dedicated implementation (`DropMenu.moveFocus`) — not the shared `Keyboard` utility, which is only used by `Navigation`'s flyout menus. `Escape`/click-outside close via the native Popover API, same as React.
+- Items with `tabindex="-1"` are skipped by arrow-key focus (both React and the web component) so invisible/hidden items don't trap focus.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-drop-menu {
+  --popover-padding: 0px; /* inherited from mx-popover, removed here */
+  --popover-top: 0px; /* inherited from mx-popover, removed here */
+}
+```
+
+Item buttons that are authored without a class (i.e. `<button>` inside `.mx-drop-menu`) are reset to inherit font/colour from the popover and get:
+
+- `padding-block: var(--spacing-xxxs)`
+- `padding-inline: var(--spacing-xs)`
+- `min-inline-size: 15ch`
+- `text-decoration: underline` when `aria-checked="true"`
+
+For positioning, gap, background, border and shadow, see the Popover component's CSS custom properties — DropMenu inherits all of them via `.mx-popover`.

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

@@ -7,7 +7,7 @@ exports[`Buttons 1`] = `
 </button>
 <div class="mx-popover mx-drop-menu" id="dropdown-menu" aria-describedby="unique-0" style="position-anchor: --dropdown-menu" data-placement="bottom-start" popover="" role="menu">
             <button type="button" data-id="news" role="menuitemradio" aria-checked="false">News</button>
-                <button type="button" data-id="events" role="menuitemradio" aria-checked="false">Events</button>
+                <button type="button" data-id="events" role="menuitemradio" aria-checked="true">Events</button>
                 <button type="button" data-id="stories" role="menuitemradio" aria-checked="false">Stories</button>
       </div>
 </mx-dropmenu>

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Drop Menu 1`] = `"<button id="drop-menu-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-drop-menu__trigger" popovertarget="drop-menu-storybook" style="anchor-name: --drop-menu-drop-menu-storybook;">Categories</button><div id="drop-menu-storybook" class="mx-drop-menu" popover="" aria-labelledby="drop-menu-storybook-target" aria-describedby="drop-menu-storybook-description" role="menu" style="position-anchor: --drop-menu-drop-menu-storybook;"><div id="drop-menu-storybook-description" class="sr-only">Results will update when you make a selection. Press escape to close.</div><button type="button" data-id="news" aria-checked="false" role="menuitemradio">News</button><button type="button" data-id="events" aria-checked="false" role="menuitemradio">Events</button><button type="button" data-id="stories" aria-checked="false" role="menuitemradio">Stories</button></div>"`;
+exports[`Drop Menu 1`] = `"<button id="drop-menu-storybook-target" type="button" class="mx-button mx-icon mx-icon--chevron-down mx-icon--end mx-popover__trigger" popovertarget="drop-menu-storybook" style="anchor-name: --drop-menu-drop-menu-storybook;">Categories</button><div id="drop-menu-storybook" class="mx-popover mx-drop-menu" popover="" aria-labelledby="drop-menu-storybook-target" aria-describedby="drop-menu-storybook-description" role="menu" style="position-anchor: --drop-menu-drop-menu-storybook;"><div id="drop-menu-storybook-description" class="sr-only">Results will update when you make a selection. Press escape to close.</div><span data-focus-scope-start="true" hidden=""></span><button type="button" data-id="news" aria-checked="false" role="menuitemradio">News</button><button type="button" data-id="events" aria-checked="false" role="menuitemradio">Events</button><button type="button" data-id="stories" aria-checked="false" role="menuitemradio">Stories</button><span data-focus-scope-end="true" hidden=""></span></div>"`;

package/src/Component/DropMenu/drop-menu.css

@@ -21,6 +21,7 @@
   :where(.mx-drop-menu) {
     --popover-padding: 0px;
     --popover-top: 0px;
+    --outline-offset: -2px;
 
     & :where(button:not([class])) {
       appearance: none;