# DisclosureMenu

> Slug: `disclosure-menu` · Category: Disclosure

## When to use
- An expandable container for grouped controls or menu content that you reveal/hide externally.
- Building a custom dropdown surface where the styling chrome (`tdds-disclosure-menu`) should be applied to your own popover content.

## When NOT to use
- For a complete trigger-plus-menu pattern — use `MenuButton` with `renderMenu={<Menu />}`.
- For a form-field-style dropdown — use `MenuDropdown`.
- For multi-item progressive disclosure — use `Accordion`.

## Variants & decision tree
`DisclosureMenu` is a presentational container — there are no behavioral variants. Decide based on how much you want to assemble yourself:

| Need | Use |
|---|---|
| Pre-built button + listbox | `MenuDropdown` |
| Pre-built button + menu items | `MenuButton` + `Menu` |
| Custom wrapper styled like Arrow's disclosure menu chrome | `DisclosureMenu` (this) |

## States
- The container has no inherent state — visibility is controlled by you (e.g. `hidden` attribute, `display: none`, or conditional rendering).
- `inverse` swaps to dark-background styling.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | — | Required identifier (used for `aria-controls` from your trigger). |
| `children` | `ReactNode` | — | Content rendered inside the container. |
| `inverse` | `boolean` | inherited | Dark-background styling. |
| `className` | `string` | — | Extra class on the root `<div>`. |

## Usage examples
```tsx
const [open, setOpen] = useState(false);

<button aria-controls="profile-menu" aria-expanded={open}
        onClick={() => setOpen((o) => !o)}>
  Profile
</button>
{open && (
  <DisclosureMenu id="profile-menu">
    <Menu role="menu" behavior="Action items" a11yLabelledBy="profile-menu-label"
          items={profileActions} />
  </DisclosureMenu>
)}
```

## Composition
Typically wraps a `Menu` or a small custom layout (links + dividers). Position via a parent wrapper or a portal — `DisclosureMenu` itself doesn't position.

## Accessibility
- Use the `id` as the trigger's `aria-controls` target.
- If contents form a menu, give the inner `Menu` the appropriate `role` and `a11yLabelledBy`.
- Manage open/closed state and outside-click externally.

## Do / Don't
- Do reach for `MenuButton` first; only drop to `DisclosureMenu` for custom triggers.
- Do label the menu via the inner `Menu`'s `a11yLabelledBy`.
- Don't hide content with CSS `visibility` and leave it focusable — fully remove or use `hidden`.
- Don't render multiple `DisclosureMenu`s sharing the same `id`.
