@wordpress/components 28.4.0 → 28.6.0

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

@@ -0,0 +1,277 @@
+/**
+ * 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 group all radios under a fieldset with an accessible label (legend)', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toBeVisible();
+		} );
+
+		it( 'should group all radios under a fieldset with an accessible label even when the label is visually hidden', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					hideLabelFromVision
+					onChange={ onChangeSpy }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toBeVisible();
+		} );
+
+		it( 'should describe the radio group with the help text', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					help="Test help text"
+					onChange={ onChangeSpy }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toHaveAccessibleDescription( 'Test help text' );
+		} );
+
+		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 option description text to describe individual options', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultPropsWithDescriptions }
+					onChange={ onChangeSpy }
+					selected={ defaultProps.options[ 1 ].value }
+					help="Select your favorite animal"
+				/>
+			);
+
+			// Group help text should not be used to describe individual options.
+			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;
+			}
+		} );
+	} );
+
+	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/radio-group/radio.tsx

@@ -7,6 +7,7 @@ import { forwardRef, useContext } from '@wordpress/element';
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
+import { useStoreState } from '@ariakit/react';
 
 /**
  * Internal dependencies
@@ -26,7 +27,7 @@ function UnforwardedRadio(
 ) {
 	const { store, disabled } = useContext( RadioGroupContext );
 
-	const selectedValue = store?.useState( 'value' );
+	const selectedValue = useStoreState( store, 'value' );
 	const isChecked = selectedValue !== undefined && selectedValue === value;
 
 	return (

package/src/range-control/README.md

@@ -362,6 +362,13 @@ Determines if the `input` number field will render next to the RangeControl. Thi
 -   Required: No
 -   Platform: Web
 
+### `__next40pxDefaultSize`: `boolean`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+-   Required: No
+-   Default: `false`
+
 ### `__nextHasNoMarginBottom`: `boolean`
 
 Start opting into the new margin-free styles that will become the default in a future version.

package/src/range-control/index.tsx

@@ -41,6 +41,25 @@ import { space } from '../utils/space';
 
 const noop = () => {};
 
+/**
+ * Computes the value that `RangeControl` should reset to when pressing
+ * the reset button.
+ */
+function computeResetValue( {
+	resetFallbackValue,
+	initialPosition,
+}: Pick< RangeControlProps, 'resetFallbackValue' | 'initialPosition' > ) {
+	if ( resetFallbackValue !== undefined ) {
+		return ! Number.isNaN( resetFallbackValue ) ? resetFallbackValue : null;
+	}
+
+	if ( initialPosition !== undefined ) {
+		return ! Number.isNaN( initialPosition ) ? initialPosition : null;
+	}
+
+	return null;
+}
+
 function UnforwardedRangeControl(
 	props: WordPressComponentProps< RangeControlProps, 'input', false >,
 	forwardedRef: ForwardedRef< HTMLInputElement >
@@ -166,13 +185,12 @@ function UnforwardedRangeControl(
 	};
 
 	const handleOnReset = () => {
-		let resetValue: number | null = parseFloat( `${ resetFallbackValue }` );
-		let onChangeResetValue: number | undefined = resetValue;
-
-		if ( isNaN( resetValue ) ) {
-			resetValue = null;
-			onChangeResetValue = undefined;
-		}
+		// Reset to `resetFallbackValue` if defined, otherwise set internal value
+		// to `null` — which, if propagated to the `value` prop, will cause
+		// the value to be reset to the `initialPosition` prop if defined.
+		const resetValue = Number.isNaN( resetFallbackValue )
+			? null
+			: resetFallbackValue ?? null;
 
 		setValue( resetValue );
 
@@ -189,7 +207,7 @@ function UnforwardedRangeControl(
 		 * preserve the undefined callback argument, except when a
 		 * resetFallbackValue is defined.
 		 */
-		onChange( onChangeResetValue );
+		onChange( resetValue ?? undefined );
 	};
 
 	const handleShowTooltip = () => setShowTooltip( true );
@@ -210,9 +228,11 @@ function UnforwardedRangeControl(
 	const offsetStyle = {
 		[ isRTL() ? 'right' : 'left' ]: fillValueOffset,
 	};
+
 	return (
 		<BaseControl
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			__associatedWPComponentName="RangeControl"
 			className={ classes }
 			label={ label }
 			hideLabelFromVision={ hideLabelFromVision }
@@ -328,7 +348,17 @@ function UnforwardedRangeControl(
 							className="components-range-control__reset"
 							// If the RangeControl itself is disabled, the reset button shouldn't be in the tab sequence.
 							accessibleWhenDisabled={ ! disabled }
-							disabled={ disabled || value === undefined }
+							// The reset button should be disabled if RangeControl itself is disabled,
+							// or if the current `value` is equal to the value that would be currently
+							// assigned when clicking the button.
+							disabled={
+								disabled ||
+								value ===
+									computeResetValue( {
+										resetFallbackValue,
+										initialPosition,
+									} )
+							}
 							variant="secondary"
 							size="small"
 							onClick={ handleOnReset }

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

@@ -70,6 +70,7 @@ const Template: StoryFn< typeof RangeControl > = ( { onChange, ...args } ) => {
 
 export const Default: StoryFn< typeof RangeControl > = Template.bind( {} );
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	help: 'Please select how transparent you would like this.',
 	initialPosition: 50,
 	label: 'Opacity',
@@ -104,6 +105,7 @@ export const WithAnyStep: StoryFn< typeof RangeControl > = ( {
 	);
 };
 WithAnyStep.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Brightness',
 	step: 'any',
 };
@@ -167,6 +169,7 @@ export const WithIntegerStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithIntegerStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Integer Step',
 	marks: marksBase,
 	max: 10,
@@ -183,6 +186,7 @@ export const WithDecimalStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithDecimalStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: [
 		...marksBase,
 		{ value: 3.5, label: '3.5' },
@@ -202,6 +206,7 @@ export const WithNegativeMinimumAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithNegativeMinimumAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksWithNegatives,
 	max: 10,
 	min: -10,
@@ -217,6 +222,7 @@ export const WithNegativeRangeAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithNegativeRangeAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksWithNegatives,
 	max: -1,
 	min: -10,
@@ -232,6 +238,7 @@ export const WithAnyStepAndMarks: StoryFn< typeof RangeControl > =
 	MarkTemplate.bind( {} );
 
 WithAnyStepAndMarks.args = {
+	__nextHasNoMarginBottom: true,
 	marks: marksBase,
 	max: 10,
 	min: 0,

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

@@ -154,7 +154,7 @@ export const Mark = styled.span`
 	height: ${ thumbSize }px;
 	left: 0;
 	position: absolute;
-	top: -4px;
+	top: 9px;
 	width: 1px;
 
 	${ markFill };
@@ -170,7 +170,7 @@ export const MarkLabel = styled.span`
 	color: ${ COLORS.gray[ 300 ] };
 	font-size: 11px;
 	position: absolute;
-	top: 12px;
+	top: 22px;
 	white-space: nowrap;
 
 	${ rtl( { left: 0 } ) };

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

@@ -6,7 +6,7 @@ import { act, fireEvent, render, screen } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import RangeControl from '../';
+import _RangeControl from '../';
 
 const getRangeInput = (): HTMLInputElement => screen.getByRole( 'slider' );
 const getNumberInput = (): HTMLInputElement => screen.getByRole( 'spinbutton' );
@@ -15,6 +15,12 @@ const getResetButton = (): HTMLButtonElement => screen.getByRole( 'button' );
 const fireChangeEvent = ( input: HTMLInputElement, value?: number | string ) =>
 	fireEvent.change( input, { target: { value } } );
 
+const RangeControl = (
+	props: React.ComponentProps< typeof _RangeControl >
+) => {
+	return <_RangeControl { ...props } __nextHasNoMarginBottom />;
+};
+
 describe( 'RangeControl', () => {
 	describe( '#render()', () => {
 		it( 'should trigger change callback with numeric value', () => {
@@ -292,14 +298,37 @@ describe( 'RangeControl', () => {
 	} );
 
 	describe( 'reset', () => {
-		it( 'should reset to a custom fallback value, defined by a parent component', () => {
+		it( 'should clear the input value when clicking the reset button', () => {
+			const spy = jest.fn();
+			render( <RangeControl allowReset onChange={ spy } /> );
+
+			const resetButton = getResetButton();
+			const rangeInput = getRangeInput();
+			const numberInput = getNumberInput();
+
+			fireChangeEvent( numberInput, '14' );
+
+			expect( rangeInput.value ).toBe( '14' );
+			expect( numberInput.value ).toBe( '14' );
+			expect( spy ).toHaveBeenCalledWith( 14 );
+
+			fireEvent.click( resetButton );
+
+			// range input resets to min + (max-min)/2
+			expect( rangeInput.value ).toBe( '50' );
+			expect( numberInput.value ).toBe( '' );
+			expect( spy ).toHaveBeenCalledWith( undefined );
+
+			expect( resetButton ).toHaveAttribute( 'aria-disabled', 'true' );
+		} );
+
+		it( 'should reset to the `initialPosition` value when clicking the reset button', () => {
 			const spy = jest.fn();
 			render(
 				<RangeControl
-					initialPosition={ 10 }
 					allowReset
+					initialPosition={ 23 }
 					onChange={ spy }
-					resetFallbackValue={ 33 }
 				/>
 			);
 
@@ -307,21 +336,29 @@ describe( 'RangeControl', () => {
 			const rangeInput = getRangeInput();
 			const numberInput = getNumberInput();
 
+			fireChangeEvent( numberInput, '14' );
+
+			expect( rangeInput.value ).toBe( '14' );
+			expect( numberInput.value ).toBe( '14' );
+			expect( spy ).toHaveBeenCalledWith( 14 );
+
 			fireEvent.click( resetButton );
 
-			expect( rangeInput.value ).toBe( '33' );
-			expect( numberInput.value ).toBe( '33' );
-			expect( spy ).toHaveBeenCalledWith( 33 );
+			expect( rangeInput.value ).toBe( '23' );
+			expect( numberInput.value ).toBe( '23' );
+			expect( spy ).toHaveBeenCalledWith( undefined );
+
+			expect( resetButton ).toHaveAttribute( 'aria-disabled', 'true' );
 		} );
 
-		it( 'should reset to a 50% of min/max value, of no initialPosition or value is defined', () => {
+		it( 'should reset to the `resetFallbackValue` value when clicking the reset button', () => {
+			const spy = jest.fn();
 			render(
 				<RangeControl
-					initialPosition={ undefined }
-					min={ 0 }
-					max={ 100 }
+					initialPosition={ 10 }
 					allowReset
-					resetFallbackValue={ undefined }
+					onChange={ spy }
+					resetFallbackValue={ 33 }
 				/>
 			);
 
@@ -331,8 +368,11 @@ describe( 'RangeControl', () => {
 
 			fireEvent.click( resetButton );
 
-			expect( rangeInput.value ).toBe( '50' );
-			expect( numberInput.value ).toBe( '' );
+			expect( rangeInput.value ).toBe( '33' );
+			expect( numberInput.value ).toBe( '33' );
+			expect( spy ).toHaveBeenCalledWith( 33 );
+
+			expect( resetButton ).toHaveAttribute( 'aria-disabled', 'true' );
 		} );
 	} );
 } );

package/src/search-control/index.tsx

@@ -77,10 +77,13 @@ function UnforwardedSearchControl(
 
 	const contextValue = useMemo(
 		() => ( {
-			// Overrides the underlying BaseControl `__nextHasNoMarginBottom` via the context system
-			// to provide backwards compatibile margin for SearchControl.
-			// (In a standard InputControl, the BaseControl `__nextHasNoMarginBottom` is always set to true.)
-			BaseControl: { _overrides: { __nextHasNoMarginBottom } },
+			BaseControl: {
+				// Overrides the underlying BaseControl `__nextHasNoMarginBottom` via the context system
+				// to provide backwards compatibile margin for SearchControl.
+				// (In a standard InputControl, the BaseControl `__nextHasNoMarginBottom` is always set to true.)
+				_overrides: { __nextHasNoMarginBottom },
+				__associatedWPComponentName: 'SearchControl',
+			},
 			// `isBorderless` is still experimental and not a public prop for InputControl yet.
 			InputBase: { isBorderless: true },
 		} ),

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

@@ -48,6 +48,7 @@ const Template: StoryFn< typeof SearchControl > = ( {
 export const Default = Template.bind( {} );
 Default.args = {
 	help: 'Help text to explain the input.',
+	__nextHasNoMarginBottom: true,
 };
 
 /**

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

@@ -23,6 +23,7 @@ function ControlledSearchControl( {
 	return (
 		<SearchControl
 			{ ...restProps }
+			__nextHasNoMarginBottom
 			value={ value }
 			onChange={ ( ...args ) => {
 				setValue( ...args );

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.
@@ -222,6 +229,14 @@ The style variant of the control.
 -   Required: No
 -   Default: `'default'`
 
+### __next40pxDefaultSize
+
+Start opting into the larger default height that will become the default size in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
 ### __nextHasNoMarginBottom
 
 Start opting into the new margin-free styles that will become the default in a future version.