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

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

@@ -137,7 +137,6 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   user-select: none;
   width: 100%;
   z-index: 2;
-  color: var(--wp-components-color-foreground, #1e1e1e);
   height: 38px;
   aspect-ratio: 1;
   padding-left: 0;
@@ -157,12 +156,13 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   border: 0;
 }
 
-.emotion-12[disabled] {
+.emotion-12[disabled],
+.emotion-12[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-12:hover {
+.emotion-12:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 
@@ -211,7 +211,6 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   user-select: none;
   width: 100%;
   z-index: 2;
-  color: var(--wp-components-color-foreground, #1e1e1e);
   height: 38px;
   aspect-ratio: 1;
   padding-left: 0;
@@ -229,12 +228,13 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   border: 0;
 }
 
-.emotion-17[disabled] {
+.emotion-17[disabled],
+.emotion-17[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-17:hover {
+.emotion-17:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 
@@ -491,12 +491,13 @@ exports[`ToggleGroupControl controlled should render correctly with text options
   border: 0;
 }
 
-.emotion-12[disabled] {
+.emotion-12[disabled],
+.emotion-12[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-12:hover {
+.emotion-12:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 
@@ -726,7 +727,6 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   user-select: none;
   width: 100%;
   z-index: 2;
-  color: var(--wp-components-color-foreground, #1e1e1e);
   height: 38px;
   aspect-ratio: 1;
   padding-left: 0;
@@ -746,12 +746,13 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   border: 0;
 }
 
-.emotion-12[disabled] {
+.emotion-12[disabled],
+.emotion-12[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-12:hover {
+.emotion-12:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 
@@ -800,7 +801,6 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   user-select: none;
   width: 100%;
   z-index: 2;
-  color: var(--wp-components-color-foreground, #1e1e1e);
   height: 38px;
   aspect-ratio: 1;
   padding-left: 0;
@@ -818,12 +818,13 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   border: 0;
 }
 
-.emotion-17[disabled] {
+.emotion-17[disabled],
+.emotion-17[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-17:hover {
+.emotion-17:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 
@@ -1074,12 +1075,13 @@ exports[`ToggleGroupControl uncontrolled should render correctly with text optio
   border: 0;
 }
 
-.emotion-12[disabled] {
+.emotion-12[disabled],
+.emotion-12[aria-disabled='true'] {
   opacity: 0.4;
   cursor: default;
 }
 
-.emotion-12:hover {
+.emotion-12:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
   color: var(--wp-components-color-foreground, #1e1e1e);
 }
 

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

@@ -114,7 +114,7 @@ function ToggleGroupControlOptionBase(
 		ref: forwardedRef,
 	};
 
-	const labelRef = useRef< HTMLDivElement | null >( null );
+	const labelRef = useRef< HTMLDivElement >( null );
 	useLayoutEffect( () => {
 		if ( isPressed && labelRef.current ) {
 			toggleGroupControlContext.setSelectedElement( labelRef.current );

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

@@ -63,13 +63,14 @@ export const buttonView = ( {
 		border: 0;
 	}
 
-	&[disabled] {
+	&[disabled],
+	&[aria-disabled='true'] {
 		opacity: 0.4;
 		cursor: default;
 	}
 
-	&:hover {
-		color: ${ COLORS.theme.gray[ 900 ] };
+	&:hover:not( [disabled] ):not( [aria-disabled='true'] ) {
+		color: ${ COLORS.theme.foreground };
 	}
 
 	${ isDeselectable && deselectable }
@@ -83,8 +84,6 @@ const pressed = css`
 `;
 
 const deselectable = css`
-	color: ${ COLORS.theme.foreground };
-
 	&:focus {
 		outline: ${ CONFIG.borderWidthFocus } solid ${ COLORS.ui.borderFocus };
 		outline-offset: 2px;
@@ -112,7 +111,6 @@ const isIconStyles = ( {
 	};
 
 	return css`
-		color: ${ COLORS.theme.foreground };
 		height: ${ iconButtonSizes[ size ] };
 		aspect-ratio: 1;
 		padding-left: 0;

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

@@ -35,7 +35,7 @@ export type ToggleGroupControlOptionIconProps = Pick<
 	 * Icon displayed as the content of the option. Usually one of the icons from
 	 * the `@wordpress/icons` package, or a custom React `<svg>` icon.
 	 */
-	icon: JSX.Element;
+	icon: React.JSX.Element;
 	/**
 	 * The text to accessibly label the icon option. Will also be shown in a tooltip.
 	 */

package/src/tree-grid/roving-tab-index-item.tsx

@@ -14,7 +14,7 @@ export const RovingTabIndexItem = forwardRef(
 		{ children, as: Component, ...props }: RovingTabIndexItemProps,
 		forwardedRef: React.ForwardedRef< any >
 	) {
-		const localRef = useRef< any >();
+		const localRef = useRef< any >( null );
 		const ref = forwardedRef || localRef;
 		// @ts-expect-error - We actually want to throw an error if this is undefined.
 		const { lastFocusedElement, setLastFocusedElement } =

package/src/tree-grid/types.ts

@@ -61,7 +61,7 @@ export type RovingTabIndexItemProps = {
 	 * </TreeGridCell>
 	 * ```
 	 */
-	children?: ( props: RovingTabIndexItemPassThruProps ) => JSX.Element;
+	children?: ( props: RovingTabIndexItemPassThruProps ) => React.JSX.Element;
 	/**
 	 * If `children` is not a function, this component will be used instead.
 	 */

package/src/utils/element-rect.ts

@@ -139,7 +139,7 @@ export function useTrackElementOffsetRect(
 ) {
 	const [ indicatorPosition, setIndicatorPosition ] =
 		useState< ElementOffsetRect >( NULL_ELEMENT_OFFSET_RECT );
-	const intervalRef = useRef< ReturnType< typeof setInterval > >();
+	const intervalRef = useRef< ReturnType< typeof setInterval > >( undefined );
 
 	const measure = useEvent( () => {
 		// Check that the targetElement is still attached to the DOM, in case

package/src/utils/hooks/use-update-effect.js

@@ -8,8 +8,8 @@ import { useRef, useEffect } from '@wordpress/element';
  * Source:
  * https://github.com/ariakit/ariakit/blob/main/packages/ariakit-react-core/src/utils/hooks.ts
  *
- * @param {import('react').EffectCallback} effect
- * @param {import('react').DependencyList} deps
+ * @param {React.EffectCallback} effect
+ * @param {React.DependencyList} deps
  */
 function useUpdateEffect( effect, deps ) {
 	const mountedRef = useRef( false );

package/src/utils/rtl.js

@@ -51,9 +51,9 @@ function getConvertedKey( key ) {
 /**
  * An incredibly basic ltr -> rtl converter for style properties
  *
- * @param {import('react').CSSProperties} ltrStyles
+ * @param {React.CSSProperties} ltrStyles
  *
- * @return {import('react').CSSProperties} Converted ltr -> rtl styles
+ * @return {React.CSSProperties} Converted ltr -> rtl styles
  */
 export const convertLTRToRTL = ( ltrStyles = {} ) => {
 	return Object.fromEntries(
@@ -67,8 +67,8 @@ export const convertLTRToRTL = ( ltrStyles = {} ) => {
 /**
  * A higher-order function that create an incredibly basic ltr -> rtl style converter for CSS objects.
  *
- * @param {import('react').CSSProperties} ltrStyles   Ltr styles. Converts and renders from ltr -> rtl styles, if applicable.
- * @param {import('react').CSSProperties} [rtlStyles] Rtl styles. Renders if provided.
+ * @param {React.CSSProperties} ltrStyles   Ltr styles. Converts and renders from ltr -> rtl styles, if applicable.
+ * @param {React.CSSProperties} [rtlStyles] Rtl styles. Renders if provided.
  *
  * @return {() => import('@emotion/react').SerializedStyles} A function to output CSS styles for Emotion's renderer
  */

package/src/utils/use-responsive-value.ts

@@ -66,9 +66,5 @@ export function useResponsiveValue< T >(
 
 	const array = values || [];
 
-	/* eslint-disable jsdoc/no-undefined-types */
-	return /** @type {T[]} */ array[
-		/* eslint-enable jsdoc/no-undefined-types */
-		index >= array.length ? array.length - 1 : index
-	];
+	return array[ index >= array.length ? array.length - 1 : index ];
 }

package/src/v-stack/test/index.tsx

@@ -41,7 +41,7 @@ describe( 'props', () => {
 	} );
 
 	test( 'should not pass through invalid props to the `as` component', () => {
-		const AsComponent = ( props: JSX.IntrinsicElements[ 'div' ] ) => {
+		const AsComponent = ( props: React.JSX.IntrinsicElements[ 'div' ] ) => {
 			return <div { ...props } />;
 		};
 

package/src/validated-form-controls/components/stories/overview.story.tsx

@@ -149,7 +149,8 @@ export const AsyncValidation: StoryObj< typeof ValidatedInputControl > = {
 				>[ 'customValidity' ]
 			>( undefined );
 
-		const timeoutRef = useRef< ReturnType< typeof setTimeout > >();
+		const timeoutRef =
+			useRef< ReturnType< typeof setTimeout > >( undefined );
 
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 		const debouncedValidate = useCallback(

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();