@wordpress/components 28.10.0 → 28.12.0

package/src/{dropdown-menu-v2 → menu}/README.md

@@ -1,51 +1,51 @@
-# `DropdownMenuV2`
+# `Menu`
 
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-`DropdownMenuV2` displays a menu to the user (such as a set of actions or functions) triggered by a button.
+`Menu` displays a menu to the user (such as a set of actions or functions). The menu is rendered in a popover (this pattern is also known as a "Dropdown menu"), which is triggered by a button.
 
 ## Design guidelines
 
 ### Usage
 
-#### When to use a DropdownMenu
+#### When to use a `Menu`
 
-Use a DropdownMenu when you want users to:
+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.
 
-`DropdownMenu` 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.
+`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 `DropdownMenu` to display a list of actions after the user interacts with a 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 `DropdownMenu` to display a list of actions after the user interacts with an icon.
+Use a `Menu` to display a list of actions after the user interacts with an icon.
 
-**Don’t** use a `DropdownMenu` for important actions that should always be visible. Use a `Toolbar` instead.
+**Don’t** use a `Menu` for important actions that should always be visible. Use a `Toolbar` instead.
 
 **Don’t**
-Don’t use a `DropdownMenu` for frequently used actions. Use a `Toolbar` instead.
+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 `DropdownMenu`.
+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 `DropdownMenu` is displayed or not.
+The parent button should retain the same visual styling regardless of whether the `Menu` is displayed or not.
 
 #### Placement
 
-The `DropdownMenu` 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 `DropdownMenu`, it can be displayed instead above the parent button.
+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.
 
 ## Development guidelines
 
 This component is still highly experimental, and it's not normally accessible to consumers of the `@wordpress/components` package.
 
-The component exposes a set of components that are meant to be used in combination with each other in order to implement a `DropdownMenu` correctly.
+The component exposes a set of components that are meant to be used in combination with each other in order to implement a `Menu` correctly.
 
-### `DropdownMenuV2`
+### `Menu`
 
 The root component, used to specify the menu's trigger and its contents.
 
@@ -55,45 +55,45 @@ The component accepts the following props:
 
 ##### `trigger`: `React.ReactNode`
 
-The trigger button
+The button triggering the menu popover.
 
 -   Required: yes
 
 ##### `children`: `React.ReactNode`
 
-The contents of the dropdown
+The contents of the menu (ie. one or more menu items).
 
 -   Required: yes
 
 ##### `defaultOpen`: `boolean`
 
-The open state of the dropdown menu when it is initially rendered. Use when not wanting to control its open state.
+The open state of the menu popover when it is initially rendered. Use when not wanting to control its open state.
 
 -   Required: no
 -   Default: `false`
 
 ##### `open`: `boolean`
 
-The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`.
+The controlled open state of the menu popover. Must be used in conjunction with `onOpenChange`.
 
 -   Required: no
 
 ##### `onOpenChange`: `(open: boolean) => void`
 
-Event handler called when the open state of the dropdown menu changes.
+Event handler called when the open state of the menu popover changes.
 
 -   Required: no
 
 ##### `modal`: `boolean`
 
-The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
+The modality of the menu popover. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
 
 -   Required: no
 -   Default: `true`
 
 ##### `placement`: ``'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
 
-The placement of the dropdown menu popover.
+The placement of the menu popover.
 
 -   Required: no
 -   Default: `'bottom-start'` for root-level menus, `'right-start'` for nested menus
@@ -112,7 +112,7 @@ The skidding of the popover along the anchor element. Can be set to negative val
 -   Required: no
 -   Default: `0` for root-level menus, `-8` for nested menus
 
-### `DropdownMenuV2.Item`
+### `Menu.Item`
 
 Used to render a menu item.
 
@@ -140,7 +140,7 @@ The contents of the item's suffix.
 
 ##### `hideOnClick`: `boolean`
 
-Whether to hide the dropdown menu when the menu item is clicked.
+Whether to hide the menu popover when the menu item is clicked.
 
 -   Required: no
 -   Default: `true`
@@ -152,7 +152,7 @@ Determines if the element is disabled.
 -   Required: no
 -   Default: `false`
 
-### `DropdownMenuV2.CheckboxItem`
+### `Menu.CheckboxItem`
 
 Used to render a checkbox item.
 
