@wordpress/components 28.3.0 → 28.5.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/range-control/README.md

@@ -90,6 +90,7 @@ const MyRangeControl = () => {
 
 	return(
 		<RangeControl
+			__nextHasNoMarginBottom
 			label="Columns"
 			value={ columns }
 			onChange={ ( value ) => setColumns( value ) }
@@ -361,6 +362,13 @@ Determines if the `input` number field will render next to the RangeControl. Thi
 -   Required: No
 -   Platform: Web
 
+### `__nextHasNoMarginBottom`: `boolean`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   To collect a numerical input in a text field, use the `TextControl` component.

package/src/range-control/index.tsx

@@ -353,6 +353,7 @@ function UnforwardedRangeControl(
  *   const [ isChecked, setChecked ] = useState( true );
  *   return (
  *     <RangeControl
+ *       __nextHasNoMarginBottom
  *       help="Please select how transparent you would like this."
  *       initialPosition={50}
  *       label="Opacity"

package/src/resizable-box/resize-tooltip/README.md

@@ -60,7 +60,7 @@ Determines if the label can render.
 
 ### labelRef
 
-Callback [Ref](https://reactjs.org/docs/forwarding-refs.html) for the label element.
+Callback [Ref](https://react.dev/learn/manipulating-the-dom-with-refs) for the label element.
 
 -   Type: `Function`
 -   Required: No

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,21 @@ 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.
+
+-   Type: `'default' | 'minimal'`
+-   Required: No
+-   Default: `'default'`
+
 ### __nextHasNoMarginBottom
 
 Start opting into the new margin-free styles that will become the default in a future version.

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 {
@@ -46,6 +62,7 @@ function UnforwardedSelectControl(
 		children,
 		prefix,
 		suffix,
+		variant = 'default',
 		__next40pxDefaultSize = false,
 		__nextHasNoMarginBottom = false,
 		...restProps
@@ -65,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 );
@@ -86,6 +105,7 @@ function UnforwardedSelectControl(
 				disabled={ disabled }
 				hideLabelFromVision={ hideLabelFromVision }
 				id={ id }
+				isBorderless={ variant === 'minimal' }
 				label={ label }
 				size={ size }
 				suffix={
@@ -93,6 +113,10 @@ function UnforwardedSelectControl(
 				}
 				prefix={ prefix }
 				labelPosition={ labelPosition }
+				__unstableInputWidth={
+					variant === 'minimal' ? 'auto' : undefined
+				}
+				variant={ variant }
 				__next40pxDefaultSize={ __next40pxDefaultSize }
 			>
 				<Select
@@ -107,24 +131,9 @@ function UnforwardedSelectControl(
 					ref={ ref }
 					selectSize={ size }
 					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>
@@ -144,6 +153,7 @@ function UnforwardedSelectControl(
  *
  *   return (
  *     <SelectControl
+ *       __nextHasNoMarginBottom
  *       label="Size"
  *       value={ size }
  *       options={ [
@@ -157,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;

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

@@ -100,3 +100,9 @@ export const WithCustomChildren: StoryFn< typeof SelectControl > = ( args ) => {
 		</SelectControlWithState>
 	);
 };
+
+export const Minimal = SelectControlWithState.bind( {} );
+Minimal.args = {
+	...Default.args,
+	variant: 'minimal',
+};

package/src/select-control/styles/select-control-styles.ts

@@ -17,7 +17,7 @@ import InputBase from '../../input-control/input-base';
 interface SelectProps
 	extends Pick<
 		SelectControlProps,
-		'__next40pxDefaultSize' | 'disabled' | 'multiple'
+		'__next40pxDefaultSize' | 'disabled' | 'multiple' | 'variant'
 	> {
 	// Using `selectSize` instead of `size` to avoid a type conflict with the
 	// `size` HTML attribute of the `select` element.
@@ -35,11 +35,22 @@ const disabledStyles = ( { disabled }: SelectProps ) => {
 	`;
 };
 
+const inputBaseVariantStyles = ( { variant }: SelectProps ) => {
+	if ( variant === 'minimal' ) {
+		return css`
+			display: inline-flex;
+		`;
+	}
+
+	return '';
+};
+
 export const StyledInputBase = styled( InputBase )`
 	color: ${ COLORS.theme.foreground };
 	cursor: pointer;
 
 	${ disabledStyles }
+	${ inputBaseVariantStyles }
 `;
 
 const sizeStyles = ( {
@@ -127,6 +138,16 @@ const overflowStyles = ( { multiple }: SelectProps ) => {
 	};
 };
 
+const variantStyles = ( { variant }: SelectProps ) => {
+	if ( variant === 'minimal' ) {
+		return css( {
+			fieldSizing: 'content',
+		} );
+	}
+
+	return '';
+};
+
 // TODO: Resolve need to use &&& to increase specificity
 // https://github.com/WordPress/gutenberg/issues/18483
 
@@ -137,6 +158,7 @@ export const Select = styled.select< SelectProps >`
 		box-sizing: border-box;
 		border: none;
 		box-shadow: none !important;
+		color: currentColor; // Overrides hover/focus styles in forms.css
 		cursor: inherit;
 		display: block;
 		font-family: inherit;
@@ -150,6 +172,7 @@ export const Select = styled.select< SelectProps >`
 		${ sizeStyles };
 		${ sizePaddings };
 		${ overflowStyles }
+		${ variantStyles }
 	}
 `;