import { Meta, Canvas, Primary, Controls } from "@storybook/addon-docs/blocks";

import * as stories from "./menu.stories";

<Meta of={stories} />

# Menu

The menu component is used to present a list of actions, selections, or navigation options in a
floating overlay. It appears in response to a user interaction, like a button or trigger, and
provides contextual choices relevant to the current workflow.

<Canvas of={stories.ClosedMenu} />

<br />

## Composition

A menu is constructed of a `bit-menu` element with child `bitMenuItem` elements. These can be
anchors or buttons. `bit-menu-divider` can be used to section menu items.

Menu triggers use the `bitMenuTriggerFor` directive to specify the menu they open.

Example code:

```html
<button type="button" bitButton buttonType="secondary" [bitMenuTriggerFor]="myMenu">
  Open menu
</button>

<bit-menu #myMenu>
  <a href="#" bitMenuItem>Anchor link</a>
  <button type="button" bitMenuItem>Button</button>
  <bit-menu-divider></bit-menu-divider>
</bit-menu>
```

### Menu Items

`bitMenuItem` supports the following slots:

| Slot           | Description                                         |
| -------------- | --------------------------------------------------- |
| default        | primary text or arbitrary content                   |
| `slot="start"` | commonly an icon or avatar; before the default slot |
| `slot="end"`   | commonly an icon; after the default slot            |

```html
<button type="button" bitMenuItem>
  <bit-icon class="bwi-key" slot="start" />
  Menu item with icons
  <bit-icon class="bwi-angle-right" slot="end" />
</button>
```

## Use cases

To categorize different use cases for menus, we use the following terminology:

- Action menus
- Filter menus (_Coming soon_)
- Input menus (_Coming soon_)

### Action menus

Action menus are used used for contextual actions such as edit, delete, copy, and similar
operations.

Usage guidelines:

- Use the menu item `danger` variant for destructive operations.
- If using leading icons, all menu items must have a leading icon; otherwise, no menu items should
  have a leading icon.
- Menu items should be anchors or buttons, depending on the action they execute.

<Canvas of={stories.ActionMenu} />

### Filter menus

_Coming soon_

### Input menus

_Coming soon_

## Accessibility

`bitMenuTriggerFor` uses the `aria-haspopup` and `aria-expanded` attributes to provide an accessible
implementation. `bit-menu` specifies a `role` and accepts an optional `aria-label` for menus that
need a differentiating accessible name. `bitMenuItem` also specifies an accessible role for itself.

Users are able to navigate the opened menu via the up and down arrow keys and close the menu using
the escape key or clicking out of the menu.
