@wordpress/components 25.6.1 → 25.8.0

package/src/dropdown/index.tsx

@@ -7,7 +7,7 @@ import type { ForwardedRef } from 'react';
 /**
  * WordPress dependencies
  */
-import { useEffect, useRef, useState } from '@wordpress/element';
+import { useRef, useState } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
 import deprecated from '@wordpress/deprecated';
 
@@ -15,25 +15,10 @@ import deprecated from '@wordpress/deprecated';
  * Internal dependencies
  */
 import { contextConnect, useContextSystem } from '../ui/context';
+import { useControlledValue } from '../utils/hooks';
 import Popover from '../popover';
 import type { DropdownProps, DropdownInternalContext } from './types';
 
-function useObservableState(
-	initialState: boolean,
-	onStateChange?: ( newState: boolean ) => void
-) {
-	const [ state, setState ] = useState( initialState );
-	return [
-		state,
-		( value: boolean ) => {
-			setState( value );
-			if ( onStateChange ) {
-				onStateChange( value );
-			}
-		},
-	] as const;
-}
-
 const UnconnectedDropdown = (
 	props: DropdownProps,
 	forwardedRef: ForwardedRef< any >
@@ -51,6 +36,9 @@ const UnconnectedDropdown = (
 		onToggle,
 		style,
 
+		open,
+		defaultOpen,
+
 		// Deprecated props
 		position,
 
@@ -74,20 +62,12 @@ const UnconnectedDropdown = (
 	const [ fallbackPopoverAnchor, setFallbackPopoverAnchor ] =
 		useState< HTMLDivElement | null >( null );
 	const containerRef = useRef< HTMLDivElement >();
-	const [ isOpen, setIsOpen ] = useObservableState( false, onToggle );
-
-	useEffect(
-		() => () => {
-			if ( onToggle && isOpen ) {
-				onToggle( false );
-			}
-		},
-		[ onToggle, isOpen ]
-	);
 
-	function toggle() {
-		setIsOpen( ! isOpen );
-	}
+	const [ isOpen, setIsOpen ] = useControlledValue( {
+		defaultValue: defaultOpen,
+		value: open,
+		onChange: onToggle,
+	} );
 
 	/**
 	 * Closes the popover when focus leaves it unless the toggle was pressed or
@@ -112,13 +92,15 @@ const UnconnectedDropdown = (
 	}
 
 	function close() {
-		if ( onClose ) {
-			onClose();
-		}
+		onClose?.();
 		setIsOpen( false );
 	}
 
-	const args = { isOpen, onToggle: toggle, onClose: close };
+	const args = {
+		isOpen: !! isOpen,
+		onToggle: () => setIsOpen( ! isOpen ),
+		onClose: close,
+	};
 	const popoverPropsHaveAnchor =
 		!! popoverProps?.anchor ||
 		// Note: `anchorRef`, `getAnchorRect` and `anchorRect` are deprecated and

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, Story } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * Internal dependencies
@@ -10,9 +10,11 @@ import Dropdown from '..';
 import Button from '../../button';
 import { DropdownContentWrapper } from '../dropdown-content-wrapper';
 
-const meta: ComponentMeta< typeof Dropdown > = {
+const meta: Meta< typeof Dropdown > = {
 	title: 'Components/Dropdown',
 	component: Dropdown,
+	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+	subcomponents: { DropdownContentWrapper },
 	argTypes: {
 		focusOnMount: {
 			options: [ 'firstElement', true, false ],
@@ -23,8 +25,13 @@ const meta: ComponentMeta< typeof Dropdown > = {
 		position: { control: { type: null } },
 		renderContent: { control: { type: null } },
 		renderToggle: { control: { type: null } },
+		open: { control: { type: null } },
+		defaultOpen: { control: { type: null } },
+		onToggle: { control: { type: null } },
+		onClose: { control: { type: null } },
 	},
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: {
 			expanded: true,
 		},
@@ -32,15 +39,13 @@ const meta: ComponentMeta< typeof Dropdown > = {
 };
 export default meta;
 
-const Template: Story< typeof Dropdown > = ( args ) => {
-	return (
-		<div style={ { height: 150 } }>
-			<Dropdown { ...args } />
-		</div>
-	);
-};
+const Template: StoryFn< typeof Dropdown > = ( args ) => (
+	<div style={ { height: 150 } }>
+		<Dropdown { ...args } />
+	</div>
+);
 
-export const Default: Story< typeof Dropdown > = Template.bind( {} );
+export const Default = Template.bind( {} );
 Default.args = {
 	renderToggle: ( { isOpen, onToggle } ) => (
 		<Button onClick={ onToggle } aria-expanded={ isOpen } variant="primary">
@@ -54,7 +59,7 @@ Default.args = {
  * To apply more padding to the dropdown content, use the provided `<DropdownContentWrapper>`
  * convenience wrapper. A `paddingSize` of `"medium"` is suitable for relatively larger dropdowns (default is `"small"`).
  */
-export const WithMorePadding: Story< typeof Dropdown > = Template.bind( {} );
+export const WithMorePadding = Template.bind( {} );
 WithMorePadding.args = {
 	...Default.args,
 	renderContent: () => (
@@ -69,7 +74,7 @@ WithMorePadding.args = {
  * with a `paddingSize` of `"none"`. This can also serve as a clean foundation to add arbitrary
  * paddings, for example when child components already have padding on their own.
  */
-export const WithNoPadding: Story< typeof Dropdown > = Template.bind( {} );
+export const WithNoPadding = Template.bind( {} );
 WithNoPadding.args = {
 	...Default.args,
 	renderContent: () => (

package/src/dropdown/types.ts

@@ -62,11 +62,8 @@ export type DropdownProps = {
 	 */
 	onClose?: () => void;
 	/**
-	 * A callback invoked when the state of the popover changes
+	 * A callback invoked when the state of the dropdown changes
 	 * from open to closed and vice versa.
-	 * The callback receives a boolean as a parameter.
-	 * If true, the popover will open.
-	 * If false, the popover will close.
 	 */
 	onToggle?: ( willOpen: boolean ) => void;
 	/**
@@ -111,6 +108,17 @@ export type DropdownProps = {
 	 * @deprecated
 	 */
 	position?: PopoverProps[ 'position' ];
+	/**
+	 * The controlled open state of the dropdown.
+	 * Must be used in conjunction with `onToggle`.
+	 */
+	open?: boolean;
+	/**
+	 * The open state of the dropdown when initially rendered.
+	 * Use when you do not need to control its open state. It will be overridden
+	 * by the `open` prop if it is specified on the component's first render.
+	 */
+	defaultOpen?: boolean;
 };
 
 export type DropdownInternalContext = {

package/src/dropdown-menu/README.md

@@ -198,3 +198,21 @@ In some contexts, the arrow down key used to open the dropdown menu might need t
 
 -   Required: No
 -   Default: `false`
+
+### `defaultOpen`: `boolean`
+
+The open state of the dropdown menu when initially rendered. Use when you do not need to control its open state. It will be overridden by the `open` prop if it is specified on the component's first render.
+
+-   Required: No
+
+### `open`: `boolean`
+
+The controlled open state of the dropdown menu. Must be used in conjunction with `onToggle`.
+
+-   Required: No
+
+### `onToggle`: `( willOpen: boolean ) => void`
+
+A callback invoked when the state of the dropdown changes from open to closed and vice versa.
+
+-   Required: No

package/src/dropdown-menu/index.tsx

@@ -22,7 +22,7 @@ import type {
 } from './types';
 
 function mergeProps<
-	T extends { className?: string; [ key: string ]: unknown }
+	T extends { className?: string; [ key: string ]: unknown },
 >( defaultProps: Partial< T > = {}, props: T = {} as T ) {
 	const mergedProps: T = {
 		...defaultProps,
@@ -57,6 +57,10 @@ function UnconnectedDropdownMenu( dropdownMenuProps: DropdownMenuProps ) {
 		text,
 		noIcons,
 
+		open,
+		defaultOpen,
+		onToggle: onToggleProp,
+
 		// Context
 		variant,
 	} = useContextSystem< DropdownMenuProps & DropdownMenuInternalContext >(
@@ -211,6 +215,9 @@ function UnconnectedDropdownMenu( dropdownMenuProps: DropdownMenuProps ) {
 					</NavigableMenu>
 				);
 			} }
+			open={ open }
+			defaultOpen={ defaultOpen }
+			onToggle={ onToggleProp }
 		/>
 	);
 }

package/src/dropdown-menu/stories/index.story.tsx

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, Story } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
@@ -21,10 +22,11 @@ import {
 	trash,
 } from '@wordpress/icons';
 
-const meta: ComponentMeta< typeof DropdownMenu > = {
+const meta: Meta< typeof DropdownMenu > = {
 	title: 'Components/DropdownMenu',
 	component: DropdownMenu,
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 	},
@@ -34,11 +36,14 @@ const meta: ComponentMeta< typeof DropdownMenu > = {
 			mapping: { menu, chevronDown, more },
 			control: { type: 'select' },
 		},
+		open: { control: { type: null } },
+		defaultOpen: { control: { type: null } },
+		onToggle: { control: { type: null } },
 	},
 };
 export default meta;
 
-const Template: Story< typeof DropdownMenu > = ( props ) => (
+const Template: StoryFn< typeof DropdownMenu > = ( props ) => (
 	<div style={ { height: 150 } }>
 		<DropdownMenu { ...props } />
 	</div>

package/src/dropdown-menu/types.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ReactNode } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 /**
  * Internal dependencies
  */
@@ -13,7 +13,7 @@ import type { NavigableMenuProps } from '../navigable-container/types';
 
 export type DropdownOption = {
 	/**
-	 * The Dashicon icon slug to be shown for the option.
+	 * The icon to be shown for the option.
 	 */
 	icon?: IconProps[ 'icon' ];
 	/**
@@ -29,7 +29,7 @@ export type DropdownOption = {
 	/**
 	 * A callback function to invoke when the option is selected.
 	 */
-	onClick?: () => void;
+	onClick?: ( event?: React.MouseEvent ) => void;
 	/**
 	 * Whether or not the control is currently active.
 	 */
@@ -41,7 +41,7 @@ export type DropdownOption = {
 	/**
 	 * The role to apply to the option's HTML element
 	 */
-	role?: HTMLElement[ 'role' ];
+	role?: HTMLAttributes< HTMLElement >[ 'role' ];
 };
 
 type DropdownCallbackProps = {
@@ -50,7 +50,7 @@ type DropdownCallbackProps = {
 	onClose: () => void;
 };
 
-// Manually including `as` prop because `WordPressComponentProps` polymorhpism
+// Manually including `as` prop because `WordPressComponentProps` polymorphism
 // creates a union that is too large for TypeScript to handle.
 type ToggleProps = Partial<
 	Omit<
@@ -59,11 +59,12 @@ type ToggleProps = Partial<
 	>
 > & {
 	as?: React.ElementType | keyof JSX.IntrinsicElements;
+	'data-toolbar-item'?: boolean;
 };
 
 export type DropdownMenuProps = {
 	/**
-	 * The Dashicon icon slug to be shown in the collapsed menu button.
+	 * The icon to be shown in the collapsed menu button.
 	 *
 	 * @default "menu"
 	 */
@@ -140,6 +141,22 @@ export type DropdownMenuProps = {
 	 * A valid DropdownMenu must specify a `controls` or `children` prop, or both.
 	 */
 	controls?: DropdownOption[] | DropdownOption[][];
+	/**
+	 * The controlled open state of the dropdown menu.
+	 * Must be used in conjunction with `onToggle`.
+	 */
+	open?: boolean;
+	/**
+	 * The open state of the dropdown menu when initially rendered.
+	 * Use when you do not need to control its open state. It will be overridden
+	 * by the `open` prop if it is specified on the component's first render.
+	 */
+	defaultOpen?: boolean;
+	/**
+	 * A callback invoked when the state of the dropdown menu changes
+	 * from open to closed and vice versa.
+	 */
+	onToggle?: ( willOpen: boolean ) => void;
 };
 
 export type DropdownMenuInternalContext = {

package/src/dropdown-menu-v2/stories/index.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta, Story } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 import styled from '@emotion/styled';
 
 /**
@@ -21,8 +21,6 @@ import {
 	DropdownSubMenuTrigger,
 } from '..';
 import Button from '../../button';
-import Popover from '../../popover';
-import { Provider as SlotFillProvider } from '../../slot-fill';
 
 /**
  * WordPress dependencies
@@ -39,6 +37,26 @@ import { ContextSystemProvider } from '../../ui/context';
 const meta: Meta< typeof DropdownMenu > = {
 	title: 'Components (Experimental)/DropdownMenu v2',
 	component: DropdownMenu,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuItem,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownSubMenu,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownSubMenuTrigger,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuSeparator,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuCheckboxItem,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuGroup,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuLabel,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuRadioGroup,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		DropdownMenuRadioItem,
+	},
 	argTypes: {
 		children: { control: { type: null } },
 		trigger: { control: { type: null } },
@@ -122,12 +140,8 @@ const RadioItemsGroup = () => {
 	);
 };
 
-const Template: Story< typeof DropdownMenu > = ( props ) => (
-	<SlotFillProvider>
-		<DropdownMenu { ...props } />
-		{ /* @ts-expect-error Slot is not currently typed on Popover */ }
-		<Popover.Slot />
-	</SlotFillProvider>
+const Template: StoryFn< typeof DropdownMenu > = ( props ) => (
+	<DropdownMenu { ...props } />
 );
 export const Default = Template.bind( {} );
 Default.args = {
@@ -197,7 +211,7 @@ const toolbarVariantContextValue = {
 		variant: 'toolbar',
 	},
 };
-export const ToolbarVariant: Story< typeof DropdownMenu > = ( props ) => (
+export const ToolbarVariant: StoryFn< typeof DropdownMenu > = ( props ) => (
 	<ContextSystemProvider value={ toolbarVariantContextValue }>
 		<DropdownMenu { ...props } />
 	</ContextSystemProvider>

package/src/dropdown-menu-v2/styles.ts

@@ -274,5 +274,5 @@ export const SubmenuRtlChevronIcon = styled( Icon )`
 		{
 			transform: `scaleX(-1) translateX(${ space( 2 ) })`,
 		}
-	)() }
+	) }
 `;

package/src/duotone-picker/README.md

@@ -64,6 +64,20 @@ An array of colors for the duotone effect.
 
 Callback which is called when the duotone colors change.
 
+### `asButtons`: `boolean`
+
+Whether the control should present as a set of buttons, each with its own tab stop.
+
+- Required: No
+- Default: `false`
+
+### `loop`: `boolean`
+
+Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+
+- Required: No
+- Default: `true`
+
 ## DuotoneSwatch Props
 
 ### `values`

package/src/duotone-picker/color-list-picker/index.tsx

@@ -3,6 +3,7 @@
  */
 import { useState } from '@wordpress/element';
 import { swatch } from '@wordpress/icons';
+import { __ } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -13,6 +14,7 @@ import ColorIndicator from '../../color-indicator';
 import Icon from '../../icon';
 import { HStack } from '../../h-stack';
 import type { ColorListPickerProps, ColorOptionProps } from './types';
+import { useInstanceId } from '@wordpress/compose';
 
 function ColorOption( {
 	label,
@@ -23,11 +25,17 @@ function ColorOption( {
 	onChange,
 }: ColorOptionProps ) {
 	const [ isOpen, setIsOpen ] = useState( false );
+	const idRoot = useInstanceId( ColorOption, 'color-list-picker-option' );
+	const labelId = `${ idRoot }__label`;
+	const contentId = `${ idRoot }__content`;
+
 	return (
 		<>
 			<Button
 				className="components-color-list-picker__swatch-button"
 				onClick={ () => setIsOpen( ( prev ) => ! prev ) }
+				aria-expanded={ isOpen }
+				aria-controls={ contentId }
 			>
 				<HStack justify="flex-start" spacing={ 2 }>
 					{ value ? (
@@ -38,20 +46,28 @@ function ColorOption( {
 					) : (
 						<Icon icon={ swatch } />
 					) }
-					<span>{ label }</span>
+					<span id={ labelId }>{ label }</span>
 				</HStack>
 			</Button>
-			{ isOpen && (
-				<ColorPalette
-					className="components-color-list-picker__color-picker"
-					colors={ colors }
-					value={ value }
-					clearable={ false }
-					onChange={ onChange }
-					disableCustomColors={ disableCustomColors }
-					enableAlpha={ enableAlpha }
-				/>
-			) }
+			<div
+				role="group"
+				id={ contentId }
+				aria-labelledby={ labelId }
+				aria-hidden={ ! isOpen }
+			>
+				{ isOpen && (
+					<ColorPalette
+						aria-label={ __( 'Color options' ) }
+						className="components-color-list-picker__color-picker"
+						colors={ colors }
+						value={ value }
+						clearable={ false }
+						onChange={ onChange }
+						disableCustomColors={ disableCustomColors }
+						enableAlpha={ enableAlpha }
+					/>
+				) }
+			</div>
 		</>
 	);
 }

package/src/duotone-picker/duotone-picker.tsx

@@ -55,6 +55,8 @@ import type { DuotonePickerProps } from './types';
  * ```
  */
 function DuotonePicker( {
+	asButtons,
+	loop,
 	clearable = true,
 	unsetable = true,
 	colorPalette,
@@ -63,6 +65,8 @@ function DuotonePicker( {
 	disableCustomDuotone,
 	value,
 	onChange,
+	'aria-label': ariaLabel,
+	'aria-labelledby': ariaLabelledby,
 }: DuotonePickerProps ) {
 	const [ defaultDark, defaultLight ] = useMemo(
 		() => getDefaultColors( colorPalette ),
@@ -120,8 +124,37 @@ function DuotonePicker( {
 		);
 	} );
 
+	let metaProps:
+		| { asButtons: false; loop?: boolean; 'aria-label': string }
+		| { asButtons: false; loop?: boolean; 'aria-labelledby': string }
+		| { asButtons: true };
+
+	if ( asButtons ) {
+		metaProps = { asButtons: true };
+	} else {
+		const _metaProps: { asButtons: false; loop?: boolean } = {
+			asButtons: false,
+			loop,
+		};
+
+		if ( ariaLabel ) {
+			metaProps = { ..._metaProps, 'aria-label': ariaLabel };
+		} else if ( ariaLabelledby ) {
+			metaProps = {
+				..._metaProps,
+				'aria-labelledby': ariaLabelledby,
+			};
+		} else {
+			metaProps = {
+				..._metaProps,
+				'aria-label': __( 'Custom color picker.' ),
+			};
+		}
+	}
+
 	return (
 		<CircularOptionPicker
+			{ ...metaProps }
 			options={ unsetable ? [ unsetOption, ...options ] : options }
 			actions={
 				!! clearable && (

package/src/duotone-picker/stories/duotone-picker.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -14,7 +14,7 @@ import { useState } from '@wordpress/element';
 import { DuotonePicker } from '..';
 import type { DuotonePickerProps } from '../types';
 
-const meta: ComponentMeta< typeof DuotonePicker > = {
+const meta: Meta< typeof DuotonePicker > = {
 	title: 'Components/DuotonePicker',
 	component: DuotonePicker,
 	argTypes: {
@@ -48,10 +48,7 @@ const COLOR_PALETTE = [
 	{ color: '#8c00b7', name: 'Purple', slug: 'purple' },
 ];
 
-const Template: ComponentStory< typeof DuotonePicker > = ( {
-	onChange,
-	...args
-} ) => {
+const Template: StoryFn< typeof DuotonePicker > = ( { onChange, ...args } ) => {
 	const [ value, setValue ] = useState< DuotonePickerProps[ 'value' ] >();
 
 	return (

package/src/duotone-picker/stories/duotone-swatch.story.tsx

@@ -1,14 +1,14 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * Internal dependencies
  */
 import { DuotoneSwatch } from '..';
 
-const meta: ComponentMeta< typeof DuotoneSwatch > = {
+const meta: Meta< typeof DuotoneSwatch > = {
 	title: 'Components/DuotoneSwatch',
 	component: DuotoneSwatch,
 	parameters: {
@@ -18,7 +18,7 @@ const meta: ComponentMeta< typeof DuotoneSwatch > = {
 };
 export default meta;
 
-const Template: ComponentStory< typeof DuotoneSwatch > = ( args ) => {
+const Template: StoryFn< typeof DuotoneSwatch > = ( args ) => {
 	return <DuotoneSwatch { ...args } />;
 };