@@ -174,7 +174,7 @@ The contents of the item's suffix.
 
 ##### `hideOnClick`: `boolean`
 
-Whether to hide the dropdown menu when the menu item is clicked.
+Whether to hide the menu popover when the menu item is clicked.
 
 -   Required: no
 -   Default: `false`
@@ -218,7 +218,7 @@ Event handler called when the checked state of the checkbox menu item changes.
 
 -   Required: no
 
-### `DropdownMenuV2.RadioItem`
+### `Menu.RadioItem`
 
 Used to render a radio item.
 
@@ -240,7 +240,7 @@ The contents of the item's suffix.
 
 ##### `hideOnClick`: `boolean`
 
-Whether to hide the dropdown menu when the menu item is clicked.
+Whether to hide the menu popover when the menu item is clicked.
 
 -   Required: no
 -   Default: `false`
@@ -283,7 +283,7 @@ Event handler called when the checked radio menu item changes.
 
 -   Required: no
 
-### `DropdownMenuV2.ItemLabel`
+### `Menu.ItemLabel`
 
 Used to render the menu item's label.
 
@@ -297,7 +297,7 @@ The label contents.
 
 -   Required: yes
 
-### `DropdownMenuV2.ItemHelpText`
+### `Menu.ItemHelpText`
 
 Used to render the menu item's help text.
 
@@ -311,7 +311,7 @@ The help text contents.
 
 -   Required: yes
 
-### `DropdownMenuV2.Group`
+### `Menu.Group`
 
 Used to group menu items.
 
@@ -321,11 +321,11 @@ The component accepts the following props:
 
 ##### `children`: `React.ReactNode`
 
-The contents of the group.
+The contents of the menu group (ie. an optional menu group label and one or more menu items).
 
 -   Required: yes
 
-### `DropdownMenuV2.GroupLabel`
+### `Menu.GroupLabel`
 
 Used to render a group label. The label text should be kept as short as possible.
 
@@ -335,10 +335,10 @@ The component accepts the following props:
 
 ##### `children`: `React.ReactNode`
 
-The contents of the group label.
+The contents of the menu group label.
 
 -   Required: yes
 
-### `DropdownMenuV2.Separator`
+### `Menu.Separator`
 
 Used to render a visual separator.

package/src/{dropdown-menu-v2 → menu}/checkbox-item.tsx

@@ -13,33 +13,33 @@ import { Icon, check } from '@wordpress/icons';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { DropdownMenuContext } from './context';
-import type { DropdownMenuCheckboxItemProps } from './types';
+import { MenuContext } from './context';
+import type { MenuCheckboxItemProps } from './types';
 import * as Styled from './styles';
 import { useTemporaryFocusVisibleFix } from './use-temporary-focus-visible-fix';
 
