import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
import {Menu} from '@workday/canvas-kit-react/menu';

import Basic from './examples/Basic';
import ContextMenu from './examples/ContextMenu';
import Icons from './examples/Icons';


# Canvas Kit Menu

`Menu` displays a list of options when triggered by an action or UI element like an icon or button.

[> Workday Design Reference](https://design.workday.com/components/popups/menus)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

`Menu` is typically triggered by an action such as pressing a button. The `Menu` comes with a
`Target` subcomponent and a Popup.

<ExampleCodeBlock code={Basic} />

`Menu` will automatically focus on the cursor item (first item by default). The `Menu` uses a menu
model which composes a list model and a popup model and sets up accessibility features for you.

`Menu` follows the
[Actions Menu pattern](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions.html)
using roving tabindex. Below is table of supported keyboard shortcuts and associated actions.

| Key                | Action                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `Enter` or `Space` | Activates the menu item and then closes the menu                                                             |
| `Escape`           | Closes the menu                                                                                              |
| `Up Arrow`         | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
| `Down Arrow`       | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item     |
| `Home`             | Moves focus to the first menu item                                                                           |
| `End`              | Moves focus to the last menu item                                                                            |

### Context Menu

<ExampleCodeBlock code={ContextMenu} />

### Icons

<ExampleCodeBlock code={Icons} />

## Component API

<SymbolDoc name="Menu" fileName="/react/" />

## Specifications

<Specifications file="Menu.spec.ts" name="Menu" />