import { Canvas, Controls, Meta, Source } from '@storybook/blocks'
import { KAIOInstallation, ResourceLinks } from '~storybook/components'
import * as docsStories from './Menu.docs.stories'
import * as exampleStories from './Menu.stories'

<Meta title="Components/Menu/API Specification" />

# Menu API Specification

Updated December 16, 2024

<ResourceLinks
  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Menu"
  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&node-id=6262-0&t=I4H23jCrCJz4O2nf-1"
  designGuidelines="/?path=/docs/components-menu-menu-next-usage-guidelines--docs"
  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Menu.html"
/>

<KAIOInstallation
  exportNames={['Menu', 'MenuTrigger', 'MenuItem', 'MenuPopover', 'MenuSection', 'MenuHeader']}
/>

## Compatibility

The `next/Menu` component is not backwards compatible with the current `Button` component (or a native `<button>` element). This will only work when used with the `next/Button` component.

## Overview

A menu displays a list of actions in a popover, toggled opened with a button.

<Canvas
  className="mb-64"
  of={exampleStories.Basic}
  source={{
    code: `
<MenuTrigger>
  <Button><Icon name="more_horiz" alt="Actions" /></Button>
  <MenuPopover>
    <Menu>
      <MenuItem href="#">Menu Item</MenuItem>
      <MenuItem onAction={handleAction}>Menu Item</MenuItem>
    </Menu>
  </MenuPopover>
</MenuTrigger>
  `,
  }}
/>

<Controls of={exampleStories.Basic} />

## Actions and Next.js routing

Use the `href` prop when an action navigates to a new page.
[Work in progress] Eventually, wrapping your app in `FrontendServices` from `@cultureamp/next-services` will automatically turn these into Next.js links.

Otherwise, use the `onAction` prop to trigger an action within the page.

<Canvas className="mb-24" of={docsStories.Actions} />

## Typeahead

Typeahead (the ability to quickly skip to an item by typing a few characters after opening) will automatically work when `MenuItem` `children` is a `string`.

If you're passing `ReactNode` into `MenuItem` `children`, you'll need to specify the `textValue` prop manually on `MenuItem` in order for typeahead to work.

<Canvas className="mb-24" of={exampleStories.RichContent} />

## Sections

Sections can be added with the `MenuSection` and `MenuHeader` components.

<Canvas className="mb-24" of={exampleStories.WithSections} />

## Disabling items

Menu items can be disabled with the `isDisabled` prop.

<Canvas className="mb-24" of={exampleStories.DisabledItems} />

## Controlled

By default, the open/closed state of the menu is handled under the hood. In cases where you need control over the open state, use the `isOpen` and `onOpenChange` props on the `MenuTrigger` component (both props must be used for this to work).

<Canvas className="mb-24" of={exampleStories.Controlled} />

## Use a menu to show additional actions

Instead of a split button (now a [deprecated component](https://cultureamp.atlassian.net/wiki/spaces/DES/pages/4286611457/Deprecating+Split+Buttons+-+Design+Request+for+Comment+RFC)), use a Button with text followed by a Menu to show any additional actions related to the most critical action.

<Canvas className="mb-24" of={exampleStories.ButtonMenuPattern} />