@wordpress/components 28.4.0 → 28.5.0

package/src/custom-select-control/index.tsx

@@ -4,18 +4,25 @@
 import * as Ariakit from '@ariakit/react';
 import clsx from 'clsx';
 
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { __, sprintf } from '@wordpress/i18n';
+
 /**
  * Internal dependencies
  */
 import _CustomSelect from '../custom-select-control-v2/custom-select';
 import CustomSelectItem from '../custom-select-control-v2/item';
 import * as Styled from '../custom-select-control-v2/styles';
-import type { CustomSelectProps } from './types';
+import type { CustomSelectProps, CustomSelectOption } from './types';
+import { VisuallyHidden } from '../visually-hidden';
 
-function useDeprecatedProps( {
+function useDeprecatedProps< T extends CustomSelectOption >( {
 	__experimentalShowSelectedHint,
 	...otherProps
-}: CustomSelectProps ) {
+}: CustomSelectProps< T > ) {
 	return {
 		showSelectedHint: __experimentalShowSelectedHint,
 		...otherProps,
@@ -28,14 +35,25 @@ function useDeprecatedProps( {
 function applyOptionDeprecations( {
 	__experimentalHint,
 	...rest
-}: CustomSelectProps[ 'options' ][ number ] ) {
+}: CustomSelectOption ) {
 	return {
 		hint: __experimentalHint,
 		...rest,
 	};
 }
 
-function CustomSelectControl( props: CustomSelectProps ) {
+function getDescribedBy( currentValue: string, describedBy?: string ) {
+	if ( describedBy ) {
+		return describedBy;
+	}
+
+	// translators: %s: The selected option.
+	return sprintf( __( 'Currently selected: %s' ), currentValue );
+}
+
+function CustomSelectControl< T extends CustomSelectOption >(
+	props: CustomSelectProps< T >
+) {
 	const {
 		__next40pxDefaultSize = false,
 		describedBy,
@@ -48,8 +66,13 @@ function CustomSelectControl( props: CustomSelectProps ) {
 		...restProps
 	} = useDeprecatedProps( props );
 
+	const descriptionId = useInstanceId(
+		CustomSelectControl,
+		'custom-select-control__description'
+	);
+
 	// Forward props + store from v2 implementation
-	const store = Ariakit.useSelectStore( {
+	const store = Ariakit.useSelectStore< string >( {
 		async setValue( nextValue ) {
 			const nextOption = options.find(
 				( item ) => item.name === nextValue
@@ -117,9 +140,9 @@ function CustomSelectControl( props: CustomSelectProps ) {
 			);
 		} );
 
-	const renderSelectedValueHint = () => {
-		const { value: currentValue } = store.getState();
+	const { value: currentValue } = store.getState();
 
+	const renderSelectedValueHint = () => {
 		const selectedOptionHint = options
 			?.map( applyOptionDeprecations )
 			?.find( ( { name } ) => currentValue === name )?.hint;
@@ -153,23 +176,30 @@ function CustomSelectControl( props: CustomSelectProps ) {
 	} )();
 
 	return (
-		<_CustomSelect
-			aria-describedby={ describedBy }
-			renderSelectedValue={
-				showSelectedHint ? renderSelectedValueHint : undefined
-			}
-			size={ translatedSize }
-			store={ store }
-			className={ clsx(
-				// Keeping the classname for legacy reasons
-				'components-custom-select-control',
-				classNameProp
-			) }
-			isLegacy
-			{ ...restProps }
-		>
-			{ children }
-		</_CustomSelect>
+		<>
+			<_CustomSelect
+				aria-describedby={ descriptionId }
+				renderSelectedValue={
+					showSelectedHint ? renderSelectedValueHint : undefined
+				}
+				size={ translatedSize }
+				store={ store }
+				className={ clsx(
+					// Keeping the classname for legacy reasons
+					'components-custom-select-control',
+					classNameProp
+				) }
+				isLegacy
+				{ ...restProps }
+			>
+				{ children }
+			</_CustomSelect>
+			<VisuallyHidden>
+				<span id={ descriptionId }>
+					{ getDescribedBy( currentValue, describedBy ) }
+				</span>
+			</VisuallyHidden>
+		</>
 	);
 }
 

package/src/custom-select-control/test/index.tsx

@@ -1,8 +1,9 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { click, press, sleep, type, waitFor } from '@ariakit/test';
+import { render } from '@ariakit/test/react';
 
 /**
  * WordPress dependencies
@@ -85,7 +86,7 @@ const ControlledCustomSelectControl = ( {
 
 it( 'Should apply external controlled updates', async () => {
 	const mockOnChange = jest.fn();
-	const { rerender } = render(
+	const { rerender } = await render(
 		<UncontrolledCustomSelectControl
 			{ ...props }
 			value={ props.options[ 0 ] }
@@ -101,7 +102,7 @@ it( 'Should apply external controlled updates', async () => {
 
 	expect( mockOnChange ).not.toHaveBeenCalled();
 
-	rerender(
+	await rerender(
 		<UncontrolledCustomSelectControl
 			{ ...props }
 			value={ props.options[ 1 ] }
@@ -124,7 +125,7 @@ describe.each( [
 
 	it( 'Should select the first option when no explicit initial value is passed without firing onChange', async () => {
 		const mockOnChange = jest.fn();
-		render( <Component { ...props } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		expect(
 			screen.getByRole( 'combobox', {
@@ -140,7 +141,7 @@ describe.each( [
 
 	it( 'Should pick the initially selected option if the value prop is passed without firing onChange', async () => {
 		const mockOnChange = jest.fn();
-		render(
+		await render(
 			<Component
 				{ ...props }
 				onChange={ mockOnChange }
@@ -161,7 +162,7 @@ describe.each( [
 	} );
 
 	it( 'Should replace the initial selection when a new item is selected', async () => {
-		render( <Component { ...props } /> );
+		await render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -189,13 +190,12 @@ describe.each( [
 	} );
 
 	it( 'Should keep current selection if dropdown is closed without changing selection', async () => {
-		render( <Component { ...props } /> );
+		await render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
 		} );
 
-		await sleep();
 		await press.Tab();
 		await press.Enter();
 		expect(
@@ -217,7 +217,7 @@ describe.each( [
 	} );
 
 	it( 'Should apply class only to options that have a className defined', async () => {
-		render( <Component { ...props } /> );
+		await render( <Component { ...props } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -251,7 +251,7 @@ describe.each( [
 	} );
 
 	it( 'Should apply styles only to options that have styles defined', async () => {
-		render( <Component { ...props } /> );
+		await render( <Component { ...props } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -285,7 +285,7 @@ describe.each( [
 	} );
 
 	it( 'does not show selected hint by default', async () => {
-		render(
+		await render(
 			<Component
 				{ ...props }
 				label="Custom select"
@@ -306,7 +306,7 @@ describe.each( [
 	} );
 
 	it( 'shows selected hint when showSelectedHint is set', async () => {
-		render(
+		await render(
 			<Component
 				{ ...props }
 				label="Custom select"
@@ -331,7 +331,7 @@ describe.each( [
 	} );
 
 	it( 'shows selected hint in list of options when added, regardless of showSelectedHint prop', async () => {
-		render(
+		await render(
 			<Component
 				{ ...props }
 				label="Custom select"
@@ -355,7 +355,7 @@ describe.each( [
 	it( 'Should return object onChange', async () => {
 		const mockOnChange = jest.fn();
 
-		render( <Component { ...props } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -385,9 +385,8 @@ describe.each( [
 	it( 'Should return selectedItem object when specified onChange', async () => {
 		const mockOnChange = jest.fn();
 
-		render( <Component { ...props } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
-		await sleep();
 		await press.Tab();
 		expect(
 			screen.getByRole( 'combobox', {
@@ -412,7 +411,7 @@ describe.each( [
 	it( "Should pass arbitrary props to onChange's selectedItem, but apply only style and className to DOM elements", async () => {
 		const onChangeMock = jest.fn();
 
-		render( <Component { ...props } onChange={ onChangeMock } /> );
+		await render( <Component { ...props } onChange={ onChangeMock } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -449,8 +448,8 @@ describe.each( [
 		);
 	} );
 
-	it( 'Should label the component correctly even when the label is not visible', () => {
-		render( <Component { ...props } hideLabelFromVision /> );
+	it( 'Should label the component correctly even when the label is not visible', async () => {
+		await render( <Component { ...props } hideLabelFromVision /> );
 
 		expect(
 			screen.getByRole( 'combobox', {
@@ -463,7 +462,7 @@ describe.each( [
 		it( 'Captures the keypress event and does not let it propagate', async () => {
 			const onKeyDown = jest.fn();
 
-			render(
+			await render(
 				<div
 					// This role="none" is required to prevent an eslint warning about accessibility.
 					role="none"
@@ -487,13 +486,12 @@ describe.each( [
 		} );
 
 		it( 'Should be able to change selection using keyboard', async () => {
-			render( <Component { ...props } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 
@@ -513,13 +511,12 @@ describe.each( [
 		} );
 
 		it( 'Should be able to type characters to select matching options', async () => {
-			render( <Component { ...props } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			await press.Enter();
 			expect(
@@ -534,13 +531,12 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {
-			render( <Component { ...props } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 			expect( currentSelectedItem ).toHaveTextContent(
@@ -564,13 +560,12 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown while pressing arrow keys', async () => {
-			render( <Component { ...props } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 			expect( currentSelectedItem ).toHaveTextContent(
@@ -591,7 +586,7 @@ describe.each( [
 		} );
 
 		it( 'Should have correct aria-selected value for selections', async () => {
-			render( <Component { ...props } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -646,7 +641,7 @@ describe.each( [
 			const onFocusMock = jest.fn();
 			const onBlurMock = jest.fn();
 
-			render(
+			await render(
 				<>
 					<Component
 						{ ...props }
@@ -670,5 +665,27 @@ describe.each( [
 			expect( currentSelectedItem ).not.toHaveFocus();
 			expect( onBlurMock ).toHaveBeenCalledTimes( 1 );
 		} );
+
+		it( 'should render the describedBy text when specified', async () => {
+			const describedByText = 'My description.';
+
+			await render(
+				<Component { ...props } describedBy={ describedByText } />
+			);
+
+			expect(
+				screen.getByRole( 'combobox' )
+			).toHaveAccessibleDescription( describedByText );
+		} );
+
+		it( 'should render the default ARIA description when describedBy is not specified', async () => {
+			await render( <Component { ...props } /> );
+
+			expect(
+				screen.getByRole( 'combobox' )
+			).toHaveAccessibleDescription(
+				`Currently selected: ${ props.options[ 0 ].name }`
+			);
+		} );
 	} );
 } );

package/src/custom-select-control/types.ts

@@ -6,7 +6,7 @@ import type { FocusEventHandler, MouseEventHandler } from 'react';
 /**
  * The object structure for the options array.
  */
-type Option = {
+export type CustomSelectOption = {
 	key: string;
 	name: string;
 	style?: React.CSSProperties;
@@ -24,15 +24,15 @@ type Option = {
 /**
  * The object returned from the onChange event.
  */
-type ChangeObject = {
+type CustomSelectChangeObject< T extends CustomSelectOption > = {
 	highlightedIndex?: number;
 	inputValue?: string;
 	isOpen?: boolean;
 	type?: string;
-	selectedItem: Option;
+	selectedItem: T;
 };
 
-export type CustomSelectProps = {
+export type CustomSelectProps< T extends CustomSelectOption > = {
 	/**
 	 * Optional classname for the component.
 	 */
@@ -55,7 +55,7 @@ export type CustomSelectProps = {
 	 * Function called with the control's internal state changes. The `selectedItem`
 	 * property contains the next selected item.
 	 */
-	onChange?: ( newValue: ChangeObject ) => void;
+	onChange?: ( newValue: CustomSelectChangeObject< T > ) => void;
 	/**
 	 * A handler for `blur` events on the trigger button.
 	 *
@@ -83,7 +83,7 @@ export type CustomSelectProps = {
 	/**
 	 * The list of options that can be chosen from.
 	 */
-	options: Array< Option >;
+	options: Array< T >;
 	/**
 	 * The size of the control.
 	 *
@@ -93,7 +93,7 @@ export type CustomSelectProps = {
 	/**
 	 * Can be used to externally control the value of the control.
 	 */
-	value?: Option;
+	value?: T;
 	/**
 	 * Use the `showSelectedHint` property instead.
 	 * @deprecated

package/src/custom-select-control-v2/styles.ts

@@ -132,12 +132,13 @@ export const SelectPopover = styled( Ariakit.SelectPopover )`
 	min-width: min-content;
 
 	/* Animation */
-	animation-duration: ${ ANIMATION_PARAMS.DURATION };
-	animation-timing-function: ${ ANIMATION_PARAMS.EASING };
-	animation-name: ${ slideDownAndFade };
-	will-change: transform, opacity;
-	@media ( prefers-reduced-motion ) {
-		animation-duration: 0s;
+	&[data-open] {
+		@media not ( prefers-reduced-motion ) {
+			animation-duration: ${ ANIMATION_PARAMS.DURATION };
+			animation-timing-function: ${ ANIMATION_PARAMS.EASING };
+			animation-name: ${ slideDownAndFade };
+			will-change: transform, opacity;
+		}
 	}
 
 	&[data-focus-visible] {

package/src/custom-select-control-v2/test/index.tsx

@@ -1,8 +1,9 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
-import { click, press, sleep, type } from '@ariakit/test';
+import { screen } from '@testing-library/react';
+import { click, press, type } from '@ariakit/test';
+import { render } from '@ariakit/test/react';
 
 /**
  * WordPress dependencies
@@ -66,7 +67,7 @@ describe.each( [
 	const [ , Component ] = modeAndComponent;
 
 	it( 'Should replace the initial selection when a new item is selected', async () => {
-		render( <Component { ...defaultProps } /> );
+		await render( <Component { ...defaultProps } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -94,13 +95,12 @@ describe.each( [
 	} );
 
 	it( 'Should keep current selection if dropdown is closed without changing selection', async () => {
-		render( <Component { ...defaultProps } /> );
+		await render( <Component { ...defaultProps } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
 		} );
 
-		await sleep();
 		await press.Tab();
 		await press.Enter();
 		expect(
@@ -121,13 +121,12 @@ describe.each( [
 
 	describe( 'Keyboard behavior and accessibility', () => {
 		it( 'Should be able to change selection using keyboard', async () => {
-			render( <Component { ...defaultProps } /> );
+			await render( <Component { ...defaultProps } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 
@@ -145,13 +144,12 @@ describe.each( [
 		} );
 
 		it( 'Should be able to type characters to select matching options', async () => {
-			render( <Component { ...defaultProps } /> );
+			await render( <Component { ...defaultProps } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			await press.Enter();
 			expect(
@@ -166,13 +164,12 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {
-			render( <Component { ...defaultProps } /> );
+			await render( <Component { ...defaultProps } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 			expect( currentSelectedItem ).toHaveTextContent( 'violets' );
@@ -194,7 +191,7 @@ describe.each( [
 		} );
 
 		it( 'Should have correct aria-selected value for selections', async () => {
-			render( <Component { ...defaultProps } /> );
+			await render( <Component { ...defaultProps } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -244,7 +241,7 @@ describe.each( [
 				'ultraviolet morning light',
 			];
 
-			render(
+			await render(
 				<Component
 					defaultValue={ defaultValues }
 					onChange={ onChangeMock }
@@ -326,7 +323,7 @@ describe.each( [
 				'ultraviolet morning light',
 			];
 
-			render(
+			await render(
 				<Component defaultValue={ defaultValues } label="Multi-select">
 					{ defaultValues.map( ( item ) => (
 						<UncontrolledCustomSelectControlV2.Item
@@ -382,7 +379,7 @@ describe.each( [
 			return <img src={ `${ value }.jpg` } alt={ value as string } />;
 		};
 
-		render(
+		await render(
 			<Component label="Rendered" renderSelectedValue={ renderValue }>
 				<UncontrolledCustomSelectControlV2.Item value="april-29">
 					{ renderValue( 'april-29' ) }
@@ -418,13 +415,12 @@ describe.each( [
 	} );
 
 	it( 'Should open the select popover when focussing the trigger button and pressing arrow down', async () => {
-		render( <Component { ...defaultProps } /> );
+		await render( <Component { ...defaultProps } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
 		} );
 
-		await sleep();
 		await press.Tab();
 		expect( currentSelectedItem ).toHaveFocus();
 		expect( currentSelectedItem ).toHaveTextContent( items[ 0 ].value );
@@ -437,8 +433,8 @@ describe.each( [
 		).toBeVisible();
 	} );
 
-	it( 'Should label the component correctly even when the label is not visible', () => {
-		render( <Component { ...defaultProps } hideLabelFromVision /> );
+	it( 'Should label the component correctly even when the label is not visible', async () => {
+		await render( <Component { ...defaultProps } hideLabelFromVision /> );
 
 		expect(
 			screen.getByRole( 'combobox', {

package/src/date-time/index.ts

@@ -3,8 +3,7 @@
  */
 import { default as DatePicker } from './date';
 import { default as TimePicker } from './time';
-import { default as TimeInput } from './time-input';
 import { default as DateTimePicker } from './date-time';
 
-export { DatePicker, TimePicker, TimeInput };
+export { DatePicker, TimePicker };
 export default DateTimePicker;

package/src/date-time/stories/time.story.tsx

@@ -16,6 +16,8 @@ import TimePicker from '../time';
 const meta: Meta< typeof TimePicker > = {
 	title: 'Components/TimePicker',
 	component: TimePicker,
+	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+	subcomponents: { 'TimePicker.TimeInput': TimePicker.TimeInput },
 	argTypes: {
 		currentTime: { control: 'date' },
 		onChange: { action: 'onChange', control: { type: null } },
@@ -49,3 +51,18 @@ const Template: StoryFn< typeof TimePicker > = ( {
 };
 
 export const Default: StoryFn< typeof TimePicker > = Template.bind( {} );
+
+const TimeInputTemplate: StoryFn< typeof TimePicker.TimeInput > = ( args ) => {
+	return <TimePicker.TimeInput { ...args } />;
+};
+
+/**
+ * The time input can be used in isolation as `<TimePicker.TimeInput />`. In this case, the `value` will be passed
+ * as an object in 24-hour format (`{ hours: number, minutes: number }`).
+ */
+export const TimeInput = TimeInputTemplate.bind( {} );
+TimeInput.args = {
+	label: 'Time',
+};
+// Hide TimePicker controls because they don't apply to TimeInput
+TimeInput.parameters = { controls: { include: [] } };