@wordpress/components 29.1.1 → 29.2.0

package/src/menu/checkbox-item.tsx

@@ -13,18 +13,18 @@ import { Icon, check } from '@wordpress/icons';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
-import type { MenuCheckboxItemProps } from './types';
+import { Context } from './context';
+import type { CheckboxItemProps } from './types';
 import * as Styled from './styles';
 
-export const MenuCheckboxItem = forwardRef<
+export const CheckboxItem = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuCheckboxItemProps, 'div', false >
->( function MenuCheckboxItem(
+	WordPressComponentProps< CheckboxItemProps, 'div', false >
+>( function CheckboxItem(
 	{ suffix, children, disabled = false, hideOnClick = false, ...props },
 	ref
 ) {
-	const menuContext = useContext( MenuContext );
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -33,7 +33,7 @@ export const MenuCheckboxItem = forwardRef<
 	}
 
 	return (
-		<Styled.MenuCheckboxItem
+		<Styled.CheckboxItem
 			ref={ ref }
 			{ ...props }
 			accessibleWhenDisabled
@@ -50,17 +50,17 @@ export const MenuCheckboxItem = forwardRef<
 				<Icon icon={ check } size={ 24 } />
 			</Ariakit.MenuItemCheck>
 
-			<Styled.MenuItemContentWrapper>
-				<Styled.MenuItemChildrenWrapper>
+			<Styled.ItemContentWrapper>
+				<Styled.ItemChildrenWrapper>
 					{ children }
-				</Styled.MenuItemChildrenWrapper>
+				</Styled.ItemChildrenWrapper>
 
 				{ suffix && (
 					<Styled.ItemSuffixWrapper>
 						{ suffix }
 					</Styled.ItemSuffixWrapper>
 				) }
-			</Styled.MenuItemContentWrapper>
-		</Styled.MenuCheckboxItem>
+			</Styled.ItemContentWrapper>
+		</Styled.CheckboxItem>
 	);
 } );

package/src/menu/context.tsx

@@ -6,8 +6,6 @@ import { createContext } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import type { MenuContext as MenuContextType } from './types';
+import type { ContextProps } from './types';
 
-export const MenuContext = createContext< MenuContextType | undefined >(
-	undefined
-);
+export const Context = createContext< ContextProps | undefined >( undefined );

package/src/menu/docs-manifest.json

@@ -0,0 +1,62 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "Menu",
+	"filePath": "./index.tsx",
+	"subcomponents": [
+		{
+			"displayName": "TriggerButton",
+			"preferredDisplayName": "Menu.TriggerButton",
+			"filePath": "./trigger-button.tsx"
+		},
+		{
+			"displayName": "Popover",
+			"preferredDisplayName": "Menu.Popover",
+			"filePath": "./popover.tsx"
+		},
+		{
+			"displayName": "Item",
+			"preferredDisplayName": "Menu.Item",
+			"filePath": "./item.tsx"
+		},
+		{
+			"displayName": "RadioItem",
+			"preferredDisplayName": "Menu.RadioItem",
+			"filePath": "./radio-item.tsx"
+		},
+		{
+			"displayName": "CheckboxItem",
+			"preferredDisplayName": "Menu.CheckboxItem",
+			"filePath": "./checkbox-item.tsx"
+		},
+		{
+			"displayName": "ItemLabel",
+			"preferredDisplayName": "Menu.ItemLabel",
+			"filePath": "./item-label.tsx"
+		},
+		{
+			"displayName": "ItemHelpText",
+			"preferredDisplayName": "Menu.ItemHelpText",
+			"filePath": "./item-help-text.tsx"
+		},
+		{
+			"displayName": "Group",
+			"preferredDisplayName": "Menu.Group",
+			"filePath": "./group.tsx"
+		},
+		{
+			"displayName": "GroupLabel",
+			"preferredDisplayName": "Menu.GroupLabel",
+			"filePath": "./group-label.tsx"
+		},
+		{
+			"displayName": "Separator",
+			"preferredDisplayName": "Menu.Separator",
+			"filePath": "./separator.tsx"
+		},
+		{
+			"displayName": "SubmenuTriggerItem",
+			"preferredDisplayName": "Menu.SubmenuTriggerItem",
+			"filePath": "./submenu-trigger-item.tsx"
+		}
+	]
+}

