@wordpress/components 25.7.0 → 25.8.1

package/src/confirm-dialog/stories/index.story.js

@@ -87,22 +87,22 @@ const _defaultSnippet = `() => {
 
   return (
     <>
-    <ConfirmDialog
-      isOpen={ isOpen }
-      onConfirm={ handleConfirm }
-      onCancel={ handleCancel }
-    >
-      Would you like to privately publish the post now?
-    </ConfirmDialog>
+      <ConfirmDialog
+        isOpen={ isOpen }
+        onConfirm={ handleConfirm }
+        onCancel={ handleCancel }
+      >
+        Would you like to privately publish the post now?
+      </ConfirmDialog>
 
-    <Heading level={ 1 }>{ confirmVal }</Heading>
+      <Heading level={ 1 }>{ confirmVal }</Heading>
 
-    <Button variant="primary" onClick={ () => setIsOpen( true ) }>
-      Open ConfirmDialog
-    </Button>
+      <Button variant="primary" onClick={ () => setIsOpen( true ) }>
+        Open ConfirmDialog
+      </Button>
     </>
-    );
-  };`;
+  );
+};`;
 _default.args = {};
 _default.parameters = {
 	docs: {
@@ -110,7 +110,6 @@ _default.parameters = {
 			code: _defaultSnippet,
 			language: 'jsx',
 			type: 'auto',
-			format: 'true',
 		},
 	},
 };

package/src/confirm-dialog/test/index.js

@@ -1,13 +1,7 @@
 /**
  * External dependencies
  */
-import {
-	render,
-	screen,
-	fireEvent,
-	waitForElementToBeRemoved,
-	waitFor,
-} from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 /**
@@ -137,6 +131,7 @@ describe( 'Confirm', () => {
 			} );
 
 			it( 'should not render if dialog is closed by clicking the overlay, and the `onCancel` callback should be called', async () => {
+				const user = userEvent.setup();
 				const onCancel = jest.fn().mockName( 'onCancel()' );
 
 				render(
@@ -147,11 +142,9 @@ describe( 'Confirm', () => {
 
 				const confirmDialog = screen.getByRole( 'dialog' );
 
-				//The overlay click is handled by detecting an onBlur from the modal frame.
-				// TODO: replace with `@testing-library/user-event`
-				fireEvent.blur( confirmDialog );
-
-				await waitForElementToBeRemoved( confirmDialog );
+				// Disable reason: Semantic queries can’t reach the overlay.
+				// eslint-disable-next-line testing-library/no-node-access
+				await user.click( confirmDialog.parentElement );
 
 				expect( confirmDialog ).not.toBeInTheDocument();
 				expect( onCancel ).toHaveBeenCalled();
@@ -315,6 +308,7 @@ describe( 'Confirm', () => {
 		} );
 
 		it( 'should call the `onCancel` callback if the overlay is clicked', async () => {
+			const user = userEvent.setup();
 			const onCancel = jest.fn().mockName( 'onCancel()' );
 
 			render(
@@ -329,13 +323,11 @@ describe( 'Confirm', () => {
 
 			const confirmDialog = screen.getByRole( 'dialog' );
 
-			//The overlay click is handled by detecting an onBlur from the modal frame.
-			// TODO: replace with `@testing-library/user-event`
-			fireEvent.blur( confirmDialog );
+			// Disable reason: Semantic queries can’t reach the overlay.
+			// eslint-disable-next-line testing-library/no-node-access
+			await user.click( confirmDialog.parentElement );
 
-			// Wait for a DOM side effect here, so that the `queueBlurCheck` in the
-			// `useFocusOutside` hook properly executes its timeout task.
-			await waitFor( () => expect( onCancel ).toHaveBeenCalled() );
+			expect( onCancel ).toHaveBeenCalled();
 		} );
 
 		it( 'should call the `onCancel` callback if the `Escape` key is pressed', async () => {

package/src/custom-gradient-picker/gradient-bar/control-points.tsx

@@ -93,7 +93,7 @@ function GradientColorPickerDropdown( {
 			( {
 				placement: 'bottom',
 				offset: 8,
-			} as const ),
+			} ) as const,
 		[]
 	);
 

package/src/custom-gradient-picker/gradient-bar/test/utils.ts

@@ -13,7 +13,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 0,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -31,7 +31,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -49,7 +49,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 0,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );
@@ -68,7 +68,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 		const containerElement = document.createElement( 'div' );
 
@@ -86,7 +86,7 @@ describe( 'getHorizontalRelativeGradientPosition', () => {
 				( {
 					x: 50,
 					width: 1000,
-				} as DOMRect )
+				} ) as DOMRect
 		);
 
 		const containerElement = document.createElement( 'div' );

package/src/date-time/time/index.tsx

@@ -127,7 +127,14 @@ export function TimePicker( {
 		method: 'hours' | 'minutes' | 'date' | 'year'
 	) => {
 		const callback: InputChangeCallback = ( value, { event } ) => {
-			if ( ! ( event.target instanceof HTMLInputElement ) ) {
+			// `instanceof` checks need to get the instance definition from the
+			// corresponding window object — therefore, the following logic makes
+			// the component work correctly even when rendered inside an iframe.
+			const HTMLInputElementInstance =
+				( event.target as HTMLInputElement )?.ownerDocument.defaultView
+					?.HTMLInputElement ?? HTMLInputElement;
+
+			if ( ! ( event.target instanceof HTMLInputElementInstance ) ) {
 				return;
 			}
 

package/src/date-time/time/timezone.tsx

@@ -38,7 +38,7 @@ const TimeZone = () => {
 			: `(${ zoneAbbr }) ${ timezone.string.replace( '_', ' ' ) }`;
 
 	return (
-		<Tooltip position="top center" text={ timezoneDetail }>
+		<Tooltip placement="top" text={ timezoneDetail }>
 			<StyledComponent className="components-datetime__timezone">
 				{ zoneAbbr }
 			</StyledComponent>

package/src/dropdown/README.md

@@ -44,6 +44,12 @@ If you want to target the dropdown menu for styling purposes, you need to provid
 
 -   Required: No
 
+### `defaultOpen`: `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.
+
+-   Required: No
+
 ### `expandOnMobile`: `boolean`
 
 Opt-in prop to show popovers fullscreen on mobile.
