@wordpress/components 25.12.0 → 25.14.0

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

@@ -4,54 +4,205 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
 /**
  * Internal dependencies
  */
 import CustomSelectControl from '..';
 
-describe( 'CustomSelectControl', () => {
-	it( 'Captures the keypress event and does not let it propagate', async () => {
-		const user = userEvent.setup();
-		const onKeyDown = jest.fn();
-		const options = [
-			{
-				key: 'one',
-				name: 'Option one',
-			},
-			{
-				key: 'two',
-				name: 'Option two',
-			},
-			{
-				key: 'three',
-				name: 'Option three',
+const customClass = 'amber-skies';
+
+const props = {
+	label: 'label!',
+	options: [
+		{
+			key: 'flower1',
+			name: 'violets',
+		},
+		{
+			key: 'flower2',
+			name: 'crimson clover',
+			className: customClass,
+		},
+		{
+			key: 'flower3',
+			name: 'poppy',
+		},
+		{
+			key: 'color1',
+			name: 'amber',
+			className: customClass,
+		},
+		{
+			key: 'color2',
+			name: 'aquamarine',
+			style: {
+				backgroundColor: 'rgb(127, 255, 212)',
+				rotate: '13deg',
 			},
-		];
+		},
+	],
+	__nextUnconstrainedWidth: true,
+};
 
-		render(
-			<div
-				// This role="none" is required to prevent an eslint warning about accessibility.
-				role="none"
-				onKeyDown={ onKeyDown }
-			>
-				<CustomSelectControl
-					options={ options }
-					__nextUnconstrainedWidth
-				/>
-			</div>
+const ControlledCustomSelectControl = ( { options } ) => {
+	const [ value, setValue ] = useState( options[ 0 ] );
+	return (
+		<CustomSelectControl
+			{ ...props }
+			onChange={ ( { selectedItem } ) => setValue( selectedItem ) }
+			value={ options.find( ( option ) => option.key === value.key ) }
+		/>
+	);
+};
+
+describe.each( [
+	[ 'uncontrolled', CustomSelectControl ],
+	[ 'controlled', ControlledCustomSelectControl ],
+] )( 'CustomSelectControl %s', ( ...modeAndComponent ) => {
+	const [ , Component ] = modeAndComponent;
+
+	it( 'Should replace the initial selection when a new item is selected', async () => {
+		const user = userEvent.setup();
+
+		render( <Component { ...props } /> );
+
+		const currentSelectedItem = screen.getByRole( 'button', {
+			expanded: false,
+		} );
+
+		await user.click( currentSelectedItem );
+
+		await user.click(
+			screen.getByRole( 'option', {
+				name: 'crimson clover',
+			} )
+		);
+
+		expect( currentSelectedItem ).toHaveTextContent( 'crimson clover' );
+
+		await user.click( currentSelectedItem );
+
+		await user.click(
+			screen.getByRole( 'option', {
+				name: 'poppy',
+			} )
+		);
+
+		expect( currentSelectedItem ).toHaveTextContent( 'poppy' );
+	} );
+
+	it( 'Should keep current selection if dropdown is closed without changing selection', async () => {
+		const user = userEvent.setup();
+
+		render( <CustomSelectControl { ...props } /> );
+
+		const currentSelectedItem = screen.getByRole( 'button', {
+			expanded: false,
+		} );
+
+		await user.tab();
+		await user.keyboard( '{enter}' );
+		expect(
+			screen.getByRole( 'listbox', {
+				name: 'label!',
+			} )
+		).toBeVisible();
+
+		await user.keyboard( '{escape}' );
+		expect(
+			screen.queryByRole( 'listbox', {
+				name: 'label!',
+			} )
+		).not.toBeInTheDocument();
+
+		expect( currentSelectedItem ).toHaveTextContent(
+			props.options[ 0 ].name
+		);
+	} );
+
+	it( 'Should apply class only to options that have a className defined', async () => {
+		const user = userEvent.setup();
+
+		render( <CustomSelectControl { ...props } /> );
+
+		await user.click(
+			screen.getByRole( 'button', {
+				expanded: false,
+			} )
+		);
+
+		// return an array of items _with_ a className added
+		const itemsWithClass = props.options.filter(
+			( option ) => option.className !== undefined
+		);
+
+		// assert against filtered array
+		itemsWithClass.map( ( { name } ) =>
+			expect( screen.getByRole( 'option', { name } ) ).toHaveClass(
+				customClass
+			)
+		);
+
+		// return an array of items _without_ a className added
+		const itemsWithoutClass = props.options.filter(
+			( option ) => option.className === undefined
+		);
+
+		// assert against filtered array
+		itemsWithoutClass.map( ( { name } ) =>
+			expect( screen.getByRole( 'option', { name } ) ).not.toHaveClass(
+				customClass
+			)
+		);
+	} );
+
+	it( 'Should apply styles only to options that have styles defined', async () => {
+		const user = userEvent.setup();
+		const customStyles =
+			'background-color: rgb(127, 255, 212); rotate: 13deg;';
+
+		render( <CustomSelectControl { ...props } /> );
+
+		await user.click(
+			screen.getByRole( 'button', {
+				expanded: false,
+			} )
+		);
+
+		// return an array of items _with_ styles added
+		const styledItems = props.options.filter(
+			( option ) => option.style !== undefined
 		);
-		const toggleButton = screen.getByRole( 'button' );
-		await user.click( toggleButton );
 
-		const customSelect = screen.getByRole( 'listbox' );
-		await user.type( customSelect, '{enter}' );
+		// assert against filtered array
+		styledItems.map( ( { name } ) =>
+			expect( screen.getByRole( 'option', { name } ) ).toHaveStyle(
+				customStyles
+			)
+		);
+
+		// return an array of items _without_ styles added
+		const unstyledItems = props.options.filter(
+			( option ) => option.style === undefined
+		);
 
-		expect( onKeyDown ).toHaveBeenCalledTimes( 0 );
+		// assert against filtered array
+		unstyledItems.map( ( { name } ) =>
+			expect( screen.getByRole( 'option', { name } ) ).not.toHaveStyle(
+				customStyles
+			)
+		);
 	} );
 
 	it( 'does not show selected hint by default', () => {
 		render(
 			<CustomSelectControl
+				{ ...props }
 				label="Custom select"
 				options={ [
 					{
@@ -60,7 +211,6 @@ describe( 'CustomSelectControl', () => {
 						__experimentalHint: 'Hint',
 					},
 				] }
-				__nextUnconstrainedWidth
 			/>
 		);
 		expect(
@@ -71,6 +221,7 @@ describe( 'CustomSelectControl', () => {
 	it( 'shows selected hint when __experimentalShowSelectedHint is set', () => {
 		render(
 			<CustomSelectControl
+				{ ...props }
 				label="Custom select"
 				options={ [
 					{
@@ -80,11 +231,192 @@ describe( 'CustomSelectControl', () => {
 					},
 				] }
 				__experimentalShowSelectedHint
-				__nextUnconstrainedWidth
 			/>
 		);
 		expect(
 			screen.getByRole( 'button', { name: 'Custom select' } )
 		).toHaveTextContent( 'Hint' );
 	} );
+
+	describe( 'Keyboard behavior and accessibility', () => {
+		it( 'Captures the keypress event and does not let it propagate', async () => {
+			const user = userEvent.setup();
+			const onKeyDown = jest.fn();
+
+			render(
+				<div
+					// This role="none" is required to prevent an eslint warning about accessibility.
+					role="none"
+					onKeyDown={ onKeyDown }
+				>
+					<CustomSelectControl { ...props } />
+				</div>
+			);
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+			await user.click( currentSelectedItem );
+
+			const customSelect = screen.getByRole( 'listbox', {
+				name: 'label!',
+			} );
+			await user.type( customSelect, '{enter}' );
+
+			expect( onKeyDown ).toHaveBeenCalledTimes( 0 );
+		} );
+
+		it( 'Should be able to change selection using keyboard', async () => {
+			const user = userEvent.setup();
+
+			render( <CustomSelectControl { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.tab();
+			expect( currentSelectedItem ).toHaveFocus();
+
+			await user.keyboard( '{enter}' );
+			expect(
+				screen.getByRole( 'listbox', {
+					name: 'label!',
+				} )
+			).toHaveFocus();
+
+			await user.keyboard( '{arrowdown}' );
+			await user.keyboard( '{enter}' );
+
+			expect( currentSelectedItem ).toHaveTextContent( 'crimson clover' );
+		} );
+
+		it( 'Should be able to type characters to select matching options', async () => {
+			const user = userEvent.setup();
+
+			render( <CustomSelectControl { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.tab();
+			await user.keyboard( '{enter}' );
+			expect(
+				screen.getByRole( 'listbox', {
+					name: 'label!',
+				} )
+			).toHaveFocus();
+
+			await user.keyboard( '{a}' );
+			await user.keyboard( '{enter}' );
+			expect( currentSelectedItem ).toHaveTextContent( 'amber' );
+		} );
+
+		it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {
+			const user = userEvent.setup();
+
+			render( <CustomSelectControl { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.tab();
+			expect( currentSelectedItem ).toHaveFocus();
+
+			await user.keyboard( '{a}' );
+			await user.keyboard( '{q}' );
+
+			expect(
+				screen.queryByRole( 'listbox', {
+					name: 'label!',
+					hidden: true,
+				} )
+			).not.toBeInTheDocument();
+
+			await user.keyboard( '{enter}' );
+			expect( currentSelectedItem ).toHaveTextContent( 'aquamarine' );
+		} );
+
+		it( 'Should have correct aria-selected value for selections', async () => {
+			const user = userEvent.setup();
+
+			render( <CustomSelectControl { ...props } /> );
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.click( currentSelectedItem );
+
+			// get all items except for first option
+			const unselectedItems = props.options.filter(
+				( { name } ) => name !== props.options[ 0 ].name
+			);
+
+			// assert that all other items have aria-selected="false"
+			unselectedItems.map( ( { name } ) =>
+				expect(
+					screen.getByRole( 'option', { name, selected: false } )
+				).toBeVisible()
+			);
+
+			// assert that first item has aria-selected="true"
+			expect(
+				screen.getByRole( 'option', {
+					name: props.options[ 0 ].name,
+					selected: true,
+				} )
+			).toBeVisible();
+
+			// change the current selection
+			await user.click( screen.getByRole( 'option', { name: 'poppy' } ) );
+
+			// click button to mount listbox with options again
+			await user.click( currentSelectedItem );
+
+			// check that first item is has aria-selected="false" after new selection
+			expect(
+				screen.getByRole( 'option', {
+					name: props.options[ 0 ].name,
+					selected: false,
+				} )
+			).toBeVisible();
+
+			// check that new selected item now has aria-selected="true"
+			expect(
+				screen.getByRole( 'option', {
+					name: 'poppy',
+					selected: true,
+				} )
+			).toBeVisible();
+		} );
+
+		it( 'Should call custom event handlers', async () => {
+			const user = userEvent.setup();
+			const onFocusMock = jest.fn();
+			const onBlurMock = jest.fn();
+
+			render(
+				<CustomSelectControl
+					{ ...props }
+					onFocus={ onFocusMock }
+					onBlur={ onBlurMock }
+				/>
+			);
+
+			const currentSelectedItem = screen.getByRole( 'button', {
+				expanded: false,
+			} );
+
+			await user.tab();
+
+			expect( currentSelectedItem ).toHaveFocus();
+			expect( onFocusMock ).toHaveBeenCalledTimes( 1 );
+
+			await user.tab();
+			expect( currentSelectedItem ).not.toHaveFocus();
+			expect( onBlurMock ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
 } );

package/src/custom-select-control-v2/README.md

@@ -0,0 +1,73 @@
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+### `CustomSelect`
+
+Used to render a customizable select control component.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The child elements. This should be composed of CustomSelect.Item components.
+
+-   Required: yes
+
+##### `defaultValue`: `string`
+
+An optional default value for the control. If left `undefined`, the first non-disabled item will be used.
+
+-   Required: no
+
+##### `label`: `string`
+
+Label for the control.
+
+-   Required: yes
+
+##### `onChange`: `( newValue: string ) => void`
+
+A function that receives the new value of the input.
+
+-   Required: no
+
+##### `renderSelectedValue`: `( selectValue: string ) => React.ReactNode`
+
+Can be used to render select UI with custom styled values.
+
+-   Required: no
+
+##### `size`: `'default' | 'large'`
+
+The size of the control.
+
+-   Required: no
+
+##### `value`: `string`
+
+Can be used to externally control the value of the control.
+
+-   Required: no
+
+### `CustomSelectItem`
+
+Used to render a select item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `value`: `string`
+
+The value of the select item. This will be used as the children if children are left `undefined`.
+
+-   Required: yes
+
+##### `children`: `React.ReactNode`
+
+The children to display for each select item. The `value` will be used if left `undefined`.
+
+-   Required: no

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

@@ -0,0 +1,99 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+import { __, sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import * as Styled from './styles';
+import type {
+	CustomSelectProps,
+	CustomSelectItemProps,
+	CustomSelectContext as CustomSelectContextType,
+} from './types';
+
+export const CustomSelectContext =
+	createContext< CustomSelectContextType >( undefined );
+
+function defaultRenderSelectedValue( value: CustomSelectProps[ 'value' ] ) {
+	const isValueEmpty = Array.isArray( value )
+		? value.length === 0
+		: value === undefined || value === null;
+
+	if ( isValueEmpty ) {
+		return __( 'Select an item' );
+	}
+
+	if ( Array.isArray( value ) ) {
+		return value.length === 1
+			? value[ 0 ]
+			: // translators: %s: number of items selected (it will always be 2 or more items)
+			  sprintf( __( '%s items selected' ), value.length );
+	}
+
+	return value;
+}
+
+export function CustomSelect( props: CustomSelectProps ) {
+	const {
+		children,
+		defaultValue,
+		label,
+		onChange,
+		size = 'default',
+		value,
+		renderSelectedValue = defaultRenderSelectedValue,
+	} = props;
+
+	const store = Ariakit.useSelectStore( {
+		setValue: ( nextValue ) => onChange?.( nextValue ),
+		defaultValue,
+		value,
+	} );
+
+	const { value: currentValue } = store.useState();
+
+	return (
+		<>
+			<Styled.CustomSelectLabel store={ store }>
+				{ label }
+			</Styled.CustomSelectLabel>
+			<Styled.CustomSelectButton
+				size={ size }
+				hasCustomRenderProp={ !! renderSelectedValue }
+				store={ store }
+			>
+				{ renderSelectedValue( currentValue ) }
+				<Ariakit.SelectArrow />
+			</Styled.CustomSelectButton>
+			<Styled.CustomSelectPopover gutter={ 12 } store={ store } sameWidth>
+				<CustomSelectContext.Provider value={ { store } }>
+					{ children }
+				</CustomSelectContext.Provider>
+			</Styled.CustomSelectPopover>
+		</>
+	);
+}
+
+export function CustomSelectItem( {
+	children,
+	...props
+}: CustomSelectItemProps ) {
+	const customSelectContext = useContext( CustomSelectContext );
+	return (
+		<Styled.CustomSelectItem
+			store={ customSelectContext?.store }
+			{ ...props }
+		>
+			{ children ?? props.value }
+			<Ariakit.SelectItemCheck />
+		</Styled.CustomSelectItem>
+	);
+}