Validated form controls: Separate validation state and message display state

packages/components/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+-   Validated form controls (private API): Removed `onValidate` prop (use `onChange` to set `customValidity` messages, or add conditionals directly inside the `customValidity` prop instead) ([#73559](https://github.com/WordPress/gutenberg/pull/73559)).
+
 ### Enhancements
 
 -   `Menu` and othr menu items: change default size to be 32px tall rather than 40px to improve menu density. ([#73429](https://github.com/WordPress/gutenberg/pull/73429)).
@@ -14,7 +18,7 @@
 
 ### Internal
 
-- `AlignmentMatrixControl`: Migrate styles from Emotion to a CSS module ([#73714](https://github.com/WordPress/gutenberg/pull/73714) and [#73757](https://github.com/WordPress/gutenberg/pull/73757)).
+-   `AlignmentMatrixControl`: Migrate styles from Emotion to a CSS module ([#73714](https://github.com/WordPress/gutenberg/pull/73714) and [#73757](https://github.com/WordPress/gutenberg/pull/73757)).
 
 ## 30.9.0 (2025-11-26)
 

packages/components/src/validated-form-controls/components/checkbox-control.tsx

@@ -10,37 +10,28 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import CheckboxControl from '../../checkbox-control';
-import type { CheckboxControlProps } from '../../checkbox-control/types';
-
-type Value = CheckboxControlProps[ 'checked' ];
 
 const UnforwardedValidatedCheckboxControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof CheckboxControl >,
 		'__nextHasNoMarginBottom'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
 	const validityTargetRef = useRef< HTMLDivElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.checked );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
@@ -50,10 +41,6 @@ const UnforwardedValidatedCheckboxControl = (
 		>
 			<CheckboxControl
 				__nextHasNoMarginBottom
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 				// TODO: Upstream limitation - CheckboxControl doesn't support uncontrolled mode, visually.
 				{ ...restProps }
 			/>

packages/components/src/validated-form-controls/components/combobox-control.tsx

@@ -10,28 +10,22 @@ import { forwardRef, useEffect, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import ComboboxControl from '../../combobox-control';
-import type { ComboboxControlProps } from '../../combobox-control/types';
-
-type Value = ComboboxControlProps[ 'value' ];
 
 const UnforwardedValidatedComboboxControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof ComboboxControl >,
 		'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.value );
 
 	// TODO: Upstream limitation - The `required` attribute is not passed down to the input,
 	// so we need to set it manually.
@@ -51,9 +45,6 @@ const UnforwardedValidatedComboboxControl = (
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
@@ -65,10 +56,6 @@ const UnforwardedValidatedComboboxControl = (
 				__nextHasNoMarginBottom
 				__next40pxDefaultSize
 				{ ...restProps }
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 			/>
 		</ControlWithError>
 	);

packages/components/src/validated-form-controls/components/custom-select-control.tsx

@@ -9,32 +9,21 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import CustomSelectControl from '../../custom-select-control';
-import type {
-	CustomSelectOption,
-	CustomSelectProps,
-} from '../../custom-select-control/types';
-
-type CustomSelectControlProps = CustomSelectProps< CustomSelectOption >;
-
-type Value = CustomSelectControlProps[ 'value' ];
 
 const UnforwardedValidatedCustomSelectControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof CustomSelectControl >,
 		'__next40pxDefaultSize'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) => {
 	const validityTargetRef = useRef< HTMLSelectElement >( null );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<div
@@ -44,20 +33,13 @@ const UnforwardedValidatedCustomSelectControl = (
 			<ControlWithError
 				required={ required }
 				markWhenOptional={ markWhenOptional }
-				onValidate={ () => {
-					return onValidate?.( valueRef.current );
-				} }
 				customValidity={ customValidity }
 				getValidityTarget={ () => validityTargetRef.current }
 			>
 				<CustomSelectControl
 					// TODO: Upstream limitation - Required isn't passed down correctly,
 					// so it needs to be set on a delegate element.
 					__next40pxDefaultSize
-					onChange={ ( value ) => {
-						valueRef.current = value.selectedItem;
-						onChange?.( value );
-					} }
 					{ ...restProps }
 				/>
 			</ControlWithError>

packages/components/src/validated-form-controls/components/form-token-field.tsx

@@ -9,27 +9,21 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import { FormTokenField } from '../../form-token-field';
-import type { FormTokenFieldProps } from '../../form-token-field/types';
-
-type Value = FormTokenFieldProps[ 'value' ];
 
 const UnforwardedValidatedFormTokenField = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof FormTokenField >,
 		'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
 	> &
-		ValidatedControlProps< FormTokenFieldProps[ 'value' ] >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) => {
 	const validityTargetRef = useRef< HTMLInputElement >( null );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<div
@@ -39,20 +33,13 @@ const UnforwardedValidatedFormTokenField = (
 			<ControlWithError
 				required={ required }
 				markWhenOptional={ markWhenOptional }
-				onValidate={ () => {
-					return onValidate?.( valueRef.current );
-				} }
 				customValidity={ customValidity }
 				getValidityTarget={ () => validityTargetRef.current }
 			>
 				<FormTokenField
 					__next40pxDefaultSize
 					__nextHasNoMarginBottom
 					{ ...restProps }
-					onChange={ ( value, ...args ) => {
-						valueRef.current = value;
-						onChange?.( value, ...args );
-					} }
 				/>
 			</ControlWithError>
 			<input
@@ -61,7 +48,7 @@ const UnforwardedValidatedFormTokenField = (
 				ref={ validityTargetRef }
 				required={ required }
 				value={
-					valueRef.current && valueRef.current.length > 0
+					restProps.value && restProps.value.length > 0
 						? 'hasvalue'
 						: ''
 				}

packages/components/src/validated-form-controls/components/input-control.tsx

@@ -10,46 +10,33 @@ import { useMergeRefs } from '@wordpress/compose';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import InputControl from '../../input-control';
-import type { InputControlProps } from '../../input-control/types';
-
-type Value = InputControlProps[ 'value' ];
 
 const UnforwardedValidatedInputControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof InputControl >,
 		'__next40pxDefaultSize'
 	> &
-		ValidatedControlProps< InputControlProps[ 'value' ] >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<InputControl
 				__next40pxDefaultSize
 				ref={ mergedRefs }
-				onChange={ ( value, ...args ) => {
-					valueRef.current = value;
-					onChange?.( value, ...args );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

packages/components/src/validated-form-controls/components/number-control.tsx

@@ -10,48 +10,33 @@ import { useMergeRefs } from '@wordpress/compose';
 import { ControlWithError } from '../control-with-error';
 import NumberControl from '../../number-control';
 import type { ValidatedControlProps } from './types';
-import type { NumberControlProps } from '../../number-control/types';
-
-type Value = NumberControlProps[ 'value' ];
 
 const UnforwardedValidatedNumberControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof NumberControl >,
 		'__next40pxDefaultSize'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<NumberControl
 				__next40pxDefaultSize
 				ref={ mergedRefs }
-				// TODO: Upstream limitation - When form is submitted when value is undefined, it will
-				// automatically set a clamped value (as defined by `min` attribute, so 0 by default).
-				onChange={ ( value, ...args ) => {
-					valueRef.current = value;
-					onChange?.( value, ...args );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

packages/components/src/validated-form-controls/components/radio-control.tsx

@@ -10,49 +10,33 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import RadioControl from '../../radio-control';
-import type { RadioControlProps } from '../../radio-control/types';
-
-type Value = RadioControlProps[ 'selected' ];
 
 const UnforwardedValidatedRadioControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
-	}: React.ComponentProps< typeof RadioControl > &
-		ValidatedControlProps< Value >,
+	}: React.ComponentProps< typeof RadioControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) => {
 	const validityTargetRef = useRef< HTMLDivElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.selected );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			// TODO: Upstream limitation - RadioControl does not accept a ref.
 			ref={ mergedRefs }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[type="radio"]'
 				)
 			}
 		>
-			<RadioControl
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
-				{ ...restProps }
-			/>
+			<RadioControl { ...restProps } />
 		</ControlWithError>
 	);
 };