@wordpress/components 28.9.0 → 28.11.0

package/src/disabled/stories/index.story.tsx

@@ -18,7 +18,8 @@ import TextareaControl from '../../textarea-control/';
 import { VStack } from '../../v-stack/';
 
 const meta: Meta< typeof Disabled > = {
-	title: 'Components/Disabled',
+	title: 'Components/Utilities/Disabled',
+	id: 'components-disabled',
 	component: Disabled,
 	argTypes: {
 		as: { control: { type: null } },

package/src/draggable/stories/index.story.tsx

@@ -18,7 +18,8 @@ import Draggable from '..';
 
 const meta: Meta< typeof Draggable > = {
 	component: Draggable,
-	title: 'Components/Draggable',
+	title: 'Components/Utilities/Draggable',
+	id: 'components-draggable',
 	argTypes: {
 		elementId: { control: { type: null } },
 		__experimentalDragComponent: { control: { type: null } },

package/src/drop-zone/index.tsx

@@ -99,6 +99,7 @@ export function DropZoneComponent( {
 			setType( _type );
 		},
 		onDragEnd() {
+			setIsDraggingOverElement( false );
 			setIsDraggingOverDocument( false );
 			setType( undefined );
 		},
@@ -116,8 +117,6 @@ export function DropZoneComponent( {
 			( ( type === 'file' && onFilesDrop ) ||
 				( type === 'html' && onHTMLDrop ) ||
 				( type === 'default' && onDrop ) ),
-		'has-dragged-out': ! isDraggingOverElement,
-		// Keeping the following classnames for legacy purposes
 		'is-dragging-over-document': isDraggingOverDocument,
 		'is-dragging-over-element': isDraggingOverElement,
 		[ `is-dragging-${ type }` ]: !! type,

package/src/drop-zone/style.scss

@@ -42,7 +42,7 @@
 		transform: scale(0.9);
 	}
 
-	&.is-active:not(.has-dragged-out) {
+	&.is-active.is-dragging-over-element {
 		.components-drop-zone__content {
 			opacity: 1;
 

package/src/font-size-picker/index.native.js

@@ -9,7 +9,7 @@ import { View, useWindowDimensions } from 'react-native';
 import { useNavigation } from '@react-navigation/native';
 import { useState } from '@wordpress/element';
 import { Icon, chevronRight, check } from '@wordpress/icons';
-import { __, sprintf } from '@wordpress/i18n';
+import { __, _x, sprintf } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -63,8 +63,8 @@ function FontSizePicker( {
 	} );
 
 	const accessibilityLabel = sprintf(
-		// translators: %1$s: Font size name e.g. Small
-		__( 'Font Size, %1$s' ),
+		// translators: %s: Font size name e.g. Small
+		__( 'Font Size, %s' ),
 		selectedOption.name
 	);
 
@@ -77,8 +77,8 @@ function FontSizePicker( {
 					value={
 						selectedValue
 							? sprintf(
-									// translators: %1$s: Select control font size name e.g. Small, %2$s: Select control font size e.g. 12px
-									__( '%1$s (%2$s)' ),
+									// translators: 1: Select control font size name e.g. Small. 2: Select control font size e.g. 12px
+									_x( '%1$s (%2$s)', 'font size' ),
 									selectedOption.name,
 									selectedPxValue
 							  )
@@ -88,7 +88,7 @@ function FontSizePicker( {
 					accessibilityRole="button"
 					accessibilityLabel={ accessibilityLabel }
 					accessibilityHint={ sprintf(
-						// translators: %s: Select control button label e.g. Small
+						// translators: %s: Select control button label e.g. "Button width"
 						__( 'Navigates to select %s' ),
 						selectedOption.name
 					) }
@@ -143,7 +143,7 @@ function FontSizePicker( {
 								accessibilityLabel={
 									item.sizePx === selectedValue
 										? sprintf(
-												// translators: %s: Select font size option value e.g: "Selected: Large".
+												// translators: %s: The selected option.
 												__( 'Selected: %s' ),
 												item.name
 										  )

package/src/form-token-field/index.tsx

@@ -124,17 +124,14 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		}
 
 		// TODO: updateSuggestions() should first be refactored so its actual deps are clearer.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ suggestions, prevSuggestions, value, prevValue ] );
 
 	useEffect( () => {
 		updateSuggestions();
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ incompleteTokenValue ] );
 
 	useEffect( () => {
 		updateSuggestions();
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ __experimentalAutoSelectFirstMatch ] );
 
 	if ( disabled && isActive ) {

package/src/form-token-field/style.scss

@@ -173,7 +173,6 @@
 	padding: $grid-unit-10 $grid-unit-15;
 	min-height: $button-size-compact;
 	margin: 0;
-	cursor: pointer;
 	box-sizing: border-box;
 
 	&.is-selected {
@@ -189,4 +188,8 @@
 			background-color: $components-color-accent-transparent-40;
 		}
 	}
+
+	&:not(.is-empty) {
+		cursor: pointer;
+	}
 }

package/src/form-token-field/suggestions-list.tsx

@@ -8,6 +8,7 @@ import type { MouseEventHandler, ReactNode } from 'react';
  * WordPress dependencies
  */
 import { useRefEffect } from '@wordpress/compose';
+import { __ } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -156,6 +157,11 @@ export function SuggestionsList<
 				);
 				/* eslint-enable jsx-a11y/click-events-have-key-events */
 			} ) }
+			{ suggestions.length === 0 && (
+				<li className="components-form-token-field__suggestion is-empty">
+					{ __( 'No items found' ) }
+				</li>
+			) }
 		</ul>
 	);
 }

package/src/item-group/stories/index.story.tsx

@@ -37,6 +37,8 @@ const Template: StoryFn< typeof ItemGroup > = ( props ) => (
 
 export const Default: StoryFn< typeof ItemGroup > = Template.bind( {} );
 Default.args = {
+	isBordered: true,
+	isSeparated: true,
 	children: (
 		[
 			{
@@ -67,6 +69,7 @@ export const NonClickableItems: StoryFn< typeof ItemGroup > = Template.bind(
 	{}
 );
 NonClickableItems.args = {
+	...Default.args,
 	children: (
 		[
 			{
@@ -83,6 +86,7 @@ NonClickableItems.args = {
 
 export const CustomItemSize: StoryFn< typeof ItemGroup > = Template.bind( {} );
 CustomItemSize.args = {
+	...Default.args,
 	children: (
 		[
 			{
@@ -98,9 +102,9 @@ CustomItemSize.args = {
 	 ).map( mapPropsToItem ),
 };
 
-export const WithBorder: StoryFn< typeof ItemGroup > = Template.bind( {} );
-WithBorder.args = {
+export const WithoutBorder: StoryFn< typeof ItemGroup > = Template.bind( {} );
+WithoutBorder.args = {
 	...Default.args,
-	isBordered: true,
-	isSeparated: true,
+	isBordered: false,
+	isSeparated: false,
 };

package/src/keyboard-shortcuts/stories/index.story.tsx

@@ -10,7 +10,8 @@ import KeyboardShortcuts from '..';
 
 const meta: Meta< typeof KeyboardShortcuts > = {
 	component: KeyboardShortcuts,
-	title: 'Components/KeyboardShortcuts',
+	title: 'Components/Utilities/KeyboardShortcuts',
+	id: 'components-keyboardshortcuts',
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },

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 }
+		/>
+	);
+} );