@@ -74,11 +80,15 @@ A callback invoked when the popover should be closed.
 
 -   Required: No
 
-### `onToggle`: `( willOpen: boolean ) => void`
+### `open`: `boolean`
 
-A callback invoked when the state of the popover changes from open to closed and vice versa.
+The controlled open state of the dropdown. Must be used in conjunction with `onToggle`.
+
+-   Required: No
+
+### `onToggle`: `( willOpen: boolean ) => void`
 
-The callback receives a boolean as a parameter. If `true`, the popover will open. If `false`, the popover will close.
+A callback invoked when the state of the dropdown changes from open to closed and vice versa.
 
 -   Required: No
 

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

@@ -25,8 +25,13 @@ const meta: Meta< 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,
 		},
@@ -34,13 +39,11 @@ const meta: Meta< typeof Dropdown > = {
 };
 export default meta;
 
-const Template: StoryFn< 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 = Template.bind( {} );
 Default.args = {

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import type { Meta, StoryFn } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
@@ -25,6 +26,7 @@ const meta: Meta< typeof DropdownMenu > = {
 	title: 'Components/DropdownMenu',
 	component: DropdownMenu,
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 	},
@@ -34,6 +36,9 @@ const meta: Meta< typeof DropdownMenu > = {
 			mapping: { menu, chevronDown, more },
 			control: { type: 'select' },
 		},
+		open: { control: { type: null } },
+		defaultOpen: { control: { type: null } },
+		onToggle: { control: { type: null } },
 	},
 };
 export default meta;

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