import {
  Canvas,
  Controls,
  Meta,
  Subtitle,
  Title,
} from '@storybook/addon-docs/blocks'
import * as DropdownMenuStories from './DropdownMenu.stories'
import { LifecycleTag, SourceLinks } from '../../docs/components'

<Meta of={DropdownMenuStories} />

<Title>DropdownMenu</Title>
<Subtitle>
  Floating menu of actions that appears when a trigger is activated. For value
  selection, use Select instead.
</Subtitle>
<SourceLinks
  links={[
    {
      label: 'Radix UI',
      href: 'https://www.radix-ui.com/primitives/docs/components/dropdown-menu#api-reference',
    },
    {
      label: 'shadcn/ui',
      href: 'https://ui.shadcn.com/docs/components/dropdown-menu',
    },
  ]}
/>
<LifecycleTag variant="In Development" />
**Component type:** Primitive

<Canvas of={DropdownMenuStories.Default} sourceState="shown" />
<Controls of={DropdownMenuStories.Default} />

## When to use

Use `DropdownMenu` for menus of actions — profile options, settings links, bulk operations. Do not use it for selecting a value from a list; use `Select` or `SimpleSelect` for that. Use `Popover` when the content is non-interactive or custom.

## Import

```tsx
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="secondary">Open menu</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuLabel>My account</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem>Settings</DropdownMenuItem>
    <DropdownMenuItem>Sign out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Subcomponents

- `DropdownMenu`: Root state container. Manages open/closed state.
- `DropdownMenuTrigger`: Element that opens the menu. Use `asChild` to make a `Button` the trigger.
- `DropdownMenuContent`: Floating panel containing menu items. Renders in a portal.
- `DropdownMenuItem`: Single clickable action. Accepts `disabled`.
- `DropdownMenuLabel`: Non-interactive section heading inside a `DropdownMenuGroup`.
- `DropdownMenuSeparator`: Horizontal rule between item groups.
- `DropdownMenuGroup`: Groups related items under an optional label.
- `DropdownMenuCheckboxItem`: Menu item with a checkbox. Use `checked` and `onCheckedChange`.
- `DropdownMenuRadioGroup`: Container for radio-style items where only one can be selected.
- `DropdownMenuRadioItem`: Radio item inside `DropdownMenuRadioGroup`.
- `DropdownMenuSub`: Container for a nested submenu.
- `DropdownMenuSubTrigger`: Item that opens a nested submenu on hover.
- `DropdownMenuSubContent`: Floating panel for the nested submenu.
- `DropdownMenuShortcut`: Right-aligned keyboard shortcut hint inside a `DropdownMenuItem`.
- `DropdownMenuTag`: Right-aligned badge inside a `DropdownMenuItem`. Useful for "New" or "Beta" labels.

## Using asChild

`DropdownMenuTrigger` accepts `asChild` to render any element as the trigger:

```tsx
<DropdownMenuTrigger asChild>
  <Button variant="ghost" size="sm">
    <SvgMoreVertical />
  </Button>
</DropdownMenuTrigger>
```

## Examples

### Simple menu

<Canvas of={DropdownMenuStories.SimpleMenu} sourceState="shown" />

### With icons

<Canvas of={DropdownMenuStories.WithIcons} sourceState="shown" />

### With checkboxes

<Canvas of={DropdownMenuStories.WithCheckboxes} sourceState="shown" />

### With submenu

<Canvas of={DropdownMenuStories.WithSubMenu} sourceState="shown" />

### Disabled states

<Canvas of={DropdownMenuStories.DisabledStates} sourceState="shown" />

## Related components

- `Select` / `SimpleSelect` for choosing a value from a list
- `Popover` for non-action floating content