# Menu

> Slug: `menu` · Category: Navigation

## When to use
- As the popup body of a dropdown, action sheet, or filter trigger that you're composing yourself.
- When you need a primitive menu list (with `role="menu"` or `role="listbox"`) and full control over the trigger and open/close state.

## When NOT to use
- For a complete trigger-plus-menu pattern — use `MenuDropdown` (form-field-style) or `MenuButton` (button trigger).
- For a single-select native field — use `Select`.
- For navigation tabs — use `Tabs` or `Subnavigation`.

## Variants & decision tree
`Menu` is a primitive — choose the right `behavior` and `role` combination:

- **`role="menu"` + `behavior="Action items"`** → items are `menuitem` (e.g. "Edit", "Delete").
- **`role="menu"` + `behavior="Single select"`** → items are `menuitemradio`. One selectable at a time.
- **`role="menu"` + `behavior="Multi select"`** → items are `menuitemcheckbox`. Multiple toggleable.
- **`role="listbox"` + any behavior** → items are `option` with `aria-selected`. Use when paired with a form-field trigger (this is what `MenuDropdown` does).

Icons render before text only when `behavior !== 'Multi select'` AND every item provides an `icon` (all-or-nothing rule from the Lit source).

## States
Items support `selected`, `disabled`, and force-`focused` styling. The list itself is `tabindex="0"` so focus lands on the container; arrow-key navigation between items is the parent component's responsibility.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `behavior` | `'Single select' \| 'Multi select' \| 'Action items'` | — | Drives item ARIA role. |
| `role` | `'menu' \| 'listbox'` | — | Container role. |
| `items` | `MenuItem[]` | — | `{ id, text, icon?, selected?, disabled?, iconA11yLabel? }`. |
| `a11yLabelledBy` | `string` | — | ID of the label element (`aria-labelledby`). |
| `inverse` | `boolean` | inherited | Dark-background styling. |

## Usage examples
```tsx
<Menu
  role="menu"
  behavior="Action items"
  a11yLabelledBy="actions-label"
  items={[
    { id: 'edit', text: 'Edit' },
    { id: 'delete', text: 'Delete', disabled: true },
  ]}
/>
```

## Composition
`MenuDropdown` composes `Menu` internally with `role="listbox"`. When using `Menu` standalone, render it inside `MenuButton`'s `renderMenu` slot or your own popover.

## Accessibility
- Always provide `a11yLabelledBy` pointing at a visible label.
- Match `role` to the trigger pattern: `menu` for command/action triggers, `listbox` for form-field-style selections.
- All items must have a unique `id` — used by parent triggers for `aria-activedescendant`.

## Do / Don't
- Do use `MenuButton` + `Menu` together for action menus.
- Do supply icons consistently (all items or none).
- Don't set `role="menu"` if the trigger is a form field — use `listbox`.
- Don't render `Menu` without a labeled trigger.
