@wordpress/components 28.4.0 → 28.5.0

package/src/placeholder/style.scss

@@ -183,8 +183,17 @@
 		}
 	}
 
-	// By painting the borders here, we enable them to be replaced by the Border control.
-	@include placeholder-style();
+	&::before {
+		content: "";
+		position: absolute;
+		top: 0;
+		right: 0;
+		bottom: 0;
+		left: 0;
+		pointer-events: none;
+		background: currentColor;
+		opacity: 0.1;
+	}
 
 	overflow: hidden;
 	.is-selected & {

package/src/query-controls/index.tsx

@@ -85,7 +85,11 @@ export function QueryControls( {
 						__next40pxDefaultSize={ __next40pxDefaultSize }
 						key="query-controls-order-select"
 						label={ __( 'Order by' ) }
-						value={ `${ orderBy }/${ order }` }
+						value={
+							orderBy === undefined || order === undefined
+								? undefined
+								: `${ orderBy }/${ order }`
+						}
 						options={ [
 							{
 								label: __( 'Newest to oldest' ),

package/src/radio-control/index.tsx

@@ -16,6 +16,16 @@ import BaseControl from '../base-control';
 import type { WordPressComponentProps } from '../context';
 import type { RadioControlProps } from './types';
 import { VStack } from '../v-stack';
+import { useBaseControlProps } from '../base-control/hooks';
+import { StyledHelp } from '../base-control/styles/base-control-styles';
+
+function generateOptionDescriptionId( radioGroupId: string, index: number ) {
+	return `${ radioGroupId }-${ index }-option-description`;
+}
+
+function generateOptionId( radioGroupId: string, index: number ) {
+	return `${ radioGroupId }-${ index }`;
+}
 
 /**
  * Render a user interface to select the user type using radio inputs.
@@ -53,13 +63,23 @@ export function RadioControl(
 		onChange,
 		hideLabelFromVision,
 		options = [],
+		id: preferredId,
 		...additionalProps
 	} = props;
-	const instanceId = useInstanceId( RadioControl );
-	const id = `inspector-radio-control-${ instanceId }`;
+	const id = useInstanceId(
+		RadioControl,
+		'inspector-radio-control',
+		preferredId
+	);
+
 	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
 		onChange( event.target.value );
 
+	// Use `useBaseControlProps` to get the id of the help text.
+	const {
+		controlProps: { 'aria-describedby': helpTextId },
+	} = useBaseControlProps( { id, help } );
+
 	if ( ! options?.length ) {
 		return null;
 	}
@@ -73,14 +93,19 @@ export function RadioControl(
 			help={ help }
 			className={ clsx( className, 'components-radio-control' ) }
 		>
-			<VStack spacing={ 2 }>
+			<VStack
+				spacing={ 3 }
+				className={ clsx( 'components-radio-control__group-wrapper', {
+					'has-help': !! help,
+				} ) }
+			>
 				{ options.map( ( option, index ) => (
 					<div
-						key={ `${ id }-${ index }` }
+						key={ generateOptionId( id, index ) }
 						className="components-radio-control__option"
 					>
 						<input
-							id={ `${ id }-${ index }` }
+							id={ generateOptionId( id, index ) }
 							className="components-radio-control__input"
 							type="radio"
 							name={ id }
@@ -88,16 +113,32 @@ export function RadioControl(
 							onChange={ onChangeValue }
 							checked={ option.value === selected }
 							aria-describedby={
-								!! help ? `${ id }__help` : undefined
+								clsx( [
+									!! option.description &&
+										generateOptionDescriptionId(
+											id,
+											index
+										),
+									helpTextId,
+								] ) || undefined
 							}
 							{ ...additionalProps }
 						/>
 						<label
 							className="components-radio-control__label"
-							htmlFor={ `${ id }-${ index }` }
+							htmlFor={ generateOptionId( id, index ) }
 						>
 							{ option.label }
 						</label>
+						{ !! option.description ? (
+							<StyledHelp
+								__nextHasNoMarginBottom
+								id={ generateOptionDescriptionId( id, index ) }
+								className="components-radio-control__option-description"
+							>
+								{ option.description }
+							</StyledHelp>
+						) : null }
 					</div>
 				) ) }
 			</VStack>

package/src/radio-control/stories/index.story.tsx

@@ -68,3 +68,26 @@ Default.args = {
 		{ label: 'Password Protected', value: 'password' },
 	],
 };
+
+export const WithOptionDescriptions: StoryFn< typeof RadioControl > =
+	Template.bind( {} );
+WithOptionDescriptions.args = {
+	...Default.args,
+	options: [
+		{
+			label: 'Public',
+			value: 'public',
+			description: 'Visible to everyone',
+		},
+		{
+			label: 'Private',
+			value: 'private',
+			description: 'Only visible to you',
+		},
+		{
+			label: 'Password Protected',
+			value: 'password',
+			description: 'Protected by a password',
+		},
+	],
+};

package/src/radio-control/style.scss

@@ -1,13 +1,23 @@
+.components-radio-control__group-wrapper.has-help {
+	margin-block-end: $grid-unit-15;
+}
+
 .components-radio-control__option {
-	display: flex;
+	display: grid;
+	grid-template-columns: auto 1fr;
+	grid-template-rows: auto minmax(0, max-content);
+	column-gap: $grid-unit-10;
 	align-items: center;
 }
 
 .components-radio-control__input[type="radio"] {
+	grid-column: 1;
+	grid-row: 1;
+
 	@include radio-control;
 
 	display: inline-flex;
-	margin: 0 $grid-unit-10 0 0;
+	margin: 0;
 	padding: 0;
 	appearance: none;
 	cursor: pointer;
@@ -28,6 +38,9 @@
 }
 
 .components-radio-control__label {
+	grid-column: 2;
+	grid-row: 1;
+
 	cursor: pointer;
 	line-height: $radio-input-size-sm;
 
@@ -35,3 +48,14 @@
 		line-height: $radio-input-size;
 	}
 }
+
+.components-radio-control__option-description {
+	grid-column: 2;
+	grid-row: 2;
+
+	padding-block-start: $grid-unit-05;
+
+	// Override the top margin of the StyledHelp component from BaseControl.
+	// TODO: we should tweak the StyledHelp component to not have a top margin.
+	margin-top: 0;
+}

package/src/radio-control/test/index.tsx

@@ -0,0 +1,274 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import RadioControl from '../';
+
+const ControlledRadioControl = ( {
+	...props
+}: React.ComponentProps< typeof RadioControl > ) => {
+	const [ option, setOption ] = useState( props.selected );
+
+	return (
+		<RadioControl
+			{ ...props }
+			onChange={ ( newValue ) => {
+				setOption( newValue );
+				props.onChange?.( newValue );
+			} }
+			selected={ option }
+		/>
+	);
+};
+
+const defaultProps = {
+	options: [
+		{ label: 'Mouse', value: 'mouse' },
+		{ label: 'Cat', value: 'cat' },
+		{ label: 'Dog', value: 'dog' },
+	],
+	label: 'Animal',
+};
+
+const defaultPropsWithDescriptions = {
+	...defaultProps,
+	options: defaultProps.options.map( ( option, index ) => ( {
+		...option,
+		description: `This is the option number ${ index + 1 }.`,
+	} ) ),
+};
+
+describe.each( [
+	// TODO: `RadioControl` doesn't currently support uncontrolled mode.
+	// [ 'uncontrolled', RadioControl ],
+	[ 'controlled', ControlledRadioControl ],
+] )( 'RadioControl %s', ( ...modeAndComponent ) => {
+	const [ , Component ] = modeAndComponent;
+
+	describe( 'semantics and labelling', () => {
+		it( 'should render radio inputs with accessible labels', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			for ( const option of defaultProps.options ) {
+				const optionEl = screen.getByRole( 'radio', {
+					name: option.label,
+				} );
+				expect( optionEl ).toBeVisible();
+				expect( optionEl ).not.toBeChecked();
+			}
+		} );
+
+		it( 'should not select have a selected value when the `selected` prop does not match any available options', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			expect(
+				screen.queryByRole( 'radio', {
+					checked: true,
+				} )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'should render mutually exclusive radio inputs', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					onChange={ onChangeSpy }
+					selected={ defaultProps.options[ 1 ].value }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+				} )
+			).toHaveAccessibleName( defaultProps.options[ 1 ].label );
+		} );
+
+		it( 'should use the group help text to describe individual options', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					onChange={ onChangeSpy }
+					selected={ defaultProps.options[ 1 ].value }
+					help="Select your favorite animal."
+				/>
+			);
+
+			for ( const option of defaultProps.options ) {
+				expect(
+					screen.getByRole( 'radio', { name: option.label } )
+				).toHaveAccessibleDescription( 'Select your favorite animal.' );
+			}
+		} );
+
+		it( 'should use the option description text to describe individual options', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultPropsWithDescriptions }
+					onChange={ onChangeSpy }
+					selected={ defaultProps.options[ 1 ].value }
+				/>
+			);
+
+			let index = 1;
+			for ( const option of defaultProps.options ) {
+				expect(
+					screen.getByRole( 'radio', { name: option.label } )
+				).toHaveAccessibleDescription(
+					`This is the option number ${ index }.`
+				);
+				index += 1;
+			}
+		} );
+
+		it( 'should use both the option description text and the group help text to describe individual options', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultPropsWithDescriptions }
+					onChange={ onChangeSpy }
+					selected={ defaultProps.options[ 1 ].value }
+					help="Select your favorite animal"
+				/>
+			);
+
+			let index = 1;
+			for ( const option of defaultProps.options ) {
+				expect(
+					screen.getByRole( 'radio', { name: option.label } )
+				).toHaveAccessibleDescription(
+					`This is the option number ${ index }. Select your favorite animal`
+				);
+				index += 1;
+			}
+		} );
+	} );
+
+	describe( 'interaction', () => {
+		it( 'should select a new value when clicking on the radio input', async () => {
+			const user = userEvent.setup();
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			// Click on the third radio, make sure it's selected.
+			await user.click(
+				screen.getByRole( 'radio', {
+					name: defaultProps.options[ 2 ].label,
+				} )
+			);
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+				} )
+			).toHaveAccessibleName( defaultProps.options[ 2 ].label );
+
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 1 );
+			expect( onChangeSpy ).toHaveBeenLastCalledWith(
+				defaultProps.options[ 2 ].value
+			);
+		} );
+
+		it( 'should select a new value when clicking on the radio label', async () => {
+			const user = userEvent.setup();
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			// Click on the second radio's label, make sure it selects the associated radio.
+			await user.click(
+				screen.getByText( defaultProps.options[ 1 ].label )
+			);
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+				} )
+			).toHaveAccessibleName( defaultProps.options[ 1 ].label );
+
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 1 );
+			expect( onChangeSpy ).toHaveBeenLastCalledWith(
+				defaultProps.options[ 1 ].value
+			);
+		} );
+
+		it( 'should select a new value when using the arrow keys', async () => {
+			const user = userEvent.setup();
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			await user.tab();
+
+			expect(
+				screen.getByRole( 'radio', {
+					name: defaultProps.options[ 0 ].label,
+				} )
+			).toHaveFocus();
+
+			await user.keyboard( '{ArrowDown}' );
+
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+					name: defaultProps.options[ 1 ].label,
+				} )
+			).toHaveFocus();
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 2 );
+			expect( onChangeSpy ).toHaveBeenLastCalledWith(
+				defaultProps.options[ 1 ].value
+			);
+
+			await user.keyboard( '{ArrowDown}' );
+			await user.keyboard( '{ArrowDown}' );
+
+			// The selection wrap around.
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+					name: defaultProps.options[ 0 ].label,
+				} )
+			).toHaveFocus();
+			// TODO: why called twice for every interaction?
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 6 );
+			expect( onChangeSpy ).toHaveBeenLastCalledWith(
+				defaultProps.options[ 0 ].value
+			);
+
+			await user.keyboard( '{ArrowUp}' );
+
+			expect(
+				screen.getByRole( 'radio', {
+					checked: true,
+					name: defaultProps.options[ 2 ].label,
+				} )
+			).toHaveFocus();
+
+			expect( onChangeSpy ).toHaveBeenCalledTimes( 8 );
+			expect( onChangeSpy ).toHaveBeenLastCalledWith(
+				defaultProps.options[ 2 ].value
+			);
+		} );
+	} );
+} );

package/src/radio-control/types.ts

@@ -24,6 +24,10 @@ export type RadioControlProps = Pick<
 		 * The internal value compared against select and passed to onChange
 		 */
 		value: string;
+		/**
+		 * Optional help text to be shown in addition the label.
+		 */
+		description?: string;
 	}[];
 	/**
 	 * The value property of the currently selected option.

package/src/select-control/README.md

@@ -190,7 +190,7 @@ In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl`
 
 #### options
 
-An array of objects containing the following properties:
+An array of objects containing the following properties, as well as any other `option` element attributes:
 
 -   `label`: (string) The label to be shown to the user.
 -   `value`: (string) The internal value used to choose the selected value. This is also the value passed to onChange when the option is selected.
@@ -214,6 +214,13 @@ If multiple is false the value received is a single value with the new selected
 -   Type: `function`
 -   Required: Yes
 
+#### value
+
+The value of the selected option. If `multiple` is true, the `value` should be an array with the values of the selected options.
+
+-   Type: `String|String[]`
+-   Required: No
+
 #### variant
 
 The style variant of the control.

package/src/select-control/index.tsx

@@ -26,8 +26,24 @@ function useUniqueId( idProp?: string ) {
 	return idProp || id;
 }
 
-function UnforwardedSelectControl(
-	props: WordPressComponentProps< SelectControlProps, 'select', false >,
+function SelectOptions( {
+	options,
+}: {
+	options: NonNullable< SelectControlProps[ 'options' ] >;
+} ) {
+	return options.map( ( { id, label, value, ...optionProps }, index ) => {
+		const key = id || `${ label }-${ value }-${ index }`;
+
+		return (
+			<option key={ key } value={ value } { ...optionProps }>
+				{ label }
+			</option>
+		);
+	} );
+}
+
+function UnforwardedSelectControl< V extends string >(
+	props: WordPressComponentProps< SelectControlProps< V >, 'select', false >,
 	ref: React.ForwardedRef< HTMLSelectElement >
 ) {
 	const {
@@ -66,12 +82,14 @@ function UnforwardedSelectControl(
 			const selectedOptions = Array.from( event.target.options ).filter(
 				( { selected } ) => selected
 			);
-			const newValues = selectedOptions.map( ( { value } ) => value );
+			const newValues = selectedOptions.map(
+				( { value } ) => value as V
+			);
 			props.onChange?.( newValues, { event } );
 			return;
 		}
 
-		props.onChange?.( event.target.value, { event } );
+		props.onChange?.( event.target.value as V, { event } );
 	};
 
 	const classes = clsx( 'components-select-control', className );
@@ -115,23 +133,7 @@ function UnforwardedSelectControl(
 					value={ valueProp }
 					variant={ variant }
 				>
-					{ children ||
-						options.map( ( option, index ) => {
-							const key =
-								option.id ||
-								`${ option.label }-${ option.value }-${ index }`;
-
-							return (
-								<option
-									key={ key }
-									value={ option.value }
-									disabled={ option.disabled }
-									hidden={ option.hidden }
-								>
-									{ option.label }
-								</option>
-							);
-						} ) }
+					{ children || <SelectOptions options={ options } /> }
 				</Select>
 			</StyledInputBase>
 		</BaseControl>
@@ -151,6 +153,7 @@ function UnforwardedSelectControl(
  *
  *   return (
  *     <SelectControl
+ *       __nextHasNoMarginBottom
  *       label="Size"
  *       value={ size }
  *       options={ [
@@ -164,6 +167,14 @@ function UnforwardedSelectControl(
  * };
  * ```
  */
-export const SelectControl = forwardRef( UnforwardedSelectControl );
+export const SelectControl = forwardRef( UnforwardedSelectControl ) as <
+	V extends string,
+>(
+	props: WordPressComponentProps<
+		SelectControlProps< V >,
+		'select',
+		false
+	> & { ref?: React.Ref< HTMLSelectElement > }
+) => React.JSX.Element | null;
 
 export default SelectControl;