@wordpress/components 28.4.0 → 28.6.0

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,152 @@ 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 }`
+			);
+		} );
+	} );
+} );
+
+describe( 'Type checking', () => {
+	// eslint-disable-next-line jest/expect-expect
+	it( 'should infer the value type from available `options`, but not the `value` or `onChange` prop', () => {
+		const options = [
+			{
+				key: 'narrow',
+				name: 'Narrow',
+			},
+			{
+				key: 'value',
+				name: 'Value',
+			},
+		];
+		const optionsReadOnly = [
+			{
+				key: 'narrow',
+				name: 'Narrow',
+			},
+			{
+				key: 'value',
+				name: 'Value',
+			},
+		] as const;
+
+		const onChange = (): void => {};
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'random string is also accepted for non-readonly options',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+				// @ts-expect-error: the option type should not be inferred from `value`
+				foo: 'foo',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ options }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			// To ensure the type inferring is working correctly, but this is not a common use case.
+			// @ts-expect-error: the option type should not be inferred from `onChange`
+			onChange={
+				onChange as ( obj: {
+					selectedItem: { key: string; name: string; foo: string };
+				} ) => void
+			}
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				// @ts-expect-error: random string is not accepted for immutable options
+				key: 'random string is not accepted for readonly options',
+				name: 'Narrow',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+				// @ts-expect-error: the option type should not be inferred from `value`
+				foo: 'foo',
+			} }
+			onChange={ onChange }
+		/>;
+
+		<UncontrolledCustomSelectControl
+			label="Label"
+			options={ optionsReadOnly }
+			value={ {
+				key: 'narrow',
+				name: 'Narrow',
+			} }
+			// To ensure the type inferring is working correctly, but this is not a common use case.
+			// @ts-expect-error: the option type should not be inferred from `onChange`
+			onChange={
+				onChange as ( obj: {
+					selectedItem: { key: string; name: string; foo: string };
+				} ) => void
+			}
+		/>;
 	} );
 } );

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< NoInfer< 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: ReadonlyArray< 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?: NoInfer< T >;
 	/**
 	 * Use the `showSelectedHint` property instead.
 	 * @deprecated

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
+import { useStoreState } from '@ariakit/react';
 
 /**
  * WordPress dependencies
@@ -62,7 +63,7 @@ const CustomSelectButton = ( {
 		CustomSelectStore,
 	'onChange'
 > ) => {
-	const { value: currentValue } = store.useState();
+	const { value: currentValue } = useStoreState( store );
 
 	const computedRenderSelectedValue = useMemo(
 		() => renderSelectedValue ?? defaultRenderSelectedValue,

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: [] } };