package/src/menu/group-label.tsx

@@ -7,16 +7,16 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
+import { Context } from './context';
 import { Text } from '../text';
-import type { MenuGroupLabelProps } from './types';
+import type { GroupLabelProps } from './types';
 import * as Styled from './styles';
 
-export const MenuGroupLabel = forwardRef<
+export const GroupLabel = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuGroupLabelProps, 'div', false >
->( function MenuGroup( props, ref ) {
-	const menuContext = useContext( MenuContext );
+	WordPressComponentProps< GroupLabelProps, 'div', false >
+>( function Group( props, ref ) {
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -25,7 +25,7 @@ export const MenuGroupLabel = forwardRef<
 	}
 
 	return (
-		<Styled.MenuGroupLabel
+		<Styled.GroupLabel
 			ref={ ref }
 			render={
 				// @ts-expect-error The `children` prop is passed

package/src/menu/group.tsx

@@ -7,15 +7,15 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
-import type { MenuGroupProps } from './types';
+import { Context } from './context';
+import type { GroupProps } from './types';
 import * as Styled from './styles';
 
-export const MenuGroup = forwardRef<
+export const Group = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuGroupProps, 'div', false >
->( function MenuGroup( props, ref ) {
-	const menuContext = useContext( MenuContext );
+	WordPressComponentProps< GroupProps, 'div', false >
+>( function Group( props, ref ) {
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -24,10 +24,6 @@ export const MenuGroup = forwardRef<
 	}
 
 	return (
-		<Styled.MenuGroup
-			ref={ ref }
-			{ ...props }
-			store={ menuContext.store }
-		/>
+		<Styled.Group ref={ ref } { ...props } store={ menuContext.store } />
 	);
 } );

package/src/menu/index.tsx

@@ -13,21 +13,21 @@ import { isRTL as isRTLFn } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { useContextSystem, contextConnectWithoutRef } from '../context';
-import type { MenuContext as MenuContextType, MenuProps } from './types';
-import { MenuContext } from './context';
-import { MenuItem } from './item';
-import { MenuCheckboxItem } from './checkbox-item';
-import { MenuRadioItem } from './radio-item';
-import { MenuGroup } from './group';
-import { MenuGroupLabel } from './group-label';
-import { MenuSeparator } from './separator';
-import { MenuItemLabel } from './item-label';
-import { MenuItemHelpText } from './item-help-text';
-import { MenuTriggerButton } from './trigger-button';
-import { MenuSubmenuTriggerItem } from './submenu-trigger-item';
-import { MenuPopover } from './popover';
+import type { ContextProps, Props } from './types';
+import { Context } from './context';
+import { Item } from './item';
+import { CheckboxItem } from './checkbox-item';
+import { RadioItem } from './radio-item';
+import { Group } from './group';
+import { GroupLabel } from './group-label';
+import { Separator } from './separator';
+import { ItemLabel } from './item-label';
+import { ItemHelpText } from './item-help-text';
+import { TriggerButton } from './trigger-button';
+import { SubmenuTriggerItem } from './submenu-trigger-item';
+import { Popover } from './popover';
 
-const UnconnectedMenu = ( props: MenuProps ) => {
+const UnconnectedMenu = ( props: Props ) => {
 	const {
 		children,
 		defaultOpen = false,
@@ -39,10 +39,10 @@ const UnconnectedMenu = ( props: MenuProps ) => {
 		variant,
 	} = useContextSystem<
 		// @ts-expect-error TODO: missing 'className' in MenuProps
-		typeof props & Pick< MenuContextType, 'variant' >
+		typeof props & Pick< ContextProps, 'variant' >
 	>( props, 'Menu' );
 
-	const parentContext = useContext( MenuContext );
+	const parentContext = useContext( Context );
 
 	const rtl = isRTLFn();
 
@@ -84,49 +84,119 @@ const UnconnectedMenu = ( props: MenuProps ) => {
 	);
 
 	return (
-		<MenuContext.Provider value={ contextValue }>
-			{ children }
-		</MenuContext.Provider>
+		<Context.Provider value={ contextValue }>{ children }</Context.Provider>
 	);
 };
 
+/**
+ * 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.
+ */
 export const Menu = Object.assign(
 	contextConnectWithoutRef( UnconnectedMenu, 'Menu' ),
 	{
-		Context: Object.assign( MenuContext, {
+		Context: Object.assign( Context, {
 			displayName: 'Menu.Context',
 		} ),
-		Item: Object.assign( MenuItem, {
+		/**
+		 * 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( Item, {
 			displayName: 'Menu.Item',
 		} ),
-		RadioItem: Object.assign( MenuRadioItem, {
+		/**
+		 * 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( RadioItem, {
 			displayName: 'Menu.RadioItem',
 		} ),
-		CheckboxItem: Object.assign( MenuCheckboxItem, {
+		/**
+		 * 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( CheckboxItem, {
 			displayName: 'Menu.CheckboxItem',
 		} ),
-		Group: Object.assign( MenuGroup, {
+		/**
+		 * 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( Group, {
 			displayName: 'Menu.Group',
 		} ),
-		GroupLabel: Object.assign( MenuGroupLabel, {
+		/**
+		 * 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( GroupLabel, {
 			displayName: 'Menu.GroupLabel',
 		} ),
-		Separator: Object.assign( MenuSeparator, {
+		/**
+		 * Renders a divider between menu items or menu groups.
+		 */
+		Separator: Object.assign( Separator, {
 			displayName: 'Menu.Separator',
 		} ),
-		ItemLabel: Object.assign( MenuItemLabel, {
+		/**
+		 * Renders a menu item's label text. It should be wrapped with `Menu.Item`,
+		 * `Menu.RadioItem`, or `Menu.CheckboxItem`.
+		 */
+		ItemLabel: Object.assign( ItemLabel, {
 			displayName: 'Menu.ItemLabel',
 		} ),
-		ItemHelpText: Object.assign( MenuItemHelpText, {
+		/**
+		 * Renders a menu item's help text. It should be wrapped with `Menu.Item`,
+		 * `Menu.RadioItem`, or `Menu.CheckboxItem`.
+		 */
+		ItemHelpText: Object.assign( ItemHelpText, {
 			displayName: 'Menu.ItemHelpText',
 		} ),
-		Popover: Object.assign( MenuPopover, {
+		/**
+		 * 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( Popover, {
 			displayName: 'Menu.Popover',
 		} ),
-		TriggerButton: Object.assign( MenuTriggerButton, {
+		/**
+		 * Renders a menu button that toggles the visibility of a sibling
+		 * `Menu.Popover` component when clicked or when using arrow keys.
+		 */
+		TriggerButton: Object.assign( TriggerButton, {
 			displayName: 'Menu.TriggerButton',
 		} ),
-		SubmenuTriggerItem: Object.assign( MenuSubmenuTriggerItem, {
+		/**
+		 * 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( SubmenuTriggerItem, {
 			displayName: 'Menu.SubmenuTriggerItem',
 		} ),
 	}

package/src/menu/item-help-text.tsx

@@ -7,14 +7,14 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
+import { Context } from './context';
 import * as Styled from './styles';
 
-export const MenuItemHelpText = forwardRef<
+export const ItemHelpText = forwardRef<
 	HTMLSpanElement,
 	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function MenuItemHelpText( props, ref ) {
-	const menuContext = useContext( MenuContext );
+>( function ItemHelpText( props, ref ) {
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -22,7 +22,5 @@ export const MenuItemHelpText = forwardRef<
 		);
 	}
 
-	return (
-		<Styled.MenuItemHelpText numberOfLines={ 2 } ref={ ref } { ...props } />
-	);
+	return <Styled.ItemHelpText numberOfLines={ 2 } ref={ ref } { ...props } />;
 } );

package/src/menu/item-label.tsx

@@ -7,14 +7,14 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
+import { Context } from './context';
 import * as Styled from './styles';
 
-export const MenuItemLabel = forwardRef<
+export const ItemLabel = forwardRef<
 	HTMLSpanElement,
 	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function MenuItemLabel( props, ref ) {
-	const menuContext = useContext( MenuContext );
+>( function ItemLabel( props, ref ) {
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -22,7 +22,5 @@ export const MenuItemLabel = forwardRef<
 		);
 	}
 
-	return (
-		<Styled.MenuItemLabel numberOfLines={ 1 } ref={ ref } { ...props } />
-	);
+	return <Styled.ItemLabel numberOfLines={ 1 } ref={ ref } { ...props } />;
 } );

package/src/menu/item.tsx

@@ -7,14 +7,14 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import type { MenuItemProps } from './types';
+import type { ItemProps } from './types';
 import * as Styled from './styles';
-import { MenuContext } from './context';
+import { Context } from './context';
 
-export const MenuItem = forwardRef<
+export const Item = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuItemProps, 'div', false >
->( function MenuItem(
+	WordPressComponentProps< ItemProps, 'div', false >
+>( function Item(
 	{
 		prefix,
 		suffix,
@@ -26,7 +26,7 @@ export const MenuItem = forwardRef<
 	},
 	ref
 ) {
-	const menuContext = useContext( MenuContext );
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -41,7 +41,7 @@ export const MenuItem = forwardRef<
 	const computedStore = store ?? menuContext.store;
 
 	return (
-		<Styled.MenuItem
+		<Styled.Item
 			ref={ ref }
 			{ ...props }
 			accessibleWhenDisabled
@@ -51,17 +51,17 @@ export const MenuItem = forwardRef<
 		>
 			<Styled.ItemPrefixWrapper>{ prefix }</Styled.ItemPrefixWrapper>
 
-			<Styled.MenuItemContentWrapper>
-				<Styled.MenuItemChildrenWrapper>
+			<Styled.ItemContentWrapper>
+				<Styled.ItemChildrenWrapper>
 					{ children }
-				</Styled.MenuItemChildrenWrapper>
+				</Styled.ItemChildrenWrapper>
 
 				{ suffix && (
 					<Styled.ItemSuffixWrapper>
 						{ suffix }
 					</Styled.ItemSuffixWrapper>
 				) }
-			</Styled.MenuItemContentWrapper>
-		</Styled.MenuItem>
+			</Styled.ItemContentWrapper>
+		</Styled.Item>
 	);
 } );

package/src/menu/popover.tsx

@@ -17,18 +17,18 @@ import {
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import type { MenuPopoverProps } from './types';
+import type { PopoverProps } from './types';
 import * as Styled from './styles';
-import { MenuContext } from './context';
+import { Context } from './context';
 
-export const MenuPopover = forwardRef<
+export const Popover = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuPopoverProps, 'div', false >
->( function MenuPopover(
+	WordPressComponentProps< PopoverProps, 'div', false >
+>( function Popover(
 	{ gutter, children, shift, modal = true, ...otherProps },
 	ref
 ) {
-	const menuContext = useContext( MenuContext );
+	const menuContext = useContext( Context );
 
 	// Extract the side from the applied placement — useful for animations.
 	// Using `currentPlacement` instead of `placement` to make sure that we
@@ -92,9 +92,9 @@ export const MenuPopover = forwardRef<
 				// container scales with a different factor than its contents.
 				// The {...renderProps} are passed to the inner wrapper, so that the
 				// menu element is the direct parent of the menu item elements.
-				<Styled.MenuPopoverOuterWrapper variant={ menuContext.variant }>
-					<Styled.MenuPopoverInnerWrapper { ...renderProps } />
-				</Styled.MenuPopoverOuterWrapper>
+				<Styled.PopoverOuterWrapper variant={ menuContext.variant }>
+					<Styled.PopoverInnerWrapper { ...renderProps } />
+				</Styled.PopoverOuterWrapper>
 			) }
 		>
 			{ children }

package/src/menu/radio-item.tsx

@@ -13,8 +13,8 @@ import { Icon } from '@wordpress/icons';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
-import type { MenuRadioItemProps } from './types';
+import { Context } from './context';
+import type { RadioItemProps } from './types';
 import * as Styled from './styles';
 import { SVG, Circle } from '@wordpress/primitives';
 
@@ -24,14 +24,14 @@ const radioCheck = (
 	</SVG>
 );
 
-export const MenuRadioItem = forwardRef<
+export const RadioItem = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< MenuRadioItemProps, 'div', false >
->( function MenuRadioItem(
+	WordPressComponentProps< RadioItemProps, 'div', false >
+>( function RadioItem(
 	{ suffix, children, disabled = false, hideOnClick = false, ...props },
 	ref
 ) {
-	const menuContext = useContext( MenuContext );
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -40,7 +40,7 @@ export const MenuRadioItem = forwardRef<
 	}
 
 	return (
-		<Styled.MenuRadioItem
+		<Styled.RadioItem
 			ref={ ref }
 			{ ...props }
 			accessibleWhenDisabled
@@ -57,17 +57,17 @@ export const MenuRadioItem = forwardRef<
 				<Icon icon={ radioCheck } size={ 24 } />
 			</Ariakit.MenuItemCheck>
 
-			<Styled.MenuItemContentWrapper>
-				<Styled.MenuItemChildrenWrapper>
+			<Styled.ItemContentWrapper>
+				<Styled.ItemChildrenWrapper>
 					{ children }
-				</Styled.MenuItemChildrenWrapper>
+				</Styled.ItemChildrenWrapper>
 
 				{ suffix && (
 					<Styled.ItemSuffixWrapper>
 						{ suffix }
 					</Styled.ItemSuffixWrapper>
 				) }
-			</Styled.MenuItemContentWrapper>
-		</Styled.MenuRadioItem>
+			</Styled.ItemContentWrapper>
+		</Styled.RadioItem>
 	);
 } );

package/src/menu/separator.tsx

@@ -7,15 +7,15 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { MenuContext } from './context';
-import type { MenuSeparatorProps } from './types';
+import { Context } from './context';
+import type { SeparatorProps } from './types';
 import * as Styled from './styles';
 
-export const MenuSeparator = forwardRef<
+export const Separator = forwardRef<
 	HTMLHRElement,
-	WordPressComponentProps< MenuSeparatorProps, 'hr', false >
->( function MenuSeparator( props, ref ) {
-	const menuContext = useContext( MenuContext );
+	WordPressComponentProps< SeparatorProps, 'hr', false >
+>( function Separator( props, ref ) {
+	const menuContext = useContext( Context );
 
 	if ( ! menuContext?.store ) {
 		throw new Error(
@@ -24,7 +24,7 @@ export const MenuSeparator = forwardRef<
 	}
 
 	return (
-		<Styled.MenuSeparator
+		<Styled.Separator
 			ref={ ref }
 			{ ...props }
 			store={ menuContext.store }

package/src/menu/stories/best-practices.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/blocks';
+
+import * as MenuStories from './index.story';
+
+<Meta of={ MenuStories } name="Best Practices" />
+
+# Menu
+
+## Usage
+
+### When to use a `Menu`
+
+Use a `Menu` when you want users to:
+
+-   Choose an action or change a setting from a list, AND
+-   Only see the available choices contextually.
+
+`Menu` is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.
+
+If you need to display all the available options at all times, consider using a Toolbar instead. Use a `Menu` to display a list of actions after the user interacts with a button.
+
+**Do**
+Use a `Menu` to display a list of actions after the user interacts with an icon.
+
+**Don’t** use a `Menu` for important actions that should always be visible. Use a `Toolbar` instead.
+
+**Don’t**
+Don’t use a `Menu` for frequently used actions. Use a `Toolbar` instead.
+
+### Behavior
+
+Generally, the parent button should indicate that interacting with it will show a `Menu`.
+
+The parent button should retain the same visual styling regardless of whether the `Menu` is displayed or not.
+
+### Placement
+
+The `Menu` should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full `Menu`, it can be displayed instead above the parent button.