@wordpress/components 32.4.1-next.v.202603102151.0 → 32.5.0

package/src/toggle-group-control/test/index.tsx

@@ -353,6 +353,60 @@ describe.each( [
 		);
 	}
 
+	it( 'should render the label', () => {
+		render(
+			<Component label="Test Toggle Group Control">{ options }</Component>
+		);
+
+		expect( screen.getByText( 'Test Toggle Group Control' ) ).toBeVisible();
+	} );
+
+	it( 'should still label the control accessibly when hideLabelFromVision is true', () => {
+		render(
+			<Component label="Test Toggle Group Control" hideLabelFromVision>
+				{ options }
+			</Component>
+		);
+
+		expect(
+			screen.getByRole( 'radiogroup', {
+				name: 'Test Toggle Group Control',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'should accessibly associate the help text', () => {
+		render(
+			<Component label="Test Toggle Group Control" help="Help text">
+				{ options }
+			</Component>
+		);
+
+		expect(
+			screen.getByRole( 'radiogroup', {
+				description: 'Help text',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'should accessibly associate the help text when isDeselectable', () => {
+		render(
+			<Component
+				label="Test Toggle Group Control"
+				help="Help text"
+				isDeselectable
+			>
+				{ options }
+			</Component>
+		);
+
+		expect(
+			screen.getByRole( 'group', {
+				description: 'Help text',
+			} )
+		).toBeVisible();
+	} );
+
 	describe( 'isDeselectable', () => {
 		describe( 'isDeselectable = false', () => {
 			it( 'should not be deselectable', async () => {

package/src/toggle-group-control/toggle-group-control/as-button-group.tsx

@@ -83,6 +83,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 				{ ...otherProps }
 				ref={ forwardedRef }
 				role="group"
+				id={ baseId }
 			>
 				{ children }
 			</View>

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -15,9 +15,8 @@ import { useMergeRefs } from '@wordpress/compose';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect, useContextSystem } from '../../context';
 import { useCx } from '../../utils/hooks';
-import BaseControl from '../../base-control';
+import BaseControl, { useBaseControlProps } from '../../base-control';
 import type { ToggleGroupControlProps } from '../types';
-import { VisualLabelWrapper } from './styles';
 import * as styles from './styles';
 import { ToggleGroupControlAsRadioGroup } from './as-radio-group';
 import { ToggleGroupControlAsButtonGroup } from './as-button-group';
@@ -37,6 +36,7 @@ function UnconnectedToggleGroupControl(
 		isAdaptiveWidth = false,
 		isBlock = false,
 		isDeselectable = false,
+		id,
 		label,
 		hideLabelFromVision = false,
 		help,
@@ -47,6 +47,13 @@ function UnconnectedToggleGroupControl(
 		...otherProps
 	} = useContextSystem( props, 'ToggleGroupControl' );
 
+	const { baseControlProps, controlProps } = useBaseControlProps( {
+		id,
+		help,
+		label,
+		hideLabelFromVision,
+	} );
+
 	const normalizedSize =
 		__next40pxDefaultSize && size === 'default' ? '__unstable-large' : size;
 
@@ -91,17 +98,15 @@ function UnconnectedToggleGroupControl(
 	} );
 
 	return (
-		<BaseControl help={ help }>
-			{ ! hideLabelFromVision && (
-				<VisualLabelWrapper>
-					<BaseControl.VisualLabel>{ label }</BaseControl.VisualLabel>
-				</VisualLabelWrapper>
-			) }
+		<BaseControl { ...baseControlProps }>
 			<MainControl
 				{ ...otherProps }
+				{ ...controlProps }
 				setSelectedElement={ setSelectedElement }
 				className={ classes }
 				isAdaptiveWidth={ isAdaptiveWidth }
+				// `label` is used for `aria-label` on the inner control.
+				// This is separate from the visual label rendered by `BaseControl`.
 				label={ label }
 				onChange={ onChange }
 				ref={ refs }

package/src/toggle-group-control/toggle-group-control/styles.ts

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { css } from '@emotion/react';
-import styled from '@emotion/styled';
 
 /**
  * Internal dependencies
@@ -100,8 +99,3 @@ export const block = css`
 	display: flex;
 	width: 100%;
 `;
-
-export const VisualLabelWrapper = styled.div`
-	// Makes the inline label be the correct height, equivalent to setting line-height: 0
-	display: flex;
-`;

package/src/validated-form-controls/control-with-error.tsx

@@ -6,6 +6,7 @@ import {
 	cloneElement,
 	forwardRef,
 	useEffect,
+	useId,
 	useState,
 } from '@wordpress/element';
 
@@ -238,22 +239,61 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 		}
 	};
 
-	const message = () => {
+	const messageId = useId();
+
+	const message = ( () => {
 		if ( errorMessage ) {
 			return (
-				<ValidityIndicator type="invalid" message={ errorMessage } />
+				<ValidityIndicator
+					id={ messageId }
+					type="invalid"
+					message={ errorMessage }
+				/>
 			);
 		}
 		if ( statusMessage?.type ) {
 			return (
 				<ValidityIndicator
+					id={ messageId }
 					type={ statusMessage.type }
 					message={ statusMessage.message }
 				/>
 			);
 		}
 		return null;
-	};
+	} )();
+
+	const visibleMessage = showMessage ? message : null;
+
+	// Imperatively manage `aria-describedby` on the validity target so we
+	// merge with any value the child control sets internally (e.g. from a
+	// `help` prop), rather than competing with it at the props level.
+	useEffect( () => {
+		const target = getValidityTarget();
+		if ( ! target ) {
+			return;
+		}
+
+		function setDescribedBy( el: Element, shouldAdd: boolean ) {
+			const ids = ( el.getAttribute( 'aria-describedby' ) ?? '' )
+				.split( ' ' )
+				.filter( ( id ) => id && id !== messageId );
+
+			if ( shouldAdd ) {
+				ids.push( messageId );
+			}
+
+			if ( ids.length ) {
+				el.setAttribute( 'aria-describedby', ids.join( ' ' ) );
+			} else {
+				el.removeAttribute( 'aria-describedby' );
+			}
+		}
+
+		setDescribedBy( target, !! visibleMessage );
+
+		return () => setDescribedBy( target, false );
+	}, [ visibleMessage, messageId, getValidityTarget ] );
 
 	return (
 		<div className={ className } ref={ forwardedRef } onBlur={ onBlur }>
@@ -265,7 +305,7 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 				),
 				required,
 			} ) }
-			<div aria-live="polite">{ showMessage && message() }</div>
+			<div aria-live="polite">{ visibleMessage }</div>
 		</div>
 	);
 }

package/src/validated-form-controls/test/checkbox-control.tsx

@@ -0,0 +1,49 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedCheckboxControl } from '../components';
+
+describe( 'ValidatedCheckboxControl', () => {
+	it( 'should preserve the help description', () => {
+		render(
+			<ValidatedCheckboxControl
+				label="Agree"
+				help="You must agree to continue."
+				onChange={ () => {} }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'checkbox', { name: 'Agree' } )
+		).toHaveAccessibleDescription( 'You must agree to continue.' );
+	} );
+
+	it( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedCheckboxControl
+					label="Agree"
+					help="You must agree to continue."
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const checkbox = screen.getByRole( 'checkbox', {
+			name: /^Agree/,
+		} );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		await waitFor( () => {
+			expect( checkbox ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Constraints not satisfied' )
+			);
+		} );
+		expect( checkbox ).toHaveAccessibleDescription(
+			expect.stringContaining( 'You must agree to continue.' )
+		);
+	} );
+} );

package/src/validated-form-controls/test/combobox-control.tsx

@@ -0,0 +1,61 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedComboboxControl } from '../components';
+
+// The `help` prop is rendered visually by BaseControl but is not
+// programmatically associated with the combobox input via aria-describedby.
+// This is a pre-existing bug in ComboboxControl, not caused by ControlWithError.
+describe( 'ValidatedComboboxControl', () => {
+	const options = [
+		{ label: 'Apple', value: 'apple' },
+		{ label: 'Banana', value: 'banana' },
+	];
+
+	// eslint-disable-next-line jest/no-disabled-tests
+	it.skip( 'should preserve the help description', () => {
+		render(
+			<ValidatedComboboxControl
+				label="Fruit"
+				help="Pick a fruit."
+				options={ options }
+				onChange={ () => {} }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', { name: 'Fruit' } )
+		).toHaveAccessibleDescription( 'Pick a fruit.' );
+	} );
+
+	// eslint-disable-next-line jest/no-disabled-tests
+	it.skip( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedComboboxControl
+					label="Fruit"
+					help="Pick a fruit."
+					options={ options }
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const combobox = screen.getByRole( 'combobox', {
+			name: /^Fruit/,
+		} );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		await waitFor( () => {
+			expect( combobox ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Constraints not satisfied' )
+			);
+		} );
+		expect( combobox ).toHaveAccessibleDescription(
+			expect.stringContaining( 'Pick a fruit.' )
+		);
+	} );
+} );

package/src/validated-form-controls/test/control-with-error.tsx

@@ -7,7 +7,7 @@ import userEvent from '@testing-library/user-event';
 /**
  * WordPress dependencies
  */
-import { useState, useCallback, useRef } from '@wordpress/element';
+import { useState, useCallback, useId, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -283,6 +283,187 @@ describe( 'ControlWithError', () => {
 		} );
 	} );
 
+	describe( 'aria-describedby', () => {
+		it( 'should connect the error message to the input via aria-describedby', async () => {
+			const user = userEvent.setup();
+			render(
+				<form>
+					<ValidatedInputControl label="URL" required />
+					<button type="submit">Submit</button>
+				</form>
+			);
+
+			const input = screen.getByRole( 'textbox', { name: /^URL/ } );
+
+			expect( input ).not.toHaveAttribute( 'aria-describedby' );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Submit' } )
+			);
+
+			await waitFor( () => {
+				expect( input ).toHaveAccessibleDescription(
+					expect.stringContaining( 'Constraints not satisfied' )
+				);
+			} );
+		} );
+
+		it( 'should preserve existing aria-describedby values', async () => {
+			const user = userEvent.setup();
+
+			function TestComponent() {
+				const hintId = useId();
+				return (
+					<form>
+						<ValidatedInputControl
+							label="URL"
+							required
+							aria-describedby={ hintId }
+						/>
+						<p id={ hintId }>Enter a full URL.</p>
+						<button type="submit">Submit</button>
+					</form>
+				);
+			}
+
+			render( <TestComponent /> );
+
+			const input = screen.getByRole( 'textbox', { name: /^URL/ } );
+
+			expect( input ).toHaveAccessibleDescription( 'Enter a full URL.' );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Submit' } )
+			);
+
+			await waitFor( () => {
+				expect( input ).toHaveAccessibleDescription(
+					expect.stringContaining( 'Constraints not satisfied' )
+				);
+			} );
+			expect( input ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Enter a full URL.' )
+			);
+		} );
+
+		it( 'should connect a custom validity error to the input via aria-describedby', async () => {
+			const user = userEvent.setup();
+
+			function TestComponent() {
+				const [ customValidity, setCustomValidity ] =
+					useState<
+						React.ComponentProps<
+							typeof ValidatedInputControl
+						>[ 'customValidity' ]
+					>( undefined );
+				const inputRef = useRef< HTMLInputElement >( null );
+
+				return (
+					<>
+						<ValidatedInputControl
+							ref={ inputRef }
+							label="URL"
+							customValidity={ customValidity }
+						/>
+						<button
+							type="button"
+							onClick={ () => {
+								setCustomValidity( {
+									type: 'invalid',
+									message: 'Please enter a valid URL.',
+								} );
+								requestAnimationFrame(
+									() => inputRef.current?.reportValidity()
+								);
+							} }
+						>
+							Validate
+						</button>
+					</>
+				);
+			}
+
+			render( <TestComponent /> );
+
+			const input = screen.getByRole( 'textbox', { name: 'URL' } );
+			expect( input ).not.toHaveAttribute( 'aria-describedby' );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Validate' } )
+			);
+
+			await waitFor( () => {
+				expect( input ).toHaveAccessibleDescription(
+					expect.stringContaining( 'Please enter a valid URL.' )
+				);
+			} );
+		} );
+
+		it( 'should remove aria-describedby when the error is resolved', async () => {
+			const user = userEvent.setup();
+
+			function TestComponent() {
+				const [ customValidity, setCustomValidity ] =
+					useState<
+						React.ComponentProps<
+							typeof ValidatedInputControl
+						>[ 'customValidity' ]
+					>( undefined );
+				const inputRef = useRef< HTMLInputElement >( null );
+
+				return (
+					<>
+						<ValidatedInputControl
+							ref={ inputRef }
+							label="URL"
+							customValidity={ customValidity }
+						/>
+						<button
+							type="button"
+							onClick={ () => {
+								setCustomValidity( {
+									type: 'invalid',
+									message: 'Please enter a valid URL.',
+								} );
+								requestAnimationFrame(
+									() => inputRef.current?.reportValidity()
+								);
+							} }
+						>
+							Validate
+						</button>
+						<button
+							type="button"
+							onClick={ () => setCustomValidity( undefined ) }
+						>
+							Clear
+						</button>
+					</>
+				);
+			}
+
+			render( <TestComponent /> );
+
+			const input = screen.getByRole( 'textbox', { name: 'URL' } );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Validate' } )
+			);
+
+			await waitFor( () => {
+				expect( input ).toHaveAccessibleDescription(
+					expect.stringContaining( 'Please enter a valid URL.' )
+				);
+			} );
+
+			await user.click( screen.getByRole( 'button', { name: 'Clear' } ) );
+
+			await waitFor( () => {
+				expect( input ).not.toHaveAttribute( 'aria-describedby' );
+			} );
+		} );
+	} );
+
 	describe( 'Focus behavior', () => {
 		it( 'should focus the first error in the form', async () => {
 			const user = userEvent.setup();

package/src/validated-form-controls/test/custom-select-control.tsx

@@ -0,0 +1,60 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedCustomSelectControl } from '../components';
+
+describe( 'ValidatedCustomSelectControl', () => {
+	const options = [
+		{ key: 'small', name: 'Small' },
+		{ key: 'large', name: 'Large' },
+	];
+
+	it( 'should preserve the built-in "Currently selected" description', async () => {
+		render(
+			<ValidatedCustomSelectControl
+				label="Font Size"
+				options={ options }
+				value={ options[ 0 ] }
+				onChange={ () => {} }
+			/>
+		);
+
+		await waitFor( () => {
+			expect(
+				screen.getByRole( 'combobox', { name: 'Font Size' } )
+			).toHaveAccessibleDescription( 'Currently selected: Small' );
+		} );
+	} );
+
+	it( 'should preserve the built-in description when validation is active', async () => {
+		const user = userEvent.setup();
+		render(
+			<form onSubmit={ ( e ) => e.preventDefault() }>
+				<ValidatedCustomSelectControl
+					label="Font Size"
+					options={ options }
+					value={ options[ 0 ] }
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const combobox = await waitFor( () => {
+			return screen.getByRole( 'combobox', {
+				name: /^Font Size/,
+			} );
+		} );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		// The validation error targets the hidden delegate <select>, not
+		// the interactive combobox. The combobox's built-in description
+		// should be unaffected.
+		await waitFor( () => {
+			expect( combobox ).toHaveAccessibleDescription(
+				'Currently selected: Small'
+			);
+		} );
+	} );
+} );

package/src/validated-form-controls/test/form-token-field.tsx

@@ -0,0 +1,52 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedFormTokenField } from '../components';
+
+describe( 'ValidatedFormTokenField', () => {
+	it( 'should preserve the built-in howto description', () => {
+		render(
+			<ValidatedFormTokenField
+				label="Tags"
+				value={ [] }
+				onChange={ () => {} }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', { name: 'Tags' } )
+		).toHaveAccessibleDescription(
+			expect.stringContaining( 'Separate with commas or the Enter key.' )
+		);
+	} );
+
+	it( 'should preserve the built-in howto description when validation is active', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedFormTokenField
+					label="Tags"
+					value={ [] }
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const input = screen.getByRole( 'combobox', { name: /^Tags/ } );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		// The validation error targets the hidden delegate input, not the
+		// interactive combobox. The combobox's built-in description should
+		// be unaffected.
+		await waitFor( () => {
+			expect(
+				screen.getByText( 'Constraints not satisfied' )
+			).toBeVisible();
+		} );
+		expect( input ).toHaveAccessibleDescription(
+			expect.stringContaining( 'Separate with commas or the Enter key.' )
+		);
+	} );
+} );

package/src/validated-form-controls/test/input-control.tsx

@@ -0,0 +1,42 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedInputControl } from '../components';
+
+describe( 'ValidatedInputControl', () => {
+	it( 'should preserve the help description', () => {
+		render(
+			<ValidatedInputControl label="URL" help="Enter a full URL." />
+		);
+
+		expect(
+			screen.getByRole( 'textbox', { name: 'URL' } )
+		).toHaveAccessibleDescription( 'Enter a full URL.' );
+	} );
+
+	it( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedInputControl
+					label="URL"
+					help="Enter a full URL."
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const input = screen.getByRole( 'textbox', { name: /^URL/ } );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		await waitFor( () => {
+			expect( input ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Constraints not satisfied' )
+			);
+		} );
+		expect( input ).toHaveAccessibleDescription(
+			expect.stringContaining( 'Enter a full URL.' )
+		);
+	} );
+} );