@wordpress/components 32.2.1-next.v.202602191100.0 → 32.2.1

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.' )
+		);
+	} );
+} );

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

@@ -0,0 +1,44 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedNumberControl } from '../components';
+
+describe( 'ValidatedNumberControl', () => {
+	it( 'should preserve the help description', () => {
+		render(
+			<ValidatedNumberControl label="Quantity" help="Enter a quantity." />
+		);
+
+		expect(
+			screen.getByRole( 'spinbutton', { name: 'Quantity' } )
+		).toHaveAccessibleDescription( 'Enter a quantity.' );
+	} );
+
+	it( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedNumberControl
+					label="Quantity"
+					help="Enter a quantity."
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const input = screen.getByRole( 'spinbutton', {
+			name: /^Quantity/,
+		} );
+
+		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 quantity.' )
+		);
+	} );
+} );

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

@@ -0,0 +1,61 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedRadioControl } from '../components';
+
+describe( 'ValidatedRadioControl', () => {
+	const options = [
+		{ label: 'Small', value: 'small' },
+		{ label: 'Medium', value: 'medium' },
+		{ label: 'Large', value: 'large' },
+	];
+
+	it( 'should preserve the help description on the radio group', () => {
+		render(
+			<ValidatedRadioControl
+				label="Size"
+				help="Choose a size."
+				options={ options }
+				onChange={ () => {} }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'group', { name: 'Size' } )
+		).toHaveAccessibleDescription( 'Choose a size.' );
+	} );
+
+	it( 'should append the validation error to the first radio input', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedRadioControl
+					label="Size"
+					help="Choose a size."
+					options={ options }
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		// The validation error targets the first radio input (the validity
+		// target), while the help description stays on the group.
+		const firstRadio = screen.getByRole( 'radio', {
+			name: 'Small',
+		} );
+		await waitFor( () => {
+			expect( firstRadio ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Constraints not satisfied' )
+			);
+		} );
+
+		expect(
+			screen.getByRole( 'group', { name: /^Size/ } )
+		).toHaveAccessibleDescription(
+			expect.stringContaining( 'Choose a size.' )
+		);
+	} );
+} );

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

@@ -0,0 +1,73 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState, useRef } from '@wordpress/element';
+import { ValidatedRangeControl } from '../components';
+
+describe( 'ValidatedRangeControl', () => {
+	it( 'should preserve the help description', () => {
+		render(
+			<ValidatedRangeControl label="Opacity" help="Set the opacity." />
+		);
+
+		expect(
+			screen.getByRole( 'slider', { name: 'Opacity' } )
+		).toHaveAccessibleDescription( 'Set the opacity.' );
+	} );
+
+	// Range inputs always have a value, so `required` never fails constraint
+	// validation. Use `customValidity` to trigger the validation error.
+	it( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+
+		function TestComponent() {
+			const [ customValidity, setCustomValidity ] =
+				useState<
+					React.ComponentProps<
+						typeof ValidatedRangeControl
+					>[ 'customValidity' ]
+				>( undefined );
+			const ref = useRef< HTMLInputElement >( null );
+
+			return (
+				<>
+					<ValidatedRangeControl
+						ref={ ref }
+						label="Opacity"
+						help="Set the opacity."
+						customValidity={ customValidity }
+					/>
+					<button
+						type="button"
+						onClick={ () => {
+							setCustomValidity( {
+								type: 'invalid',
+								message: 'Value out of range.',
+							} );
+							requestAnimationFrame(
+								() => ref.current?.reportValidity()
+							);
+						} }
+					>
+						Validate
+					</button>
+				</>
+			);
+		}
+
+		render( <TestComponent /> );
+
+		const slider = screen.getByRole( 'slider', { name: 'Opacity' } );
+		expect( slider ).toHaveAccessibleDescription( 'Set the opacity.' );
+
+		await user.click( screen.getByRole( 'button', { name: 'Validate' } ) );
+
+		await waitFor( () => {
+			expect( slider ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Value out of range.' )
+			);
+		} );
+		expect( slider ).toHaveAccessibleDescription(
+			expect.stringContaining( 'Set the opacity.' )
+		);
+	} );
+} );

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

@@ -0,0 +1,57 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ValidatedSelectControl } from '../components';
+
+describe( 'ValidatedSelectControl', () => {
+	const options = [
+		{ label: 'Select a color...', value: '' },
+		{ label: 'Red', value: 'red' },
+		{ label: 'Blue', value: 'blue' },
+	];
+
+	it( 'should preserve the help description', () => {
+		render(
+			<ValidatedSelectControl
+				label="Color"
+				help="Pick a color."
+				options={ options }
+				onChange={ () => {} }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', { name: 'Color' } )
+		).toHaveAccessibleDescription( 'Pick a color.' );
+	} );
+
+	it( 'should append the validation error alongside the help description', async () => {
+		const user = userEvent.setup();
+		render(
+			<form>
+				<ValidatedSelectControl
+					label="Color"
+					help="Pick a color."
+					options={ options }
+					onChange={ () => {} }
+					required
+				/>
+				<button type="submit">Submit</button>
+			</form>
+		);
+
+		const select = screen.getByRole( 'combobox', {
+			name: /^Color/,
+		} );
+
+		await user.click( screen.getByRole( 'button', { name: 'Submit' } ) );
+
+		await waitFor( () => {
+			expect( select ).toHaveAccessibleDescription(
+				expect.stringContaining( 'Constraints not satisfied' )
+			);
+		} );
+		expect( select ).toHaveAccessibleDescription(
+			expect.stringContaining( 'Pick a color.' )
+		);
+	} );
+} );

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

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