-export const DropdownMenuCheckboxItem = forwardRef<
+export const MenuCheckboxItem = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< DropdownMenuCheckboxItemProps, 'div', false >
->( function DropdownMenuCheckboxItem(
+	WordPressComponentProps< MenuCheckboxItemProps, 'div', false >
+>( function MenuCheckboxItem(
 	{ suffix, children, onBlur, hideOnClick = false, ...props },
 	ref
 ) {
 	// TODO: Remove when https://github.com/ariakit/ariakit/issues/4083 is fixed
 	const focusVisibleFixProps = useTemporaryFocusVisibleFix( { onBlur } );
-	const dropdownMenuContext = useContext( DropdownMenuContext );
+	const menuContext = useContext( MenuContext );
 
 	return (
-		<Styled.DropdownMenuCheckboxItem
+		<Styled.MenuCheckboxItem
 			ref={ ref }
 			{ ...props }
 			{ ...focusVisibleFixProps }
 			accessibleWhenDisabled
 			hideOnClick={ hideOnClick }
-			store={ dropdownMenuContext?.store }
+			store={ menuContext?.store }
 		>
 			<Ariakit.MenuItemCheck
-				store={ dropdownMenuContext?.store }
+				store={ menuContext?.store }
 				render={ <Styled.ItemPrefixWrapper /> }
 				// Override some ariakit inline styles
 				style={ { width: 'auto', height: 'auto' } }
@@ -47,17 +47,17 @@ export const DropdownMenuCheckboxItem = forwardRef<
 				<Icon icon={ check } size={ 24 } />
 			</Ariakit.MenuItemCheck>
 
-			<Styled.DropdownMenuItemContentWrapper>
-				<Styled.DropdownMenuItemChildrenWrapper>
+			<Styled.MenuItemContentWrapper>
+				<Styled.MenuItemChildrenWrapper>
 					{ children }
-				</Styled.DropdownMenuItemChildrenWrapper>
+				</Styled.MenuItemChildrenWrapper>
 
 				{ suffix && (
 					<Styled.ItemSuffixWrapper>
 						{ suffix }
 					</Styled.ItemSuffixWrapper>
 				) }
-			</Styled.DropdownMenuItemContentWrapper>
-		</Styled.DropdownMenuCheckboxItem>
+			</Styled.MenuItemContentWrapper>
+		</Styled.MenuCheckboxItem>
 	);
 } );

package/src/menu/context.tsx

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

package/src/{dropdown-menu-v2 → menu}/group-label.tsx

@@ -7,18 +7,18 @@ import { forwardRef, useContext } from '@wordpress/element';
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { DropdownMenuContext } from './context';
+import { MenuContext } from './context';
 import { Text } from '../text';
-import type { DropdownMenuGroupLabelProps } from './types';
+import type { MenuGroupLabelProps } from './types';
 import * as Styled from './styles';
 
-export const DropdownMenuGroupLabel = forwardRef<
+export const MenuGroupLabel = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< DropdownMenuGroupLabelProps, 'div', false >
->( function DropdownMenuGroup( props, ref ) {
-	const dropdownMenuContext = useContext( DropdownMenuContext );
+	WordPressComponentProps< MenuGroupLabelProps, 'div', false >
+>( function MenuGroup( props, ref ) {
+	const menuContext = useContext( MenuContext );
 	return (
-		<Styled.DropdownMenuGroupLabel
+		<Styled.MenuGroupLabel
 			ref={ ref }
 			render={
 				// @ts-expect-error The `children` prop is passed
@@ -31,7 +31,7 @@ export const DropdownMenuGroupLabel = forwardRef<
 				/>
 			}
 			{ ...props }
-			store={ dropdownMenuContext?.store }
+			store={ menuContext?.store }
 		/>
 	);
 } );

package/src/menu/group.tsx

@@ -0,0 +1,26 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../context';
+import { MenuContext } from './context';
+import type { MenuGroupProps } from './types';
+import * as Styled from './styles';
+
+export const MenuGroup = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< MenuGroupProps, 'div', false >
+>( function MenuGroup( props, ref ) {
+	const menuContext = useContext( MenuContext );
+	return (
+		<Styled.MenuGroup
+			ref={ ref }
+			{ ...props }
+			store={ menuContext?.store }
+		/>
+	);
+} );

package/src/{dropdown-menu-v2 → menu}/index.tsx

@@ -22,23 +22,20 @@ import { chevronRightSmall } from '@wordpress/icons';
  */
 import { useContextSystem, contextConnect } from '../context';
 import type { WordPressComponentProps } from '../context';
-import type {
-	DropdownMenuContext as DropdownMenuContextType,
-	DropdownMenuProps,
-} from './types';
+import type { MenuContext as MenuContextType, MenuProps } from './types';
 import * as Styled from './styles';
-import { DropdownMenuContext } from './context';
-import { DropdownMenuItem } from './item';
-import { DropdownMenuCheckboxItem } from './checkbox-item';
-import { DropdownMenuRadioItem } from './radio-item';
-import { DropdownMenuGroup } from './group';
-import { DropdownMenuGroupLabel } from './group-label';
-import { DropdownMenuSeparator } from './separator';
-import { DropdownMenuItemLabel } from './item-label';
-import { DropdownMenuItemHelpText } from './item-help-text';
-
-const UnconnectedDropdownMenu = (
-	props: WordPressComponentProps< DropdownMenuProps, 'div', false >,
+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';
+
+const UnconnectedMenu = (
+	props: WordPressComponentProps< MenuProps, 'div', false >,
 	ref: React.ForwardedRef< HTMLDivElement >
 ) => {
 	const {
@@ -62,17 +59,18 @@ const UnconnectedDropdownMenu = (
 
 		// Rest
 		...otherProps
-	} = useContextSystem<
-		typeof props & Pick< DropdownMenuContextType, 'variant' >
-	>( props, 'DropdownMenu' );
+	} = useContextSystem< typeof props & Pick< MenuContextType, 'variant' > >(
+		props,
+		'Menu'
+	);
 
-	const parentContext = useContext( DropdownMenuContext );
+	const parentContext = useContext( MenuContext );
 
 	const computedDirection = isRTL() ? 'rtl' : 'ltr';
 
 	// If an explicit value for the `placement` prop is not passed,
-	// apply a default placement of `bottom-start` for the root dropdown,
-	// and of `right-start` for nested dropdowns.
+	// apply a default placement of `bottom-start` for the root menu popover,
+	// and of `right-start` for nested menu popovers.
 	let computedPlacement =
 		props.placement ??
 		( parentContext?.store ? 'right-start' : 'bottom-start' );
@@ -91,7 +89,7 @@ const UnconnectedDropdownMenu = (
 		}
 	}
 
-	const dropdownMenuStore = Ariakit.useMenuStore( {
+	const menuStore = Ariakit.useMenuStore( {
 		parent: parentContext?.store,
 		open,
 		defaultOpen,
@@ -104,25 +102,25 @@ const UnconnectedDropdownMenu = (
 	} );
 
 	const contextValue = useMemo(
-		() => ( { store: dropdownMenuStore, variant } ),
-		[ dropdownMenuStore, variant ]
+		() => ( { store: menuStore, variant } ),
+		[ menuStore, variant ]
 	);
 
 	// Extract the side from the applied placement — useful for animations.
 	// Using `currentPlacement` instead of `placement` to make sure that we
 	// use the final computed placement (including "flips" etc).
 	const appliedPlacementSide = useStoreState(
-		dropdownMenuStore,
+		menuStore,
 		'currentPlacement'
 	).split( '-' )[ 0 ];
 
 	if (
-		dropdownMenuStore.parent &&
-		! ( isValidElement( trigger ) && DropdownMenuItem === trigger.type )
+		menuStore.parent &&
+		! ( isValidElement( trigger ) && MenuItem === trigger.type )
 	) {
 		// eslint-disable-next-line no-console
 		console.warn(
-			'For nested DropdownMenus, the `trigger` should always be a `DropdownMenuItem`.'
+			'For nested Menus, the `trigger` should always be a `MenuItem`.'
 		);
 	}
 
@@ -153,9 +151,9 @@ const UnconnectedDropdownMenu = (
 			{ /* Menu trigger */ }
 			<Ariakit.MenuButton
 				ref={ ref }
-				store={ dropdownMenuStore }
+				store={ menuStore }
 				render={
-					dropdownMenuStore.parent
+					menuStore.parent
 						? cloneElement( trigger, {
 								// Add submenu arrow, unless a `suffix` is explicitly specified
 								suffix: (
@@ -178,13 +176,13 @@ const UnconnectedDropdownMenu = (
 			<Ariakit.Menu
 				{ ...otherProps }
 				modal={ modal }
-				store={ dropdownMenuStore }
+				store={ menuStore }
 				// Root menu has an 8px distance from its trigger,
 				// otherwise 0 (which causes the submenu to slightly overlap)
-				gutter={ gutter ?? ( dropdownMenuStore.parent ? 0 : 8 ) }
+				gutter={ gutter ?? ( menuStore.parent ? 0 : 8 ) }
 				// Align nested menu by the same (but opposite) amount
 				// as the menu container's padding.
-				shift={ shift ?? ( dropdownMenuStore.parent ? -4 : 0 ) }
+				shift={ shift ?? ( menuStore.parent ? -4 : 0 ) }
 				hideOnHoverOutside={ false }
 				data-side={ appliedPlacementSide }
 				wrapperProps={ wrapperProps }
@@ -200,45 +198,42 @@ const UnconnectedDropdownMenu = (
 					</Styled.MenuPopoverOuterWrapper>
 				) }
 			>
-				<DropdownMenuContext.Provider value={ contextValue }>
+				<MenuContext.Provider value={ contextValue }>
 					{ children }
-				</DropdownMenuContext.Provider>
+				</MenuContext.Provider>
 			</Ariakit.Menu>
 		</>
 	);
 };
 
-export const DropdownMenuV2 = Object.assign(
-	contextConnect( UnconnectedDropdownMenu, 'DropdownMenu' ),
-	{
-		Context: Object.assign( DropdownMenuContext, {
-			displayName: 'DropdownMenuV2.Context',
-		} ),
-		Item: Object.assign( DropdownMenuItem, {
-			displayName: 'DropdownMenuV2.Item',
-		} ),
-		RadioItem: Object.assign( DropdownMenuRadioItem, {
-			displayName: 'DropdownMenuV2.RadioItem',
-		} ),
-		CheckboxItem: Object.assign( DropdownMenuCheckboxItem, {
-			displayName: 'DropdownMenuV2.CheckboxItem',
-		} ),
-		Group: Object.assign( DropdownMenuGroup, {
-			displayName: 'DropdownMenuV2.Group',
-		} ),
-		GroupLabel: Object.assign( DropdownMenuGroupLabel, {
-			displayName: 'DropdownMenuV2.GroupLabel',
-		} ),
-		Separator: Object.assign( DropdownMenuSeparator, {
-			displayName: 'DropdownMenuV2.Separator',
-		} ),
-		ItemLabel: Object.assign( DropdownMenuItemLabel, {
-			displayName: 'DropdownMenuV2.ItemLabel',
-		} ),
-		ItemHelpText: Object.assign( DropdownMenuItemHelpText, {
-			displayName: 'DropdownMenuV2.ItemHelpText',
-		} ),
-	}
-);
-
-export default DropdownMenuV2;
+export const Menu = Object.assign( contextConnect( UnconnectedMenu, 'Menu' ), {
+	Context: Object.assign( MenuContext, {
+		displayName: 'Menu.Context',
+	} ),
+	Item: Object.assign( MenuItem, {
+		displayName: 'Menu.Item',
+	} ),
+	RadioItem: Object.assign( MenuRadioItem, {
+		displayName: 'Menu.RadioItem',
+	} ),
+	CheckboxItem: Object.assign( MenuCheckboxItem, {
+		displayName: 'Menu.CheckboxItem',
+	} ),
+	Group: Object.assign( MenuGroup, {
+		displayName: 'Menu.Group',
+	} ),
+	GroupLabel: Object.assign( MenuGroupLabel, {
+		displayName: 'Menu.GroupLabel',
+	} ),
+	Separator: Object.assign( MenuSeparator, {
+		displayName: 'Menu.Separator',
+	} ),
+	ItemLabel: Object.assign( MenuItemLabel, {
+		displayName: 'Menu.ItemLabel',
+	} ),
+	ItemHelpText: Object.assign( MenuItemHelpText, {
+		displayName: 'Menu.ItemHelpText',
+	} ),
+} );
+
+export default Menu;

package/src/{dropdown-menu-v2 → menu}/item-help-text.tsx

@@ -9,15 +9,11 @@ import { forwardRef } from '@wordpress/element';
 import type { WordPressComponentProps } from '../context';
 import * as Styled from './styles';
 
-export const DropdownMenuItemHelpText = forwardRef<
+export const MenuItemHelpText = forwardRef<
 	HTMLSpanElement,
 	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function DropdownMenuItemHelpText( props, ref ) {
+>( function MenuItemHelpText( props, ref ) {
 	return (
-		<Styled.DropdownMenuItemHelpText
-			numberOfLines={ 2 }
-			ref={ ref }
-			{ ...props }
-		/>
+		<Styled.MenuItemHelpText numberOfLines={ 2 } ref={ ref } { ...props } />
 	);
 } );

package/src/{dropdown-menu-v2 → menu}/item-label.tsx

@@ -9,15 +9,11 @@ import { forwardRef } from '@wordpress/element';
 import type { WordPressComponentProps } from '../context';
 import * as Styled from './styles';
 
-export const DropdownMenuItemLabel = forwardRef<
+export const MenuItemLabel = forwardRef<
 	HTMLSpanElement,
 	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function DropdownMenuItemLabel( props, ref ) {
+>( function MenuItemLabel( props, ref ) {
 	return (
-		<Styled.DropdownMenuItemLabel
-			numberOfLines={ 1 }
-			ref={ ref }
-			{ ...props }
-		/>
+		<Styled.MenuItemLabel numberOfLines={ 1 } ref={ ref } { ...props } />
 	);
 } );