@wordpress/components 28.3.0 → 28.5.0

package/src/{custom-select-control-v2/legacy-component → 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
@@ -20,7 +21,7 @@ const customStyles = {
 	rotate: '13deg',
 };
 
-const legacyProps = {
+const props = {
 	label: 'label!',
 	options: [
 		{
@@ -85,10 +86,10 @@ const ControlledCustomSelectControl = ( {
 
 it( 'Should apply external controlled updates', async () => {
 	const mockOnChange = jest.fn();
-	const { rerender } = render(
+	const { rerender } = await render(
 		<UncontrolledCustomSelectControl
-			{ ...legacyProps }
-			value={ legacyProps.options[ 0 ] }
+			{ ...props }
+			value={ props.options[ 0 ] }
 			onChange={ mockOnChange }
 		/>
 	);
@@ -97,22 +98,18 @@ it( 'Should apply external controlled updates', async () => {
 		expanded: false,
 	} );
 
-	expect( currentSelectedItem ).toHaveTextContent(
-		legacyProps.options[ 0 ].name
-	);
+	expect( currentSelectedItem ).toHaveTextContent( props.options[ 0 ].name );
 
 	expect( mockOnChange ).not.toHaveBeenCalled();
 
-	rerender(
+	await rerender(
 		<UncontrolledCustomSelectControl
-			{ ...legacyProps }
-			value={ legacyProps.options[ 1 ] }
+			{ ...props }
+			value={ props.options[ 1 ] }
 		/>
 	);
 
-	expect( currentSelectedItem ).toHaveTextContent(
-		legacyProps.options[ 1 ].name
-	);
+	expect( currentSelectedItem ).toHaveTextContent( props.options[ 1 ].name );
 
 	// Necessary to wait for onChange to potentially fire
 	await sleep();
@@ -128,13 +125,13 @@ 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 { ...legacyProps } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		expect(
 			screen.getByRole( 'combobox', {
 				expanded: false,
 			} )
-		).toHaveTextContent( legacyProps.options[ 0 ].name );
+		).toHaveTextContent( props.options[ 0 ].name );
 
 		// Necessary to wait for onChange to potentially fire
 		await sleep();
@@ -144,11 +141,11 @@ 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
-				{ ...legacyProps }
+				{ ...props }
 				onChange={ mockOnChange }
-				value={ legacyProps.options[ 3 ] }
+				value={ props.options[ 3 ] }
 			/>
 		);
 
@@ -156,7 +153,7 @@ describe.each( [
 			screen.getByRole( 'combobox', {
 				expanded: false,
 			} )
-		).toHaveTextContent( legacyProps.options[ 3 ].name );
+		).toHaveTextContent( props.options[ 3 ].name );
 
 		// Necessary to wait for onChange to potentially fire
 		await sleep();
@@ -165,7 +162,7 @@ describe.each( [
 	} );
 
 	it( 'Should replace the initial selection when a new item is selected', async () => {
-		render( <Component { ...legacyProps } /> );
+		await render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -193,35 +190,34 @@ describe.each( [
 	} );
 
 	it( 'Should keep current selection if dropdown is closed without changing selection', async () => {
-		render( <Component { ...legacyProps } /> );
+		await render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
 		} );
 
-		await sleep();
 		await press.Tab();
 		await press.Enter();
 		expect(
 			screen.getByRole( 'listbox', {
-				name: legacyProps.label,
+				name: props.label,
 			} )
 		).toBeVisible();
 
 		await press.Escape();
 		expect(
 			screen.queryByRole( 'listbox', {
-				name: legacyProps.label,
+				name: props.label,
 			} )
 		).not.toBeInTheDocument();
 
 		expect( currentSelectedItem ).toHaveTextContent(
-			legacyProps.options[ 0 ].name
+			props.options[ 0 ].name
 		);
 	} );
 
 	it( 'Should apply class only to options that have a className defined', async () => {
-		render( <Component { ...legacyProps } /> );
+		await render( <Component { ...props } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -230,7 +226,7 @@ describe.each( [
 		);
 
 		// return an array of items _with_ a className added
-		const itemsWithClass = legacyProps.options.filter(
+		const itemsWithClass = props.options.filter(
 			( option ) => option.className !== undefined
 		);
 
@@ -242,7 +238,7 @@ describe.each( [
 		);
 
 		// return an array of items _without_ a className added
-		const itemsWithoutClass = legacyProps.options.filter(
+		const itemsWithoutClass = props.options.filter(
 			( option ) => option.className === undefined
 		);
 
@@ -255,7 +251,7 @@ describe.each( [
 	} );
 
 	it( 'Should apply styles only to options that have styles defined', async () => {
-		render( <Component { ...legacyProps } /> );
+		await render( <Component { ...props } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -264,7 +260,7 @@ describe.each( [
 		);
 
 		// return an array of items _with_ styles added
-		const styledItems = legacyProps.options.filter(
+		const styledItems = props.options.filter(
 			( option ) => option.style !== undefined
 		);
 
@@ -276,7 +272,7 @@ describe.each( [
 		);
 
 		// return an array of items _without_ styles added
-		const unstyledItems = legacyProps.options.filter(
+		const unstyledItems = props.options.filter(
 			( option ) => option.style === undefined
 		);
 
@@ -289,15 +285,15 @@ describe.each( [
 	} );
 
 	it( 'does not show selected hint by default', async () => {
-		render(
+		await render(
 			<Component
-				{ ...legacyProps }
+				{ ...props }
 				label="Custom select"
 				options={ [
 					{
 						key: 'one',
 						name: 'One',
-						__experimentalHint: 'Hint',
+						hint: 'Hint',
 					},
 				] }
 			/>
@@ -309,19 +305,19 @@ describe.each( [
 		);
 	} );
 
-	it( 'shows selected hint when __experimentalShowSelectedHint is set', async () => {
-		render(
+	it( 'shows selected hint when showSelectedHint is set', async () => {
+		await render(
 			<Component
-				{ ...legacyProps }
+				{ ...props }
 				label="Custom select"
 				options={ [
 					{
 						key: 'one',
 						name: 'One',
-						__experimentalHint: 'Hint',
+						hint: 'Hint',
 					},
 				] }
-				__experimentalShowSelectedHint
+				showSelectedHint
 			/>
 		);
 
@@ -334,16 +330,16 @@ describe.each( [
 		);
 	} );
 
-	it( 'shows selected hint in list of options when added, regardless of __experimentalShowSelectedHint prop', async () => {
-		render(
+	it( 'shows selected hint in list of options when added, regardless of showSelectedHint prop', async () => {
+		await render(
 			<Component
-				{ ...legacyProps }
+				{ ...props }
 				label="Custom select"
 				options={ [
 					{
 						key: 'one',
 						name: 'One',
-						__experimentalHint: 'Hint',
+						hint: 'Hint',
 					},
 				] }
 			/>
@@ -359,7 +355,7 @@ describe.each( [
 	it( 'Should return object onChange', async () => {
 		const mockOnChange = jest.fn();
 
-		render( <Component { ...legacyProps } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -389,9 +385,8 @@ describe.each( [
 	it( 'Should return selectedItem object when specified onChange', async () => {
 		const mockOnChange = jest.fn();
 
-		render( <Component { ...legacyProps } onChange={ mockOnChange } /> );
+		await render( <Component { ...props } onChange={ mockOnChange } /> );
 
-		await sleep();
 		await press.Tab();
 		expect(
 			screen.getByRole( 'combobox', {
@@ -416,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 { ...legacyProps } onChange={ onChangeMock } /> );
+		await render( <Component { ...props } onChange={ onChangeMock } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -453,12 +448,12 @@ describe.each( [
 		);
 	} );
 
-	it( 'Should label the component correctly even when the label is not visible', () => {
-		render( <Component { ...legacyProps } hideLabelFromVision /> );
+	it( 'Should label the component correctly even when the label is not visible', async () => {
+		await render( <Component { ...props } hideLabelFromVision /> );
 
 		expect(
 			screen.getByRole( 'combobox', {
-				name: legacyProps.label,
+				name: props.label,
 			} )
 		).toBeVisible();
 	} );
@@ -467,13 +462,13 @@ 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"
 					onKeyDown={ onKeyDown }
 				>
-					<Component { ...legacyProps } />
+					<Component { ...props } />
 				</div>
 			);
 			const currentSelectedItem = screen.getByRole( 'combobox', {
@@ -482,7 +477,7 @@ describe.each( [
 			await click( currentSelectedItem );
 
 			const customSelect = screen.getByRole( 'listbox', {
-				name: legacyProps.label,
+				name: props.label,
 			} );
 			expect( customSelect ).toHaveFocus();
 			await press.Enter();
@@ -491,20 +486,19 @@ describe.each( [
 		} );
 
 		it( 'Should be able to change selection using keyboard', async () => {
-			render( <Component { ...legacyProps } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 
 			await press.Enter();
 			expect(
 				screen.getByRole( 'listbox', {
-					name: legacyProps.label,
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -512,23 +506,22 @@ describe.each( [
 			await press.Enter();
 
 			expect( currentSelectedItem ).toHaveTextContent(
-				legacyProps.options[ 1 ].name
+				props.options[ 1 ].name
 			);
 		} );
 
 		it( 'Should be able to type characters to select matching options', async () => {
-			render( <Component { ...legacyProps } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			await press.Enter();
 			expect(
 				screen.getByRole( 'listbox', {
-					name: legacyProps.label,
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -538,17 +531,16 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {
-			render( <Component { ...legacyProps } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 			expect( currentSelectedItem ).toHaveTextContent(
-				legacyProps.options[ 0 ].name
+				props.options[ 0 ].name
 			);
 
 			// Ideally we would test a multi-character typeahead, but anything more than a single character is flaky
@@ -556,7 +548,7 @@ describe.each( [
 
 			expect(
 				screen.queryByRole( 'listbox', {
-					name: legacyProps.label,
+					name: props.label,
 					hidden: true,
 				} )
 			).not.toBeInTheDocument();
@@ -568,34 +560,33 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown while pressing arrow keys', async () => {
-			render( <Component { ...legacyProps } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( currentSelectedItem ).toHaveFocus();
 			expect( currentSelectedItem ).toHaveTextContent(
-				legacyProps.options[ 0 ].name
+				props.options[ 0 ].name
 			);
 
 			await press.ArrowDown();
 			await press.ArrowDown();
 			expect(
 				screen.queryByRole( 'listbox', {
-					name: legacyProps.label,
+					name: props.label,
 				} )
 			).not.toBeInTheDocument();
 
 			expect( currentSelectedItem ).toHaveTextContent(
-				legacyProps.options[ 2 ].name
+				props.options[ 2 ].name
 			);
 		} );
 
 		it( 'Should have correct aria-selected value for selections', async () => {
-			render( <Component { ...legacyProps } /> );
+			await render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -604,8 +595,8 @@ describe.each( [
 			await click( currentSelectedItem );
 
 			// get all items except for first option
-			const unselectedItems = legacyProps.options.filter(
-				( { name } ) => name !== legacyProps.options[ 0 ].name
+			const unselectedItems = props.options.filter(
+				( { name } ) => name !== props.options[ 0 ].name
 			);
 
 			// assert that all other items have aria-selected="false"
@@ -618,7 +609,7 @@ describe.each( [
 			// assert that first item has aria-selected="true"
 			expect(
 				screen.getByRole( 'option', {
-					name: legacyProps.options[ 0 ].name,
+					name: props.options[ 0 ].name,
 					selected: true,
 				} )
 			).toBeVisible();
@@ -632,7 +623,7 @@ describe.each( [
 			// check that first item is has aria-selected="false" after new selection
 			expect(
 				screen.getByRole( 'option', {
-					name: legacyProps.options[ 0 ].name,
+					name: props.options[ 0 ].name,
 					selected: false,
 				} )
 			).toBeVisible();
@@ -650,10 +641,10 @@ describe.each( [
 			const onFocusMock = jest.fn();
 			const onBlurMock = jest.fn();
 
-			render(
+			await render(
 				<>
 					<Component
-						{ ...legacyProps }
+						{ ...props }
 						onFocus={ onFocusMock }
 						onBlur={ onBlurMock }
 					/>
@@ -674,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

@@ -0,0 +1,123 @@
+/**
+ * External dependencies
+ */
+import type { FocusEventHandler, MouseEventHandler } from 'react';
+
+/**
+ * The object structure for the options array.
+ */
+export type CustomSelectOption = {
+	key: string;
+	name: string;
+	style?: React.CSSProperties;
+	className?: string;
+	hint?: string;
+	/**
+	 * Use the `hint` property instead
+	 * @deprecated
+	 * @ignore
+	 */
+	__experimentalHint?: string;
+	[ key: string ]: any;
+};
+
+/**
+ * The object returned from the onChange event.
+ */
+type CustomSelectChangeObject< T extends CustomSelectOption > = {
+	highlightedIndex?: number;
+	inputValue?: string;
+	isOpen?: boolean;
+	type?: string;
+	selectedItem: T;
+};
+
+export type CustomSelectProps< T extends CustomSelectOption > = {
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * Hide the label visually, while keeping available to assistive technology.
+	 */
+	hideLabelFromVision?: boolean;
+	/**
+	 * Description for the select trigger button used by assistive technology.
+	 * If no value is passed, the text "Currently selected: selectedItem.name"
+	 * will be used fully translated.
+	 */
+	describedBy?: string;
+	/**
+	 * Label for the control.
+	 */
+	label: string;
+	/**
+	 * Function called with the control's internal state changes. The `selectedItem`
+	 * property contains the next selected item.
+	 */
+	onChange?: ( newValue: CustomSelectChangeObject< T > ) => void;
+	/**
+	 * A handler for `blur` events on the trigger button.
+	 *
+	 * @ignore
+	 */
+	onBlur?: FocusEventHandler< HTMLButtonElement >;
+	/**
+	 * A handler for `focus` events on the trigger button.
+	 *
+	 * @ignore
+	 */
+	onFocus?: FocusEventHandler< HTMLButtonElement >;
+	/**
+	 * A handler for `mouseout` events on the trigger button.
+	 *
+	 * @ignore
+	 */
+	onMouseOut?: MouseEventHandler< HTMLButtonElement >;
+	/**
+	 * A handler for `mouseover` events on the trigger button.
+	 *
+	 * @ignore
+	 */
+	onMouseOver?: MouseEventHandler< HTMLButtonElement >;
+	/**
+	 * The list of options that can be chosen from.
+	 */
+	options: Array< T >;
+	/**
+	 * The size of the control.
+	 *
+	 * @default 'default'
+	 */
+	size?: 'default' | 'small' | '__unstable-large';
+	/**
+	 * Can be used to externally control the value of the control.
+	 */
+	value?: T;
+	/**
+	 * Use the `showSelectedHint` property instead.
+	 * @deprecated
+	 * @ignore
+	 */
+	__experimentalShowSelectedHint?: boolean;
+	/**
+	 * Show the hint of the selected item in the trigger button.
+	 *
+	 * @default false
+	 */
+	showSelectedHint?: boolean;
+	/**
+	 * Opt-in prop for an unconstrained width style which became the default in
+	 * WordPress 6.5. The prop is no longer needed and can be safely removed.
+	 *
+	 * @deprecated
+	 * @ignore
+	 */
+	__nextUnconstrainedWidth?: boolean;
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next40pxDefaultSize?: boolean;
+};

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

@@ -145,6 +145,8 @@ function _CustomSelect(
 					sameWidth
 					slide={ false }
 					onKeyDown={ onSelectPopoverKeyDown }
+					// Match legacy behavior
+					flip={ ! isLegacy }
 				>
 					<CustomSelectContext.Provider value={ contextValue }>
 						{ children }

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

@@ -1,4 +1,29 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
 /**
  * Internal dependencies
  */
-export { default } from './default-component';
+import _CustomSelect from './custom-select';
+import type { CustomSelectProps } from './types';
+import type { WordPressComponentProps } from '../context';
+import Item from './item';
+
+function CustomSelectControlV2(
+	props: WordPressComponentProps< CustomSelectProps, 'button', false >
+) {
+	const { defaultValue, onChange, value, ...restProps } = props;
+	// Forward props + store from v2 implementation
+	const store = Ariakit.useSelectStore( {
+		setValue: ( nextValue ) => onChange?.( nextValue ),
+		defaultValue,
+		value,
+	} );
+
+	return <_CustomSelect { ...restProps } store={ store } />;
+}
+
+CustomSelectControlV2.Item = Item;
+
+export default CustomSelectControlV2;

package/src/custom-select-control-v2/stories/{default.story.tsx → index.story.tsx}

@@ -14,7 +14,7 @@ import { useState } from '@wordpress/element';
 import CustomSelectControlV2 from '..';
 
 const meta: Meta< typeof CustomSelectControlV2 > = {
-	title: 'Components/CustomSelectControl v2/Default',
+	title: 'Components/CustomSelectControl v2',
 	component: CustomSelectControlV2,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170