MediaEdit: Support custom validation

[ntsekouras]

What?

Part of: #72614

This PR adds support for custom validation in MediaEdit component. The code is very similar to the date control with custom handling because there are multiple interactive controls inside and we don't have a simple input control.

Since MediaEdit has various complex components without an input, I used a hidden input field and programmatically setCustomValidity based on the validity object (this is used for prevent form submissions).

This also means that in order for MediaEdit to display validation messages, the consumer should also pass the validity object in DataForm. Is this expected and/or reasonable @oandregal?

Testing Instructions

You can test it by updating the featured image field like this:

function validateRequired(
	item: BasePostWithEmbeddedFeaturedMedia,
	field: NormalizedField< BasePostWithEmbeddedFeaturedMedia >
): string | null {
	const value = field.getValue( { item } );
	if ( value === 6 ) {
		return 'This specific image is not allowed.';
	}
	return ! [ 0, undefined, '', null ].includes( value )
		? null
		: __( 'This field is required.' );
}
const featuredImageField: Field< BasePostWithEmbeddedFeaturedMedia > = {
	id: 'featured_media',
	type: 'media',
	label: __( 'Featured Image' ),
	Edit: MediaEdit,
	render: FeaturedImageView,
	setValue: ( { value } ) => ( {
		featured_media: value ?? 0,
	} ),
	enableSorting: false,
	filterBy: false,
	isValid: {
		custom: validateRequired,
	},
};

You should also update the post edit form to pass the validity object.

import { DataForm, useFormValidity } from '@wordpress/dataviews';

....

const data = ids.length === 1 ? record : multiEdits;
const { validity } = useFormValidity( data, fieldsWithDependency, form );

return (
	<VStack spacing={ 4 }>
		<PostCardPanel postType={ postType } postId={ ids } />
		{ hasFinishedResolution && (
			<DataForm
				data={ data }
				fields={ fieldsWithDependency }
				form={ form }
				onChange={ onChange }
				validity={ validity }
			/>
		) }
	</VStack>
);

Video with the snippets above applied.

Noting that in trunk we don't have a validation requirement for featured image field, so no validation message is being displayed.

Screen.Recording.2026-01-20.at.1.30.35.PM.mov

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ntsekouras <ntsekouras@git.wordpress.org>
Co-authored-by: oandregal <oandregal@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[oandregal]

This means the input will be invalid when:

• value is an empty array
• value is a scalar but falsy (undefined, null, empty, false, 0, NaN)

This logic is different from the type, that checks for null/undefined/empty. Shouldn't they be the same?

[ntsekouras]

You're not wrong about this and after thinking more I followed a different approach. MediaEdit fields can have different values and validation logic (array for multiple, 0 that implies empty for FeaturedImage etc..), so it makes more sense for any field that uses it and wants validation, to add a custom validation function. I'll update the PR's description with some test instructions.

The new approach is to have an input and programmatically setCustomValidity based on the validity object.

[github-actions]

Flaky tests detected in 9ff04ba.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/21165134775
📝 Reported issues:

• [Flaky Test] should show the original content after revert and page reload #68604 in /test/e2e/specs/site-editor/template-revert.spec.js

[oandregal]

This also means that in order for MediaEdit to display validation messages, the consumer should also pass the validity object in DataForm. Is this expected and/or reasonable

Yes, this is how validation works. Validation is intentionally designed as controlled state: see PR and discussion on alternative design. There were some challenges when it was not.

[oandregal]

Thanks for making media-edit support validation!