diff --git a/packages/components/src/menu/index.tsx b/packages/components/src/menu/index.tsx index 2e0fc91cfbc34f..66bfd0124dd9d1 100644 --- a/packages/components/src/menu/index.tsx +++ b/packages/components/src/menu/index.tsx @@ -27,6 +27,16 @@ import { MenuTriggerButton } from './trigger-button'; import { MenuSubmenuTriggerItem } from './submenu-trigger-item'; import { MenuPopover } from './popover'; +/** + * Menu is a collection of React components that combine to render + * ARIA-compliant [menu](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) and + * [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/) patterns. + * + * `Menu` itself is a wrapper component and context provider. + * It is responsible for managing the state of the menu and its items, and for + * rendering the `Menu.TriggerButton` (or the `Menu.SubmenuTriggerItem`) + * component, and the `Menu.Popover` component. + */ const UnconnectedMenu = ( props: MenuProps ) => { const { children, @@ -96,36 +106,98 @@ export const Menu = Object.assign( Context: Object.assign( MenuContext, { displayName: 'Menu.Context', } ), + /** + * Renders a menu item inside the `Menu.Popover` or `Menu.Group` components. + * + * It can optionally contain one instance of the `Menu.ItemLabel` component + * and one instance of the `Menu.ItemHelpText` component. + */ Item: Object.assign( MenuItem, { displayName: 'Menu.Item', } ), + /** + * Renders a radio menu item inside the `Menu.Popover` or `Menu.Group` + * components. + * + * It can optionally contain one instance of the `Menu.ItemLabel` component + * and one instance of the `Menu.ItemHelpText` component. + */ RadioItem: Object.assign( MenuRadioItem, { displayName: 'Menu.RadioItem', } ), + /** + * Renders a checkbox menu item inside the `Menu.Popover` or `Menu.Group` + * components. + * + * It can optionally contain one instance of the `Menu.ItemLabel` component + * and one instance of the `Menu.ItemHelpText` component. + */ CheckboxItem: Object.assign( MenuCheckboxItem, { displayName: 'Menu.CheckboxItem', } ), + /** + * Renders a group for menu items. + * + * It should contain one instance of `Menu.GroupLabel` and one or more + * instances of `Menu.Item`, `Menu.RadioItem`, or `Menu.CheckboxItem`. + */ Group: Object.assign( MenuGroup, { displayName: 'Menu.Group', } ), + /** + * Renders a label in a menu group. + * + * This component should be wrapped with `Menu.Group` so the + * `aria-labelledby` is correctly set on the group element. + */ GroupLabel: Object.assign( MenuGroupLabel, { displayName: 'Menu.GroupLabel', } ), + /** + * Renders a divider between menu items or menu groups. + */ Separator: Object.assign( MenuSeparator, { displayName: 'Menu.Separator', } ), + /** + * Renders a menu item's label text. It should be wrapped with `Menu.Item`, + * `Menu.RadioItem`, or `Menu.CheckboxItem`. + */ ItemLabel: Object.assign( MenuItemLabel, { displayName: 'Menu.ItemLabel', } ), + /** + * Renders a menu item's help text. It should be wrapped with `Menu.Item`, + * `Menu.RadioItem`, or `Menu.CheckboxItem`. + */ ItemHelpText: Object.assign( MenuItemHelpText, { displayName: 'Menu.ItemHelpText', } ), + /** + * Renders a dropdown menu element that's controlled by a sibling + * `Menu.TriggerButton` component. It renders a popover and automatically + * focuses on items when the menu is shown. + * + * The only valid children of `Menu.Popover` are `Menu.Item`, + * `Menu.RadioItem`, `Menu.CheckboxItem`, `Menu.Group`, `Menu.Separator`, + * and `Menu` (for nested dropdown menus). + */ Popover: Object.assign( MenuPopover, { displayName: 'Menu.Popover', } ), + /** + * Renders a menu button that toggles the visibility of a sibling + * `Menu.Popover` component when clicked or when using arrow keys. + */ TriggerButton: Object.assign( MenuTriggerButton, { displayName: 'Menu.TriggerButton', } ), + /** + * Renders a menu item that toggles the visibility of a sibling + * `Menu.Popover` component when clicked or when using arrow keys. + * + * This component is used to create a nested dropdown menu. + */ SubmenuTriggerItem: Object.assign( MenuSubmenuTriggerItem, { displayName: 'Menu.SubmenuTriggerItem', } ),