@wordpress/components 28.2.0 → 28.4.0

package/src/{custom-select-control-v2/legacy-component → custom-select-control}/test/index.tsx

@@ -20,7 +20,7 @@ const customStyles = {
 	rotate: '13deg',
 };
 
-const legacyProps = {
+const props = {
 	label: 'label!',
 	options: [
 		{
@@ -87,8 +87,8 @@ it( 'Should apply external controlled updates', async () => {
 	const mockOnChange = jest.fn();
 	const { rerender } = render(
 		<UncontrolledCustomSelectControl
-			{ ...legacyProps }
-			value={ legacyProps.options[ 0 ] }
+			{ ...props }
+			value={ props.options[ 0 ] }
 			onChange={ mockOnChange }
 		/>
 	);
@@ -97,22 +97,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(
 		<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 +124,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 } /> );
+		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();
@@ -146,9 +142,9 @@ describe.each( [
 		const mockOnChange = jest.fn();
 		render(
 			<Component
-				{ ...legacyProps }
+				{ ...props }
 				onChange={ mockOnChange }
-				value={ legacyProps.options[ 3 ] }
+				value={ props.options[ 3 ] }
 			/>
 		);
 
@@ -156,7 +152,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 +161,7 @@ describe.each( [
 	} );
 
 	it( 'Should replace the initial selection when a new item is selected', async () => {
-		render( <Component { ...legacyProps } /> );
+		render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -193,7 +189,7 @@ describe.each( [
 	} );
 
 	it( 'Should keep current selection if dropdown is closed without changing selection', async () => {
-		render( <Component { ...legacyProps } /> );
+		render( <Component { ...props } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -204,24 +200,24 @@ describe.each( [
 		await press.Enter();
 		expect(
 			screen.getByRole( 'listbox', {
-				name: 'label!',
+				name: props.label,
 			} )
 		).toBeVisible();
 
 		await press.Escape();
 		expect(
 			screen.queryByRole( 'listbox', {
-				name: '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 } /> );
+		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 } /> );
+		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
 		);
 
@@ -291,13 +287,13 @@ describe.each( [
 	it( 'does not show selected hint by default', async () => {
 		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 () => {
+	it( 'shows selected hint when showSelectedHint is set', async () => {
 		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 () => {
+	it( 'shows selected hint in list of options when added, regardless of showSelectedHint prop', async () => {
 		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 } /> );
+		render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		await click(
 			screen.getByRole( 'combobox', {
@@ -389,7 +385,7 @@ describe.each( [
 	it( 'Should return selectedItem object when specified onChange', async () => {
 		const mockOnChange = jest.fn();
 
-		render( <Component { ...legacyProps } onChange={ mockOnChange } /> );
+		render( <Component { ...props } onChange={ mockOnChange } /> );
 
 		await sleep();
 		await press.Tab();
@@ -416,7 +412,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 } /> );
+		render( <Component { ...props } onChange={ onChangeMock } /> );
 
 		const currentSelectedItem = screen.getByRole( 'combobox', {
 			expanded: false,
@@ -453,9 +449,18 @@ describe.each( [
 		);
 	} );
 
+	it( 'Should label the component correctly even when the label is not visible', () => {
+		render( <Component { ...props } hideLabelFromVision /> );
+
+		expect(
+			screen.getByRole( 'combobox', {
+				name: props.label,
+			} )
+		).toBeVisible();
+	} );
+
 	describe( 'Keyboard behavior and accessibility', () => {
-		// skip reason: legacy v2 doesn't currently implement this behavior
-		it.skip( 'Captures the keypress event and does not let it propagate', async () => {
+		it( 'Captures the keypress event and does not let it propagate', async () => {
 			const onKeyDown = jest.fn();
 
 			render(
@@ -464,7 +469,7 @@ describe.each( [
 					role="none"
 					onKeyDown={ onKeyDown }
 				>
-					<Component { ...legacyProps } />
+					<Component { ...props } />
 				</div>
 			);
 			const currentSelectedItem = screen.getByRole( 'combobox', {
@@ -473,7 +478,7 @@ describe.each( [
 			await click( currentSelectedItem );
 
 			const customSelect = screen.getByRole( 'listbox', {
-				name: 'label!',
+				name: props.label,
 			} );
 			expect( customSelect ).toHaveFocus();
 			await press.Enter();
@@ -482,7 +487,7 @@ describe.each( [
 		} );
 
 		it( 'Should be able to change selection using keyboard', async () => {
-			render( <Component { ...legacyProps } /> );
+			render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -495,7 +500,7 @@ describe.each( [
 			await press.Enter();
 			expect(
 				screen.getByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -503,12 +508,12 @@ 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 } /> );
+			render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -519,7 +524,7 @@ describe.each( [
 			await press.Enter();
 			expect(
 				screen.getByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 				} )
 			).toHaveFocus();
 
@@ -529,7 +534,7 @@ describe.each( [
 		} );
 
 		it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {
-			render( <Component { ...legacyProps } /> );
+			render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -539,7 +544,7 @@ describe.each( [
 			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
@@ -547,7 +552,7 @@ describe.each( [
 
 			expect(
 				screen.queryByRole( 'listbox', {
-					name: 'label!',
+					name: props.label,
 					hidden: true,
 				} )
 			).not.toBeInTheDocument();
@@ -558,8 +563,35 @@ describe.each( [
 			expect( currentSelectedItem ).toHaveTextContent( 'amber' );
 		} );
 
+		it( 'Can change selection with a focused input and closed dropdown while pressing arrow keys', async () => {
+			render( <Component { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'combobox', {
+				expanded: false,
+			} );
+
+			await sleep();
+			await press.Tab();
+			expect( currentSelectedItem ).toHaveFocus();
+			expect( currentSelectedItem ).toHaveTextContent(
+				props.options[ 0 ].name
+			);
+
+			await press.ArrowDown();
+			await press.ArrowDown();
+			expect(
+				screen.queryByRole( 'listbox', {
+					name: props.label,
+				} )
+			).not.toBeInTheDocument();
+
+			expect( currentSelectedItem ).toHaveTextContent(
+				props.options[ 2 ].name
+			);
+		} );
+
 		it( 'Should have correct aria-selected value for selections', async () => {
-			render( <Component { ...legacyProps } /> );
+			render( <Component { ...props } /> );
 
 			const currentSelectedItem = screen.getByRole( 'combobox', {
 				expanded: false,
@@ -568,8 +600,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"
@@ -582,7 +614,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();
@@ -596,7 +628,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();
@@ -617,7 +649,7 @@ describe.each( [
 			render(
 				<>
 					<Component
-						{ ...legacyProps }
+						{ ...props }
 						onFocus={ onFocusMock }
 						onBlur={ onBlurMock }
 					/>

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.
+ */
+type Option = {
+	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 ChangeObject = {
+	highlightedIndex?: number;
+	inputValue?: string;
+	isOpen?: boolean;
+	type?: string;
+	selectedItem: Option;
+};
+
+export type CustomSelectProps = {
+	/**
+	 * 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: ChangeObject ) => 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< Option >;
+	/**
+	 * The size of the control.
+	 *
+	 * @default 'default'
+	 */
+	size?: 'default' | 'small' | '__unstable-large';
+	/**
+	 * Can be used to externally control the value of the control.
+	 */
+	value?: Option;
+	/**
+	 * 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

@@ -1,7 +1,12 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
 /**
  * WordPress dependencies
  */
-import { createContext, useMemo } from '@wordpress/element';
+import { createContext, useCallback, useMemo } from '@wordpress/element';
 import { __, sprintf } from '@wordpress/i18n';
 
 /**
@@ -14,11 +19,12 @@ import type {
 	CustomSelectStore,
 	CustomSelectButtonProps,
 	CustomSelectButtonSize,
+	_CustomSelectInternalProps,
 	_CustomSelectProps,
 } from './types';
-import type { WordPressComponentProps } from '../context';
 import InputBase from '../input-control/input-base';
 import SelectControlChevronDown from '../select-control/chevron-down';
+import BaseControl from '../base-control';
 
 export const CustomSelectContext =
 	createContext< CustomSelectContextType >( undefined );
@@ -50,11 +56,10 @@ const CustomSelectButton = ( {
 	store,
 	...restProps
 }: Omit<
-	WordPressComponentProps<
-		CustomSelectButtonProps & CustomSelectButtonSize & CustomSelectStore,
-		'button',
-		false
-	>,
+	React.ComponentProps< typeof Ariakit.Select > &
+		CustomSelectButtonProps &
+		CustomSelectButtonSize &
+		CustomSelectStore,
 	'onChange'
 > ) => {
 	const { value: currentValue } = store.useState();
@@ -70,9 +75,6 @@ const CustomSelectButton = ( {
 			size={ size }
 			hasCustomRenderProp={ !! renderSelectedValue }
 			store={ store }
-			// to match legacy behavior where using arrow keys
-			// move selection rather than open the popover
-			showOnKeyDown={ false }
 		>
 			{ computedRenderSelectedValue( currentValue ) }
 		</Styled.Select>
@@ -80,7 +82,10 @@ const CustomSelectButton = ( {
 };
 
 function _CustomSelect(
-	props: _CustomSelectProps & CustomSelectStore & CustomSelectButtonSize
+	props: _CustomSelectInternalProps &
+		_CustomSelectProps &
+		CustomSelectStore &
+		CustomSelectButtonSize
 ) {
 	const {
 		children,
@@ -88,18 +93,40 @@ function _CustomSelect(
 		label,
 		size,
 		store,
+		className,
+		isLegacy = false,
 		...restProps
 	} = props;
 
+	const onSelectPopoverKeyDown: React.KeyboardEventHandler< HTMLDivElement > =
+		useCallback(
+			( e ) => {
+				if ( isLegacy ) {
+					e.stopPropagation();
+				}
+			},
+			[ isLegacy ]
+		);
+
+	const contextValue = useMemo( () => ( { store, size } ), [ store, size ] );
+
 	return (
-		<>
-			{ hideLabelFromVision ? ( // TODO: Replace with BaseControl
-				<VisuallyHidden as="label">{ label }</VisuallyHidden>
-			) : (
-				<Styled.SelectLabel store={ store }>
-					{ label }
-				</Styled.SelectLabel>
-			) }
+		// Where should `restProps` be forwarded to?
+		<div className={ className }>
+			<Ariakit.SelectLabel
+				store={ store }
+				render={
+					hideLabelFromVision ? (
+						// @ts-expect-error `children` are passed via the render prop
+						<VisuallyHidden />
+					) : (
+						// @ts-expect-error `children` are passed via the render prop
+						<BaseControl.VisualLabel as="div" />
+					)
+				}
+			>
+				{ label }
+			</Ariakit.SelectLabel>
 			<InputBase
 				__next40pxDefaultSize
 				size={ size }
@@ -109,14 +136,24 @@ function _CustomSelect(
 					{ ...restProps }
 					size={ size }
 					store={ store }
+					// Match legacy behavior (move selection rather than open the popover)
+					showOnKeyDown={ ! isLegacy }
 				/>
-				<Styled.SelectPopover gutter={ 12 } store={ store } sameWidth>
-					<CustomSelectContext.Provider value={ { store } }>
+				<Styled.SelectPopover
+					gutter={ 12 }
+					store={ store }
+					sameWidth
+					slide={ false }
+					onKeyDown={ onSelectPopoverKeyDown }
+					// Match legacy behavior
+					flip={ ! isLegacy }
+				>
+					<CustomSelectContext.Provider value={ contextValue }>
 						{ children }
 					</CustomSelectContext.Provider>
 				</Styled.SelectPopover>
 			</InputBase>
-		</>
+		</div>
 	);
 }